module_builder 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e7a6ca0b59291dc18d4c0dc812248ec345b9ea41
+  data.tar.gz: b736892bcd79e3e21dc39f207187314e1410f497
+SHA512:
+  metadata.gz: 448d824a8ac9754dd25df4fee94e108757aa70073a198dc28906f46ac4452f8ff1935524051608775384570a4ecad583b26b32f45726a99e852cdd135b1b2911
+  data.tar.gz: 495736ff1c2209579e8bfbd6e8ebf51661cb043505f142d46fa409532c5a9f4ec902fa1dff33fb21546f6806b5d65b3f431c5b7090a7c484be4a95fb89a6823a

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Change Log
+
+All notable changes to this project will be documented in this file. This
+project adheres to [Semantic Versioning 2.0.0][semver]. Any violations of this
+scheme are considered to be bugs.
+
+[semver]: http://semver.org/spec/v2.0.0.html
+
+## [0.1.0] - 2015-11-21
+
+### Added
+
+- Stateless inclusions via the `Builder#inclusions` extension method.
+- Stateless extension via the `Builder#extensions` extension method.
+- Defined hooks via the `Builder#hooks` extension method.
+- Stateful building via passing state into the Builder constructor and using
+  the resulting state in a defined hook.
+- Buildable module to mix into modules that you want to be able to build.
+- Default state via the `Builder#defaults` extension method.
+- Including a `Buildable` module includes the default built version in the
+  descendant class or module.
+
+[0.1.0]: https://github.com/michaelherold/module_builder/tree/v0.1.0

