toolchain 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 988af450afb20a81dae7333ff7ded62a2fc6ca52
+  data.tar.gz: f0cecb5a9bfe8ec82cbadab21019f4267f8ae5e5
+SHA512:
+  metadata.gz: 3f707cd58b11de78ce0166874d9712d6197e572dcd6919787355a56cf2821b52127b0748732d2207f238721d45a25bf28c1fc8dc7ffc5d56255682accc1fe6d0
+  data.tar.gz: 62c64f506a01f32f050f17b4418e1828a13e8c8f9f0dae62b324b3af615e5cc64f469f69af33fd2c7decb651e6fd48c4fd8eab4f579beaf69e5ab4738e6479f6

data/.gitignore

@@ -0,0 +1,5 @@
+.DS_Store
+.yardoc
+/doc
+/coverage
+/pkg

data/.rspec

@@ -0,0 +1 @@
+--color --format documentation

data/Gemfile

@@ -0,0 +1,10 @@
+source "https://rubygems.org"
+
+gem "rake"
+
+group :test do
+  gem "yard"
+  gem "rspec"
+  gem "mocha"
+  gem "simplecov"
+end

data/Gemfile.lock

@@ -0,0 +1,34 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.2.5)
+    docile (1.1.3)
+    metaclass (0.0.4)
+    mocha (1.0.0)
+      metaclass (~> 0.0.1)
+    multi_json (1.9.0)
+    rake (10.1.1)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.8)
+    rspec-expectations (2.14.5)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.6)
+    simplecov (0.8.2)
+      docile (~> 1.1.0)
+      multi_json
+      simplecov-html (~> 0.8.0)
+    simplecov-html (0.8.0)
+    yard (0.8.7.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  mocha
+  rake
+  rspec
+  simplecov
+  yard

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) Machinery ( http://machinery.io )
+
+MIT License
+
+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,254 @@
+# Toolchain
+
+Collection of Ruby light-weight modules that enhance plain Ruby classes with zero runtime dependencies.
+
+##### Available modules
+
+* Attributes
+  * For defining rich attributes without a data store mapper like ActiveRecord
+  * Useful for applying principles such as the Single Responsibility Principe (SRP)
+* Validations
+  * Inspired by `ActiveModel::Validations`
+  * Supports nested validations for Hash data types
+  * Useful for applying principles such as the Single Responsibility Principe (SRP)
+  * Lightweight (~250 LOC) instead of `ActiveModel::Validations` (~1600 LOC)
+    * Note: This isn't a clone. Don't expect all of the features in `ActiveModel::Validations` to be available here. Part of the public api behaves in a similar fashion, there are however also a bunch of subtle differences.
+
+## Installation
+
+In `Gemfile`:
+
+```rb
+gem "toolchain"
+```
+
+Or, if you wish to only include certain modules:
+
+In `Gemfile`:
+
+```rb
+gem "toolchain", require: false
+```
+
+Then from anywhere in your program/app:
+
+```rb
+require "toolchain/attributes"
+require "toolchain/validations"
+```
+
+## Modules
+
+Below follows a list of modules.
+
+### Toolchain::Attributes
+
+The `Toolchain::Attributes` module provides your class with the `attribute` class method which you can use to define rich attributes. Think of it as `attr_accessor` but with type-definitions, optional defaults and a few convenience methods.
+
+```rb
+require "toolchain/attributes"
+
+class Person
+  include Toolchain::Attributes
+
+  attribute :name, String
+  attribute :cash, Integer
+  attribute :birthdate, DateTime
+  attribute :pocket, Array
+  attribute :misc, Hash
+  attribute :winning, Boolean, true
+end
+```
+
+##### Defined attributes (keys)
+
+You can get a list of defined attributes usind the `Person.keys` method.
+
+##### All attributes/values as a Hash
+
+You can access a Hash of attributes by calling the `person.attributes` instance method. By default this Hash returns all attributes with Symbol keys (including nested Hashes stored in Hash-type attributes).
+
+Hash-type attributes automatically convert String-type keys to Symbol-type keys when setting a new Hash.
+
+##### (Global) Configuration
+
+You can configure whether you want to have all your attribute keys as String- or Symbol type like so:
+
+```rb
+Toolchain::Attributes::Configuration.configure do |config|
+  config.hash_transformation = :stringify_keys # defaults to :symbolize_keys
+end
+```
+
+##### Mass-assignment
+
+You can mass-assign attributes using the `person.attributes` instance method. Note that any attributes you mass-assign that you haven't defined on the model are simply ignored and will not be set. Defined attributes automatically act as a whitelist for what can and cannot be mass-assigned.
+
+## Toolchain::Validations
+
+The `Toolchain::Validations` module provides your class with the `validates` and `validate` class methods which you can use to validate attributes. Note that this **DOES NOT** require `Toolchain::Attributes`, any instance method that returns a value can be validated.
+
+```rb
+require "toolchain/validations"
+
+class Person
+  include Toolchain::Validations
+
+  validates :name, presence: true
+  validates :email, email: { message: "isn't valid" }
+  validate :domain_validation
+
+  attr_accessor :name
+  attr_accessor :domain
+
+  def email; @email end
+  def email=(value); @email = value end
+
+  private
+
+  def domain_validation
+    if true # host validation logic here
+      errors.add(:domain, "couldn't connect")
+    end
+  end
+end
+```
+
+##### Nested Validations
+
+While `Toolchain::Validations` mirrors `ActiveModel::Validations` in most cases for the sake of consistency, there is an important diference when defining a validation using the `validates` method. In `Toolchain::Validation`, this creates a nested (Hash) validation:
+
+```rb
+require "toolchain/validations"
+
+class Person
+  include Toolchain::Attributes # optional
+  include Toolchain::Validations
+
+  attribute :info, Hash, {}
+  validates :info, :phone, presence: true
+end
+
+Person.new.tap do |person|
+  person.validate
+  person.errors[:info][:phone] # => ["can't be blank"]
+end
+```
+
+This feature isn't limited to single-level validation. You can have an infinitely deep nested Hash and validate each known attribute on it and it'll properly map the attributes/errors 1:1.
+
+This is useful when you keep a Hash of serialized data in a database, but you still want a hassle-free way of validating it's attributes that doesn't require you to create custom validators and re-invent the wheel just for nested attributes.
+
+##### Class-level Validators
+
+Similar to `ActiveModel::Validations` you can create your own class-level validations.
+
+```rb
+require "toolchain/validations"
+
+class Person
+  include Toolchain::Attributes # optional
+  include Toolchain::Validations
+
+  attribute :name, String
+  attribute :info, Hash, {}
+
+  validate :name_validation
+  validate :info_phone_validation
+
+  private
+
+  def name_validation
+    if true # name validation logic here
+      errors.add(:name, "is invalid")
+    end
+  end
+
+  def info_validation
+    if true # info[:phone] validation logic here
+      errors.add(:info, :phone, "not a number")
+    end
+  end
+end
+
+Person.new.tap do |person|
+  person.validate
+  person.errors[:info][:phone] # => ["can't be blank"]
+end
+```
+
+##### Custom (re-usable) Validators
+
+To define a validator, simply create and load a file like this:
+
+```rb
+module Toolchain::Validations::Validators
+  class MyValidator < Base
+
+    def validate
+      errors.add(key_path, message || "is invalid") if invalid?
+    end
+
+    private
+
+    def invalid?
+      # logic that determines that this value is invalid
+      #
+      # list of instance methods to work with:
+      #
+      # - object
+      # - errors
+      # - key_path
+      # - data
+      # - message
+    end
+  end
+end
+```
+
+###### object
+
+A reference to the object that contains the attribute which is being validated.
+
+###### errors
+
+A reference to the errors object on the `object`. Write potential validation errors to it.
+
+###### key_path
+
+An array of one or more keys. Single key means it's a root-level attribute validation. If this includes two or more keys, it means it's a nested validation on a Hash-type attribute.
+
+You generally don't need to worry about this. Just pass it in to `errors.add`'s first argument and it'll take care of properly assigning the error message at the right level.
+
+###### data
+
+This contains the options data that was passed in to the `validates` method.
+
+For example:
+
+```rb
+validates :cash, format: {
+  with: /^\d+$/,
+  message: "not a valid cash format"
+}
+
+data[:with] # /^\d+$/
+data[:message] # "not a valid cash format"
+```
+
+This can optionally be used in your validations.
+
+###### message
+
+If `data[:message]` is set (see `data` example), the `message` method will be contain it. Else, `message` will return `nil`, in which case you'll to use a default error message.
+
+
+
+## Contributing
+
+1. Fork it ( http://github.com/<my-github-username>/toolchain/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/toolchain.rb

@@ -0,0 +1,2 @@
+require_relative "toolchain/attributes"
+require_relative "toolchain/validations"

data/lib/toolchain/attributes.rb

@@ -0,0 +1,154 @@
+require_relative "version"
+require_relative "attributes/ext/boolean"
+
+module Toolchain::Attributes
+  require_relative "attributes/configuration"
+  require_relative "attributes/errors"
+  require_relative "attributes/helpers"
+
+  module ClassMethods
+
+    # @return [Array<Symbol>] all defined attributes.
+    #
+    def keys
+      @keys ||= []
+    end
+
+    # Defines an attribute on the Class.
+    #
+    # @example
+    #   class Company
+    #     attribute :name, String, "Unnamed"
+    #     attribute :email, String
+    #   end
+    #
+    # @param key [Symbol, String]
+    # @param type [Class]
+    # @param default [Object]
+    #
+    def attribute(key, type, default = nil)
+      type = [TrueClass, FalseClass] if type == Boolean
+
+      if Helpers.invalid_value?(default, type)
+        raise Errors::TypeMismatch,
+          "expected #{self.name}##{key} to have default value " +
+          "of #{type} type, but received #{default.class} (#{default})."
+      end
+
+      keys.push(key.to_sym)
+
+      define_method(key) do
+        value = instance_variable_get("@#{key}")
+
+        if value.nil?
+          new_value =
+            begin
+              if default.kind_of?(Proc)
+                default.call
+              else
+                default.dup
+              end
+            rescue TypeError
+              default
+            end
+
+          send("#{key}=", new_value)
+        else
+          value
+        end
+      end
+
+      define_method("#{key}=") do |value|
+        if value.kind_of?(String) && type.respond_to?(:parse)
+          value = type.parse(value)
+        end
+
+        if type == [TrueClass, FalseClass] && [0, "0"].include?(value)
+          value = false
+        end
+
+        if type == [TrueClass, FalseClass] && [1, "1"].include?(value)
+          value = true
+        end
+
+        if Helpers.invalid_value?(value, type)
+          raise Errors::TypeMismatch,
+            "#{self.class}##{key} expected #{type} type, " +
+            "but received #{value.class} (#{value})."
+        end
+
+        if value.kind_of?(Hash)
+          transformation = Configuration.hash_transformation
+          value = Helpers.send(transformation, value)
+        end
+
+        instance_variable_set("@#{key}", value)
+      end
+    end
+
+    # Takes a Proc that contains attribute definitions and applies
+    # that to this class.
+    #
+    # @param attributes [Proc]
+    #
+    def include_attributes(attributes)
+      class_eval(&attributes)
+    end
+  end
+
+  module InstanceMethods
+
+    # @param attributes [Hash]
+    #
+    def initialize(attributes = {})
+      self.attributes = attributes
+    end
+
+    # @return [Hash] keys and values for each defined attribute.
+    #
+    def attributes
+      include_nil = Configuration.include_nil_in_attributes
+
+      attributes = Hash.new.tap do |attrs|
+        Helpers.each_key(self.class) do |key|
+          value = send(key)
+
+          if !value.nil? || (value.nil? && include_nil)
+            attrs[key] = value
+          end
+        end
+      end
+
+      transformation = Configuration.hash_transformation
+      Helpers.send(transformation, attributes)
+    end
+
+    # Mass-assignment for the defined attributes by passing
+    # in a Hash. Non-existing attributes are ignored.
+    #
+    # @param value [Hash]
+    #
+    def attributes=(value)
+      if !value.kind_of?(Hash)
+        raise Errors::InvalidMassAssignment,
+          "Can't mass-assign #{value.class} (#{value}) type " +
+          "to #{self.class}#attributes."
+      end
+
+      value = Helpers.symbolize_keys(value)
+      keys = Array.new.tap do |keys|
+        Helpers.each_key(self.class) { |key| keys << key }
+        keys.uniq!
+      end
+
+      value.each do |key, value|
+        send("#{key}=", value) if keys.include?(key)
+      end
+    end
+  end
+
+  def self.included(base)
+    base.send(:include, InstanceMethods)
+    base.extend(ClassMethods)
+  end
+end