lean-attributes 0.1.0 → 0.2.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    Yzc3ZDljN2E0MGU2N2Y3ZTg2YWI5NzY4Y2M1NWMyYjIzM2E2MzJmMQ==
+    YjNkZDIxZDUzMGFkMWE5MGNiM2U3NGVhMTkzOWVmNDFkNWJmNTMwZg==
   data.tar.gz: !binary |-
-    ZWY1NWQ4MGI3NjczYTdiZGRjODU4MjM0YjU5MWE1MzY5NDZlMDY1Ng==
+    NmUwMTkxOGE4MDkyZjFiNmUwODFmNzQ4Y2U4OTlmNTlkYWUxN2Q4NA==
 SHA512:
   metadata.gz: !binary |-
-    Mjk3OGIyNjBlNDMzMWU2ZGI3MzBlNWI0MzNjOGM0NTA0NjUwODU5N2RiMGUz
-    NjJkOTM3MTNkNzg1YzMyZWYyZGJiZmMzYzI3MTg5MjBkY2FhNmFjYzRjOWI5
-    OWJjM2U5YTk4NDg1MmQxN2JiYzlkZTBlMDMwYjEyOTgxZWY5Njk=
+    MDUyMGU1OTY2NmUyYzY2YTNjMmE5MmE4MDk1YmQ1MTBiOTc0MGZjNzM4MzJl
+    NWY1ZmRhOGZjYzdjZGU5MGYzOGM4NDk2Y2I5YTkxNjhiMjVhYTg3NDYzY2Ux
+    YjI2ZjY5YjRmMWY5YjQ5NTFiMDBlYzljMjY2Y2I4ZTFiNzgzYWM=
   data.tar.gz: !binary |-
-    NzY1MGFmODVlNGI2Nzc4NWU1NTUwNGI4MDY4NWQ4NzE1YTNkM2Y0YmRjYzkw
-    MGI2ODQ0OTAxNDJiMmFlYTdhNTdjYTUwODFjNDNkOTEwMWU1MWY4MWU0OTQ3
-    YWNiYjQ3ZjZmMTNlMjA2YmRkYjA2YWMyYWQ3NDgxZDIwY2Q0MjY=
+    MDQ3YzZhZTBiMThmYTMxMzdhMjg1MWQ1ZmY4MWM2Nzc2MWE4OGRjYTQzNGVl
+    Y2FiODYwZGQwMmNhNDRkNzU3ZWEyYjg5NThkMjQ3MTJjZTQ1YWUxY2RkMDlh
+    NTBiNmIzZGY5ZTg5ODMwOGQzZDQwNTQxMzk1ZGI4NDJiYTExMDE=

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Change Log
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org/).
+
+## [Unreleased][unreleased]
+
+## [0.2.0] - 2015-09-18
+### Added
+- Adds content to README.md
+- Adds comprehensive YARD documentation
+- Adds #attributes method to return attribute values as a hash
+
+## Changed
+- Renames generated coercion methods from `coerce_<attribute>_to_<type>` to `coerce_<attribute>`
+- `Lean::Attribute::CoercionHelpers` is no longer an included module but a utility for precompiling coercion methods
+
+### Fixed
+- Fixes a bug where Time attributes would be improperly parsed to January 1st
+- Fixes a bug where coercion methods were not being called as documented
+
+## [0.1.0] - 2015-09-09
+### Changed
+- Makes calls to `coerce_<attribute>_to_<type>` unconditional when setting an attribute
+- Lean::Attributes::Coercion is now Lean::Attributes::CoercionHelpers
+
+## [0.0.2] - 2015-09-09 [YANKED]
+### Fixed
+- Fixes error when setting Symbol attributes
+
+## [0.0.1] - 2015-09-08
+### Added
+- Initial release
+
+[unreleased]: https://github.com/lleolin/lean-attributes/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/lleolin/lean-attributes/compare/v0.0.2...v0.1.0
+[0.0.2]: https://github.com/lleolin/lean-attributes/compare/v0.0.1...v0.0.2

data/README.md

@@ -1,5 +1,7 @@
 # Lean::Attributes
 
+Lean::Attributes is inspired by gems like [Virtus](https://github.com/solnic/virtus) or [FastAttributes](https://github.com/applift/fast_attributes). It allows one to define typed attributes on arbitrary Ruby classes. Lean::Attributes aims to be roughly as fast as FastAttributes but has a few syntactical differences in addition to support for default values.
+
 ## Status
 [![Gem Version](https://badge.fury.io/rb/lean-attributes.svg)](http://badge.fury.io/rb/lean-attributes)
 [![Build Status](https://travis-ci.org/lleolin/lean-attributes.svg)](https://travis-ci.org/lleolin/lean-attributes)
@@ -7,3 +9,120 @@
 [![Code Climate](https://codeclimate.com/github/lleolin/lean-attributes/badges/gpa.svg)](https://codeclimate.com/github/lleolin/lean-attributes)
 [![Dependency Status](https://gemnasium.com/lleolin/lean-attributes.svg)](https://gemnasium.com/lleolin/lean-attributes)
 [![Inline docs](http://inch-ci.org/github/lleolin/lean-attributes.svg?branch=master)](http://inch-ci.org/github/lleolin/lean-attributes)
+
+## Installation
+Add this line to your Gemfile:
+```ruby
+gem 'lean-attributes', '~> 0.2'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself with:
+
+    $ gem install lean-attributes
+
+## Usage
+```ruby
+require 'lean-attributes'
+
+class Book
+  include Lean::Attributes
+
+  attribute :title,     String
+  attribute :name,      String
+  attribute :pages,     Integer
+  attribute :authors,   Array
+  attribute :published, Date
+  attribute :sold,      Time,     default: :time_now
+  attribute :finished,  DateTime
+  attribute :format,    Symbol,   default: :hardcover
+
+  private
+
+  def time_now
+    Time.now.utc
+  end
+end
+
+book = Book.new(
+  title:      'There and Back Again',
+  name:       'The Hobbit',
+  pages:      '200',
+  authors:    'Tolkien',
+  published:  '1937-09-21',
+)
+book.finished = '1937-08-20 12:35'
+
+book.format # => :hardcover
+book.sold # => 2015-09-15 23:06:34 UTC
+book # =>
+# #<Book:0x007fcb7613b610
+#   @authors=["Tolkien"],
+#   @finished=
+#     #<DateTime: 1937-08-20T12:35:00+00:00 ((2428766j,45300s,0n),+0s,2299161j)>,
+#   @format=:hardcover,
+#   @name="The Hobbit",
+#   @pages=200,
+#   @published=#<Date: 1937-09-21 ((2428798j,0s,0n),+0s,2299161j)>,
+#   @sold=2015-09-15 23:06:34 UTC,
+#   @title="There and Back Again">
+```
+### Coercion
+The coercion capabilities included in this gem are poor by design and will only handle trivial use cases. Whenever you set an attribute, generated coercion methods are called. You can override these methods to create your own coercion rules.
+
+```ruby
+class ReadingProgress
+  include Lean::Attributes
+
+  attribute :current_page, Integer, default: 1
+
+  private
+
+  def coerce_current_page(value)
+    value = begin
+      value.to_i
+    rescue NoMethodError
+      1
+    end
+
+    value = 1 if value < 1
+    value
+  end
+end
+```
+
+Another way to contain such behavior is to create a `CurrentPage` class to represent your attribute instead of an Integer. The power is yours.
+
+## Benchmarks
+Lean::Attributes is meant to be relatively lightweight and fast.
+
+```
+FastAttributes: without values                          :  3499535.3 i/s
+Lean::Attributes: without values                        :  3467944.9 i/s - 1.01x slower
+Lean::Attributes: integer values for integer attributes :   151398.8 i/s - 23.11x slower
+FastAttributes: integer values for integer attributes   :   140099.8 i/s - 24.98x slower
+Lean::Attributes: string values for integer attributes  :   139070.9 i/s - 25.16x slower
+FastAttributes: string values for integer attributes    :   124387.2 i/s - 28.13x slower
+Virtus: integer values for integer attributes           :    36776.0 i/s - 95.16x slower
+Attrio: integer values for integer attributes           :    19452.5 i/s - 179.90x slower
+Virtus: without values                                  :    18184.8 i/s - 192.44x slower
+Attrio: string values for integer attributes            :    17689.9 i/s - 197.83x slower
+Attrio: without values                                  :    12769.1 i/s - 274.06x slower
+Virtus: string values for integer attributes            :     5043.4 i/s - 693.88x slower
+```
+
+## Versioning
+Lean:Attributes uses [Semantic Versioning 2.0.0](http://semver.org)
+
+## Contributing
+1. Fork it ( https://github.com/lleolin/lean-attributes/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
+
+## Copyright
+Copyright © 2015 R. Elliott Mason – Released under MIT License

data/lib/lean-attributes.rb

@@ -1 +1,5 @@
 require 'lean-attributes/attributes'
+
+# `Lean` namespace
+module Lean
+end

data/lib/lean-attributes/attributes.rb

@@ -3,21 +3,63 @@ require 'lean-attributes/attributes/coercion_helpers'
 require 'lean-attributes/attributes/initializer'
 
 module Lean
+  # Allows one to define typed, coercible attributes on Ruby classes with
+  # the {Lean::Attributes::ClassMethods#attribute attribute} method.
+  #
+  # @since 0.0.1
+  # @api public
+  #
+  # @see Lean::Attributes::ClassMethods#attribute
   module Attributes
-    def self.included(base)
-      base.class_eval do
-        include Basic
-        include CoercionHelpers
-        include Initializer
-      end
-    end
-
+    # Includes basic methods for defining attributes without polluting the
+    # inclusive class with coercion or initialization methods. You may mean to
+    # use {Lean::Attributes}.
+    #
+    # @since 0.1.0
+    #
+    # @see Lean::Attributes
+    # @see Lean::Attributes::ClassMethods
     module Basic
+      # Adds `.attribute` definition only
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @see ClassMethods
       def self.included(base)
         base.class_eval do
           extend ClassMethods
         end
       end
+
+      # Returns a hash containing defined attribute names and their values.
+      #
+      # @return [Hash] defined attributes and their values
+      #
+      # @since 0.2.0
+      # @api public
+      def attributes
+        @attributes ||=
+          self.class.defined_attributes.each_with_object({}) do |attr, memo|
+            memo[attr] = send(attr)
+          end
+      end
+    end
+
+    # `include Lean::Attributes` will add {Basic} functionality, in addition
+    # to {Initializer}
+    #
+    # @since 0.1.0
+    # @api private
+    #
+    # @see Basic
+    # @see ClassMethods
+    # @see Initializer
+    def self.included(base)
+      base.class_eval do
+        include Basic
+        include Initializer
+      end
     end
   end
 end

data/lib/lean-attributes/attributes/attribute.rb

@@ -1,26 +1,84 @@
 module Lean
   module Attributes
+    # Represents an attribute defined by
+    # {Lean::Attributes::ClassMethods#attribute}
+    #
+    # @since 0.0.1
+    # @api private
+    #
+    # @see Lean::Attributes::ClassMethods#attribute
     class Attribute
+      # @return [Symbol] name of the Attribute
       attr_reader :name
 
+      # Description of method
+      #
+      # @param [Hash] options = {} describe options = {}
+      # @option options [Object] :default default value or method name as a
+      #   Symbol
+      # @option options [#to_sym] :name attribute name
+      # @option options [#to_s] :type class or class name that the attribute
+      #   will be
+      # @return [Attribute] description of returned object
+      #
+      # @see Lean::Attributes::ClassMethods#attribute
       def initialize(options = {})
         @default  = options[:default]
         @name     = options[:name].to_sym
         @type     = options[:type].to_s.to_sym
       end
 
+      # Generates a method definition as a String with the name
+      # `coerce_<attribute>`.
+      #
+      # @example
+      #   class Post
+      #     include Lean::Attributes
+      #
+      #     attribute :author, String
+      #     attribute :parent, Post
+      #
+      #     # generated_methods:
+      #     # def coerce_author(value)
+      #     #   value.to_s unless value.nil?
+      #     # end
+      #
+      #     # def coerce_parent(value)
+      #     #   Post.new(value) unless value.nil?
+      #     # end
+      #   end
+      #
+      # @return [String] method definition
+      #
+      # @see #coercion_method_name
+      # @see CoercionHelpers
       def coercion_method
         <<-EOS
-          def #{coercion_method_name(name)}(value)
-            #{coercion_method_name}(value)
+          def coerce_#{name}(value)
+            #{CoercionHelpers.method_body_for_type(@type)} unless value.nil?
           end
         EOS
       end
 
-      def coercion_method_name(from = nil)
-        ['coerce', from, 'to', @type.to_s.downcase].compact.join('_')
+      # Generates a method with a name `coerce_<attribute>`.
+      #
+      # @return [String] method name
+      #
+      # @see #coercion_method
+      def coercion_method_name
+        "coerce_#{name}"
       end
 
+      # If the configured default is a Symbol but the intended type for this
+      # attribute is anything but, interpret the default as a method name to
+      # which we will `send`. Otherwise, just use the configured default as a
+      # String.
+      #
+      # @return [Object] configured default
+      #
+      # @since 0.1.0
+      #
+      # @see #getter_method_with_default
       def default
         if @default.is_a?(Symbol) && @type != :Symbol
           return "send(:#{@default})"
@@ -29,12 +87,57 @@ module Lean
         @default.inspect
       end
 
+      # Generates a getter method definition if the Attribute has a default,
+      # or we just use the straightforward `attr_reader :attribute_name`.
+      #
+      # @example
+      #   class Post
+      #     include Lean::Attributes
+      #
+      #     attribute :author,        String
+      #     attribute :replies_count, Integer, default: 0
+      #
+      #     # generated attr_reader:
+      #     # attr_reader :author
+      #
+      #     # generated getter with default
+      #     # def replies_count
+      #     #  @replies_count ||= 0
+      #     # end
+      #   end
+      #
+      # @return [String] description of returned object
+      #
+      # @see #getter_method_with_default
       def getter_method
         return getter_method_with_default unless @default.nil?
 
         "attr_reader :#{@name}"
       end
 
+      # Generates a getter method definition that lazily sets a default.
+      #
+      # @example
+      #   class Post
+      #     include Lean::Attributes
+      #
+      #     attribute :created_at,    Time,     default: :default_created_at
+      #     attribute :replies_count, Integer,  default: 0
+      #
+      #     # generated methods:
+      #     # def created_at
+      #     #   @first_name ||= send(:default_created_at)
+      #     # end
+      #
+      #     # def replies_count
+      #     #   @replies_count ||= 0
+      #     # end
+      #   end
+      #
+      # @return [String] method definition that sets default
+      #
+      # @see #default
+      # @see #getter_method
       def getter_method_with_default
         <<-EOS
           def #{name}
@@ -43,10 +146,27 @@ module Lean
         EOS
       end
 
+      # Generates a setter method definition that coerces values to the
+      # configured type if necessary.
+      #
+      # @example
+      #   class Book
+      #     include Lean::Attributes
+      #
+      #     attribute :pages, Integer
+      #
+      #     # generated method:
+      #     # def pages=(value)
+      #     #  value = coerce_pages(value)
+      #     #  @pages = value
+      #     # end
+      #   end
+      #
+      # @return [String] method definition
       def setter_method
         <<-EOS
           def #{name}=(value)
-            value = #{coercion_method_name}(value) unless value.is_a?(#{@type})
+            value = #{coercion_method_name}(value)
             @#{name} = value
           end
         EOS

data/lib/lean-attributes/attributes/class_methods.rb

@@ -2,7 +2,19 @@ require 'lean-attributes/attributes/attribute'
 
 module Lean
   module Attributes
+    # Methods that extend classes that include {Lean::Attributes}
+    #
+    # @since 0.0.1
+    # @api public
     module ClassMethods
+      # Defines a new attribute. Adds getter and setter methods to the class.
+      #
+      # @param [Symbol] name describe name
+      # @param [Class,String,Symbol] type describe type
+      # @param [Hash] options
+      # @option options [Object] :default default value or method name to call
+      #   as a Symbol
+      # @return [Attribute] configured Attribute
       def attribute(name, type, options = {})
         attribute = Attribute.new(
           default:  options[:default],
@@ -10,12 +22,28 @@ module Lean
           type:     type
         )
 
+        defined_attributes << attribute.name
+
         class_eval(attribute.coercion_method, __FILE__, __LINE__ + 1)
         class_eval(attribute.getter_method,   __FILE__, __LINE__ + 1)
         class_eval(attribute.setter_method,   __FILE__, __LINE__ + 1)
 
         attribute
       end
+
+      # @return [Array<Symbol>] names of defined attributes
+      #
+      # @since 0.2.0
+      # @api private
+      def defined_attributes
+        return @defined_attributes if @defined_attributes
+
+        @defined_attributes = if superclass.respond_to?(:defined_attributes)
+                                superclass.defined_attributes.clone
+                              else
+                                []
+                              end
+      end
     end
   end
 end

data/lib/lean-attributes/attributes/coercion_helpers.rb

@@ -1,36 +1,40 @@
 module Lean
   module Attributes
+    # Incredibly straightforward methods that coerce some types into other
+    # common types. You may find that you need to override these methods,
+    # depending on your use case.
+    #
+    # @since 0.1.0
+    # @api private
     module CoercionHelpers
-      def coerce_to_array(value)
-        Array(value) unless value.nil?
-      end
-
-      def coerce_to_bigdecimal(value)
-        BigDecimal.new(value, 0) unless value.nil?
-      end
-
-      def coerce_to_date(value)
-        Date.parse(value) unless value.nil?
-      end
-
-      def coerce_to_datetime(value)
-        DateTime.parse(value) unless value.nil?
-      end
-
-      def coerce_to_integer(value)
-        value.to_i unless value.nil?
-      end
-
-      def coerce_to_string(value)
-        value.to_s unless value.nil?
-      end
-
-      def coerce_to_symbol(value)
-        value.to_sym unless value.nil?
-      end
+      # Method body strings used to precompile `coerce_<attribute>` methods
+      #
+      # @since 0.2.0
+      #
+      # @see .method_body_for_type
+      # @see Attribute#coercion_method
+      METHOD_BODIES = {
+        Array:      'Array(value)',
+        BigDecimal: 'BigDecimal.new(value, 0)',
+        Date:       'Date.parse(value)',
+        DateTime:   'DateTime.parse(value)',
+        Float:      'value.to_f',
+        Integer:    'value.to_i',
+        String:     'value.to_s',
+        Symbol:     'value.to_s.to_sym',
+        Time:       'Time.parse(value).utc'
+      }
 
-      def coerce_to_time(value)
-        Time.new(value) unless value.nil?
+      # Fetches or generates the method body for coercing a value to this type
+      #
+      # @param [Symbol] type based on class name e.g. `:DateTime`
+      # @return [String] method body for coercion to type
+      #
+      # @since 0.2.0
+      #
+      # @see Attribute#coercion_method
+      def self.method_body_for_type(type)
+        METHOD_BODIES[type] || "#{type}.new(value)"
       end
     end
   end

data/lib/lean-attributes/attributes/initializer.rb

@@ -1,6 +1,15 @@
 module Lean
   module Attributes
+    # Adds an `#initialize` method that sets attribute values based on
+    # Hash keys-values
+    #
+    # @since 0.0.1
+    # @api public
     module Initializer
+      # Assigns Hash values to attributes based on key names
+      #
+      # @param [Hash] attributes
+      # @return [Object] instance of inclusive class with attributes set
       def initialize(attributes = {})
         attributes.each do |name, value|
           send(:"#{name}=", value)

data/lib/lean-attributes/version.rb

@@ -1,5 +1,5 @@
 module Lean
   module Attributes
-    VERSION = '0.1.0'
+    VERSION = '0.2.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lean-attributes
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - R. Elliott Mason
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-09 00:00:00.000000000 Z
+date: 2015-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -60,6 +60,7 @@ extensions: []
 extra_rdoc_files:
 - README.md
 files:
+- CHANGELOG.md
 - README.md
 - lean-attributes.gemspec
 - lib/lean-attributes.rb