data/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Michael Herold
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,289 @@
+# ModuleBuilder
+
+[![Build Status](https://travis-ci.org/michaelherold/module_builder.svg)][travis]
+[![Code Climate](https://codeclimate.com/github/michaelherold/module_builder/badges/gpa.svg)][codeclimate]
+[![Inline docs](http://inch-ci.org/github/michaelherold/module_builder.svg?branch=master)][inch]
+
+[codeclimate]: https://codeclimate.com/github/michaelherold/module_builder
+[inch]: http://inch-ci.org/github/michaelherold/module_builder
+[travis]: https://travis-ci.org/michaelherold/module_builder
+
+ModuleBuilder gives you the ability to create modules that are customizable for
+different situations. Are you creating a module that has an adapter, but don't
+want to expose a setter on the including class because it's not a public API?
+ModuleBuilder can help with that! Do you have two implementations of some
+behavior that have different tradeoffs? Do you want to offer both through one
+easy-to-use syntax? ModuleBuilder can do that too!
+
+Come see what ModuleBuilder will help you with today!
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "module_builder"
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install module_builder
+
+## Usage
+
+ModuleBuilder revolves around the concept of Builders that are responsible for
+building modules based on your specification. For convenience, there is a
+`Buildable` module that you can mix in to give your module building
+superpowers.
+
+You configure Builders through two channels: class-level configuration and
+instance-level state. There are three types of class-level configuration:
+stateless inclusions, stateless extensions, and defined hooks.
+
+Stateless methods do not give much more power than just using a standard set of
+`include`s and `extend`s. However, they help you organize your code in an
+easily extensible fashion.
+
+You can use instance-level state within defined hooks to customize the behavior
+of the built module. If you need to conditionally define a method based on the
+configuration, you want to look here.
+
+### Stateless Inclusions
+
+The builder simply `include`s stateless inclusions into the built module. There
+are no customization hooks here, just a single place to specify all the modules
+you want to `include` in your built module.
+
+```ruby
+class StatelessInclusionBuilder < ModuleBuilder::Builder
+  def inclusions
+    [Comparable, Enumerable]
+  end
+end
+
+StatelessInclusionBuilder.new.module.ancestors
+#=> [#<Module>, Enumerable, Comparable]
+```
+
+### Stateless Extensions
+
+The builder adds all stateless extensions into the `Module#extended` hook of
+the built module so they are extended onto anything that extends the built
+module.
+
+```ruby
+module Quack
+  def quack
+    "quack"
+  end
+end
+
+class QuackingBuilder < ModuleBuilder::Builder
+  def extensions
+    [Quack]
+  end
+end
+
+class Duck
+  extend QuackingBuilder.new.module
+end
+
+Duck.quack #=> "quack"
+```
+
+### Defined Hooks
+
+Defined hooks are where you can do the heavy customization when building a
+module. They are arbitrary methods that the builder invokes during its
+initialization. Add any behavior that you want to make customizable via the
+state that you give to the builder as a defined hook.
+
+```ruby
+module Walk
+  def walk
+    "step, step, step"
+  end
+end
+
+class WalkingBuilder < ModuleBuilder::Builder
+  def hooks
+    [:rename_walk]
+  end
+
+  def inclusions
+    [Walk]
+  end
+
+  private
+
+  def rename_walk
+    return unless @walk_method
+
+    @module.__send__(:alias_method, @walk_method, :walk)
+    @module.__send__(:undef_method, :walk)
+  end
+end
+
+class Duck
+  include WalkingBuilder.new(:walk_method => :waddle).module
+end
+
+Duck.new.waddle  #=> "step, step, step"
+Duck.new.walk    #=> NoMethodError
+```
+
+### Buildable Module
+
+Explicitly instantiating a Builder and accessing the module that it built is
+clunky. To gain easy access to a consistent syntax for your module, you can
+include the `Buildable` module and specify the builder you want to use when
+building your module.
+
+```ruby
+class MyBuilder < ModuleBuilder::Builder
+end
+
+module BuildableExample
+  include ModuleBuilder::Buildable
+
+  builder MyBuilder
+end
+
+module IncludingModule
+  include BuildableExample.new(:state => "value")
+end
+```
+
+`Buildable` defaults to using a `Builder` defined within the current module.
+You can rely on that instead of using the DSL for specifying the builder.
+
+```ruby
+module OtherBuildableExample
+  include ModuleBuilder::Buildable
+
+  class Builder < ModuleBuilder::Builder
+  end
+end
+
+module OtherIncludingModule
+  include OtherBuildableExample.new(:my_config_value => "awesome")
+end
+```
+
+When a `Buildable` module is included without the use of its constructor, the
+default version of the module is included in the descendant class or module.
+
+```ruby
+module BuildableExample
+  include ModuleBuilder::Buildable
+
+  class Builder < ModuleBuilder::Builder
+  end
+end
+
+module IncludingModule
+  include BuildableExample
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+When writing code, you can use the helper application [Guard][guard] to
+automatically run tests and coverage tools whenever you modify and save a file.
+This helps to eliminate the tedium of running tests manually and reduces the
+change that you will accidentally forget to run the tests. To use Guard, run
+`bundle exec guard`.
+
+Before committing code, run `rake` to check that the code conforms to the style
+guidelines of the project, that all of the tests are green (if you're writing a
+feature; if you're only submitting a failing test, then it does not have to
+pass!), and that the changes are sufficiently documented.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and tags, and push the `.gem` file to [rubygems.org][rubygems].
+
+[guard]: http://guardgem.org
+[rubygems]: https://rubygems.org
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/michaelherold/module_builder. This project is intended to be
+a safe, welcoming space for collaboration, and contributors are expected to
+adhere to the [Contributor Covenant][covenant] code of conduct.
+
+[covenant]: http://contributor-covenant.org
+
+## Supported Ruby Versions
+
+This library aims to support and is [tested against][travis] the following Ruby
+versions:
+
+* Ruby 1.9.3
+* Ruby 2.0
+* Ruby 2.1
+* Ruby 2.2
+* JRuby 1.7 (in Ruby 1.9 mode)
+* JRuby 9.0
+
+If something doesn't work on one of these versions, it's a bug.
+
+This library may inadvertently work (or seem to work) on other Ruby versions,
+however support will only be provided for the versions listed above.
+
+If you would like this library to support another Ruby version or
+implementation, you may volunteer to be a maintainer. Being a maintainer
+entails making sure all tests run and pass on that implementation. When
+something breaks on your implementation, you will be responsible for providing
+patches in a timely fashion. If critical issues for a particular implementation
+exist at the time of a major release, support for that Ruby version may be
+dropped.
+
+## Versioning
+
+This library aims to adhere to [Semantic Versioning 2.0.0][semver]. Violations
+of this scheme should be reported as bugs. Specifically, if a minor or patch
+version is released that breaks backward compatibility, that version should be
+immediately yanked and/or a new version should be immediately released that
+restores compatibility. Breaking changes to the public API will only be
+introduced with new major versions. As a result of this policy, you can (and
+should) specify a dependency on this gem using the [Pessimistic Version
+Constraint][pessimistic] with two digits of precision. For example:
+
+    spec.add_dependency "module_builder", "~> 0.1"
+
+[pessimistic]: http://guides.rubygems.org/patterns/#pessimistic-version-constraint
+[semver]: http://semver.org/spec/v2.0.0.html
+
+## Credits
+
+The original implementation of this library was based on the [Builder][builder]
+within the [virtus] gem by Piotr Solnica, which I used for inspiration. Pieces
+of it live on, but the current product expands on the original.
+
+The idea for the library came from [a conversation][conversation] about the
+best way to configure a module once it is included in a class. [Grégory
+Horion][gregory]'s comment lead me down the path of using `Module.new` as the
+base for this library.
+
+[builder]: https://github.com/solnic/virtus/blob/3248a465643b86d7fcb0c16fe6937293adbd1055/lib/virtus/builder.rb
+[conversation]: https://github.com/intridea/hashie/pull/262
+[gregory]: http://gregory.io
+[piotr]: http://solnic.eu
+[virtus]: https://github.com/solnic/virtus
+
+## License
+
+The gem is available as open source under the terms of the [MIT License][license].
+
+[license]: http://opensource.org/licenses/MIT.

data/Rakefile

@@ -0,0 +1,29 @@
+require "bundler"
+Bundler.setup
+Bundler::GemHelper.install_tasks
+
+require "inch/rake"
+Inch::Rake::Suggest.new(:inch)
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new(:rubocop)
+
+require "yard/rake/yardoc_task"
+YARD::Rake::YardocTask.new(:yard)
+
+task :mutant do
+  command = [
+    "bundle exec mutant",
+    "--include lib",
+    "--require module_builder",
+    "--use rspec",
+    "ModuleBuilder*",
+  ].join(" ")
+
+  system command
+end
+
+task :default => [:spec, :rubocop, :yard, :inch]

data/lib/module_builder.rb

@@ -0,0 +1,4 @@
+require "module_builder/error"
+require "module_builder/builder"
+require "module_builder/buildable"
+require "module_builder/version"

data/lib/module_builder/buildable.rb

@@ -0,0 +1,113 @@
+module ModuleBuilder
+  # Gives a module the ability to be customized via a {ModuleBuilder::Builder}
+  # in a class-like manner via a {::new} method.
+  module Buildable
+    # Extends the {ClassMethods} module onto any descendent.
+    #
+    # @param [Module] descendent the descendent module.
+    # @return [void]
+    def self.included(descendent)
+      descendent.extend(ClassMethods)
+    end
+
+    # Gives a module that mixes in Buildable a small DSL for specifying the
+    # class to use when building the module and the ability to easily build a
+    # new copy of the module using a given state.
+    module ClassMethods
+      # Sets and accesses the builder class for a buildable module.
+      #
+      # @example
+      #   class MyBuilder < ModuleBuilder::Builder
+      #   end
+      #
+      #   module MyBuiltModule
+      #     include ModuleBuilder::Buildable
+      #
+      #     builder MyBuilder
+      #   end
+      #
+      # @note When used as a class method, it declaratively sets the builder
+      #   class. When used without a parameter, it uses the `:not_set` symbol
+      #   as a marker to set itself into reader mode.
+      #
+      # @param [Class] builder_class the class to instantiate when building the
+      #   module.
+      # @raise [ModuleBuilder::UnspecifiedBuilder] if the builder is not found.
+      # @return [Class] the builder class.
+      def builder(builder_class = :not_set)
+        if builder_class.equal?(:not_set)
+          builder_or_fail
+        else
+          @builder = builder_class
+        end
+      end
+
+      # Includes the default version of the built module when included without
+      # a constructor.
+      #
+      # @example
+      #   module MyBuildableModule
+      #     include ModuleBuilder::Buildable
+      #
+      #     class Builder < ModuleBuilder::Builder
+      #     end
+      #   end
+      #
+      #   class MyUncustomizedClass
+      #     include MyBuildableModule
+      #   end
+      #
+      # @param [Class, Module] descendant the including class or module.
+      # @return [void]
+      def included(descendant)
+        descendant.__send__(:include, new)
+      end
+
+      # Builds a module with the configured builder class using the given
+      # state.
+      #
+      # @example
+      #   module MyBuildableModule
+      #     include ModuleBuilder::Buildable
+      #
+      #     class Builder < ModuleBuilder::Builder
+      #     end
+      #   end
+      #
+      #   class MyClass
+      #     include MyBuildableModule.new(:example => "value")
+      #   end
+      #
+      # @param [Hash] state the state to use when configuring the builder.
+      # @return [Module] the newly built module.
+      def new(state = {})
+        builder.new(state).module
+      end
+
+      private
+
+      # Fetches the configured or default builder class for the module.
+      #
+      # @raise [ModuleBuilder::UnspecifiedBuilder] if the builder is not found.
+      # @return [Class] the builder class.
+      def builder_or_fail
+        if @builder
+          @builder
+        else
+          default_builder
+        end
+      end
+
+      # Fetches the default builder for the module.
+      #
+      # @raise [ModuleBuilder::UnspecifiedBuilder] if there is no default
+      #   Builder within the module.
+      # @return [Class] the default builder class.
+      def default_builder
+        const_get("Builder")
+      rescue NameError
+        raise UnspecifiedBuilder
+      end
+    end
+  end
+end

data/lib/module_builder/builder.rb

@@ -0,0 +1,130 @@
+module ModuleBuilder
+  # Builds a module based on instance-level state and class-level configuration.
+  #
+  # This class is intended to be subclassed, not used as-is. There are several
+  # methods to override in order to give the builder the behavior you want. You
+  # can also define setup methods that are specified in the {Builder#hooks}
+  # array for arbitrary setup based on the state passed into the builder's
+  # constructor.
+  class Builder
+    # The module built by the builder.
+    #
+    # @!attribute [r] module
+    #   @return [Module] the Module built by the builder
+    attr_reader :module
+
+    # Creates a new module builder that uses the specified base module as a
+    # foundation for its built module and sets any other specified key/value
+    # pairs as instance variables on the builder.
+    #
+    # @example
+    #   ModuleBuilder::Builder.new(base: Module.new)
+    #
+    # @param [Hash] state the state to use for defined hooks.
+    # @option state [Module] :base (Module.new) the module to use as a base on
+    #   which to build.
+    def initialize(state = {})
+      state = [builder_defaults, defaults, state].reduce(&:merge)
+      @module = state.delete(:base)
+
+      state.each_pair do |attr, value|
+        instance_variable_set("@#{attr}", value)
+      end
+
+      add_extended_hook
+      add_inclusions
+      add_defined_hooks
+    end
+
+    # The defaults for any state values that require them.
+    #
+    # @note This can be overridden in a subclass with any default values for
+    #   state variables that are needed in defined hooks.
+    #
+    # @return [Hash] the default state for defined hooks.
+    def defaults
+      {}
+    end
+
+    # Lists the modules to be added into the Module#extended hook
+    # of the built module.
+    #
+    # @note This can be overridden in a subclass with any modules that
+    #   should be extended onto modules that extend the built module.
+    #
+    # @return [Array<Module>] the modules to be extended onto any
+    #   modules that extend the built module.
+    def extensions
+      []
+    end
+
+    # Lists the methods that should be called when building a module.
+    #
+    # @note This can be overridden in a subclass with any methods that
+    #   should be called to build the built module.
+    #
+    # @return [Array<Symbol>] the methods to call when building the
+    #   module.
+    def hooks
+      []
+    end
+
+    # Lists the modules to be included into the built module.
+    #
+    # @note This can be overridden in a subclass to automatically
+    #   include modules in the built module.
+    #
+    # @return [Array<Module>] the modules to be included into the built
+    #   module.
+    def inclusions
+      []
+    end
+
+    private
+
+    # Performs every method listed in the builder's {#hooks}.
+    #
+    # @return [void]
+    def add_defined_hooks
+      hooks.each { |hook| __send__(hook) }
+    end
+
+    # Adds the modules listed by the builder's {#extensions} to the
+    # Module#extended hook, for extension onto any modules that
+    # extend the built module
+    #
+    # @return [void]
+    def add_extended_hook
+      within_context do |context|
+        @module.define_singleton_method :extended do |object|
+          context.extensions.each { |extension| object.extend(extension) }
+        end
+      end
+    end
+
+    # Includes the modules listed by the builder's {#inclusions} in the
+    # built module.
+    #
+    # @return [void]
+    def add_inclusions
+      inclusions.each { |mod| @module.__send__(:include, mod) }
+    end
+
+    # Defines the basic defaults that every builder needs.
+    #
+    # @return [Hash] the defaults that every builder needs.
+    def builder_defaults
+      {:base => Module.new}
+    end
+
+    # Gives access to the builder's context when dynamically defining
+    # hooks.
+    #
+    # @api private
+    #
+    # @return [void]
+    def within_context
+      yield self
+    end
+  end
+end

data/lib/module_builder/error.rb

@@ -0,0 +1,8 @@
+module ModuleBuilder
+  # Represents any error that is expected to be raised by {ModuleBuilder}.
+  class Error < StandardError; end
+
+  # Raised when a {ModuleBuilder::Buildable} module cannot find the
+  # {ModuleBuilder::Builder} to use when building itself.
+  class UnspecifiedBuilder < Error; end
+end

data/lib/module_builder/version.rb

@@ -0,0 +1,5 @@
+# :nodoc:
+module ModuleBuilder
+  # :nodoc:
+  VERSION = "0.1.0".freeze
+end

data/module_builder.gemspec

@@ -0,0 +1,22 @@
+# coding: utf-8
+
+require File.expand_path("../lib/module_builder/version", __FILE__)
+
+Gem::Specification.new do |spec|
+  spec.name          = "module_builder"
+  spec.version       = ModuleBuilder::VERSION.dup
+  spec.authors       = ["Michael Herold"]
+  spec.email         = ["michael.j.herold@gmail.com"]
+
+  spec.summary       = "Dynamically build customized modules"
+  spec.description   = "Dynamically build customized modules"
+  spec.homepage      = "https://github.com/michaelherold/module_builder"
+  spec.license       = "MIT"
+
+  spec.files = %w(CHANGELOG.md LICENSE.md README.md Rakefile)
+  spec.files += %w(module_builder.gemspec)
+  spec.files += Dir["lib/**/*.rb"]
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: module_builder
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Michael Herold
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-11-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+description: Dynamically build customized modules
+email:
+- michael.j.herold@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- Rakefile
+- lib/module_builder.rb
+- lib/module_builder/buildable.rb
+- lib/module_builder/builder.rb
+- lib/module_builder/error.rb
+- lib/module_builder/version.rb
+- module_builder.gemspec
+homepage: https://github.com/michaelherold/module_builder
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: Dynamically build customized modules
+test_files: []
+has_rdoc: