intrinsic 1.0.3 → 1.1.0

data/CHANGELOG.mdown

@@ -1,3 +1,25 @@
+1.1.0 / 2012-01-08
+==================
+
+  * Adding TODO's and bugs to fix
+  * Documenting the check_properties_of method
+  * Documenting the redefine of the to_s method
+  * Documenting the initialize method provided to objects
+  * Detailing the internals of the included hook
+  * Documenting the included hook
+  * Documenting details about the intrinsic model
+  * ADding an example of usage from the sample file
+  * ADding a list of pros and cons for Virtus
+  * Adding a list of pros and cons for activemodel
+  * Adding a section on alternatives
+  * Adding in the two people who deserve credit the most
+  * Updating the gem version
+  * Adding chainable syntax detail
+  * Extrapolating on idea
+  * Adding code markup
+  * Adding code markup
+
+
 1.0.3 / 2012-01-08
 ==================
 

data/README.md

@@ -7,21 +7,71 @@ The intrinsic gem is for giving your objects typed attributes, defaults, and val
 usage
 -----
 
-Using the intrinsic library is pretty simple.
+Using the intrinsic library is pretty simple and it works much like [ActiveModel](https://github.com/rails/rails/tree/master/activemodel) or [Virtus](https://github.com/solnic/virtus).
 The basic features are:
 
-  - Getters & Setters for named properties (similar to attr_accessor)
-  - Default values, both in regular and Proc (ie callable lambda) form
-  - Easy API for dumping object attributes (similar to ostruct)
+  - Getters & Setters for named properties (similar to `attr_accessor`)
+  - Default values, both in regular and Proc (ie callable `lambda`) form
+  - Easy API for dumping object attributes (similar to `ostruct`)
   - Type and Argument errors for incorrectly supplied properties
   - Type coercion for attributes, as well as easily defininable new types
 
 
 In addition you get these cool features:
 
-  - Validate your properties with simple boolean logic, no complex Validator classes!
-  - Get errors when your validations don't work (simple errors for now)
-  -
+  - Validate your properties with simple boolean logic, no complex `Validator` classes!
+  - Simple error messages when your validations don't work (basic strings for now)
+  - Chainable syntax for property setting: `Person.new.name("Kurtis").age(24)`
+
+
+Here's an example of a Class modified by intrinsic:
+
+``` ruby
+require 'intrinsic'
+
+class Person
+  include Intrinsic
+  include Intrinsic::Intrinsicism::Validation
+
+  property :name
+  property :email
+  property :age, Integer, default: 13
+
+  validation_for :name  { name.match /\w/ }
+  validation_for :age   { (13..100).include? age }
+  validation_for :email { email.count('@') == 1 and (5..256).include? email.length }
+end
+
+person = Person.new name: "Kurtis"     # => #<Person:2152879000 name="Kurtis", email=nil, age=13>
+person.name("Hurly Burly").age("34")   # => #<Person:2153464580 name="Hurly Burly", age=34>
+person.name                            # => "Hurly Burly"
+person.is_valid?                       # => false
+person.errors                          # => ["email is not valid"]
+```
+
+
+**Alternatives**
+
+You may have noticed some alternative gems out there!
+This is great, because it gives you a keen eye on how to make intrinsic better.
+Here's a list of what those alternatives are and why I think Intrinsic should exist:
+
+  * *ActiveModel*
+      - **Pro**: Extremely large community and support over intrinsic
+      - Pro: Well tested, documented, and designed
+      - Pro: Continually worked on by many
+      - **Con**: Large and bulky, with far too many tools in the toolbox
+      - Con: Always tied to Rails
+      - Con: Complex inner workings for even simple things
+  * *Virtus*
+      - **Pro**: Well maintained and contributed too.
+      - Pro: Extremely well tested and documented
+      - Pro: Extended feature set above and beyond intrinsic
+      - **Con**: Always tied to DataMapper
+      - Con: Still not version 1.0.0, and thus has an unstable API
+      - Con: No validation system planned or in feature set
+
+All of these alternatives are worth looking into!
 
 
 installing
@@ -43,7 +93,7 @@ Or add it to your `Gemfile`:
 ``` ruby
 source :rubygems
 
-gem "intrinsic", "1.0.1"
+gem "intrinsic", "1.1.0"
 ```
 
 That's all you have to do.
@@ -70,8 +120,8 @@ We welcome any pull requests or commits that improve `intrinsic`.
 changelog
 ---------
 
-  - 1.0.3:
-      * Adding helpful README and license, updating example script
+  - 1.1.0: Documentation of the intrinsic module, updating of readme details
+  - 1.0.3: Adding helpful README and license, updating example script
   - 1.0.0: Initial release
 
 
@@ -96,15 +146,14 @@ contributing
 Credits
 -------
 
-  - []()
-  - []()
-  - []()
+  - [Piotr Solnica](https://github.com/solnic) for starting [Virtus](https://github.com/solnic/virtus) and inspiring me to build my own version of the concept.
+  - [Yehuda Katz](https://github.com/wycats) for pulling out [ActiveModel](https://github.com/rails/rails/tree/master/activemodel), thus inspiring me to work on my own.
 
 
 License
 -------
 
-Copyright (c) 2011 Kurtis Rainbolt-Greene
+Copyright (c) 2012 Kurtis Rainbolt-Greene
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/lib/intrinsic.rb

@@ -2,27 +2,62 @@ require 'intrinsic/version'
 require 'intrinsic/intrinsicism'
 require 'intrinsic/extrinsicism'
 
+# The Intrinsic model is the gateway to all the sub models, and by including
+# it into a model or class you gain all of the power of the library
 module Intrinsic
+
+  # Defines a hooks onto `include` so that the subject is also extended with the model
+  # meaning that singleton and instance methods exist on the class and instance
+  # of the class.
   def self.included(subject)
+    # Make a call to the superclass original included method
     super
+    # Extend the class with the model to get the singleton methods
     subject.extend Intrinsicism
+    # Send the include method with the model as an argument
+    # TODO: Find out if this is needed?
     subject.send :include, Intrinsicism
   end
 
+  # Defines the initialize method that takes a hash and sets the properties
+  # to those values. It also takes the defaults and assigns them to the properties.
+  # TODO: Rename the parameter to something else, like `initial_properties`
+  # TODO: Make sure all the keys are symbols, or at least turn them into symbols
   def initialize(values = {})
+    # Create a new empty table for the properties, and then merge in the defaults
+    # TODO: Make defaults a class variable
     @properties = {}.merge self.class.defaults
+    # Check to make sure all of the given properties are within the acceptable list
+    # TODO: Rename this method, it's terribly named
+    # TODO: Move it above everything else, and in an if block to save CPU time
     check_properties_of values
+    # Go over each property-value pair and send the value to the correct
+    # property method
     values.each { |property, value| send property.to_sym, value }
+    # Return the object for chaining purposes
+    # TODO: Is this even needed?
     self
   end
 
+  # Redefining the `to_s` method so that print out is prettier
+  # TODO: Change object_id to the correct hash
+  # TODO: Remove self from object_id
   def to_s
     "#<#{self.class}:#{self.object_id} #{properties.map{|k,v| k.to_s + '=' + v.inspect}.join(', ')}>"
   end
 
   private
+    # Defining a method that makes sure all of the properties are within
+    # the list of class properties
+    # TODO: Look into expanding this to allow for "subclass with slightly different
+    # attributes" situation
+    # TODO: Rename the parameter like with initialize
     def check_properties_of(values)
+      # Go over each key, and if it results in false raise an ArgumentError
+      # TODO: Provide helpful raise message
       raise ArgumentError unless values.each_key.all? do |property|
+        # Check to see if the property is included in the class property list
+        # TODO: Raise properties into a class variable
         self.class.properties.include? property
       end
     end

data/lib/intrinsic/version.rb

@@ -1,3 +1,3 @@
 module Intrinsic
-  VERSION = "1.0.3"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: intrinsic
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2012-01-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &2156056780 !ruby/object:Gem::Requirement
+  requirement: &2157876040 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - =
@@ -21,10 +21,10 @@ dependencies:
         version: 0.9.2.2
   type: :development
   prerelease: false
-  version_requirements: *2156056780
+  version_requirements: *2157876040
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &2156056260 !ruby/object:Gem::Requirement
+  requirement: &2157875520 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - =
@@ -32,7 +32,7 @@ dependencies:
         version: 0.7.4
   type: :development
   prerelease: false
-  version_requirements: *2156056260
+  version_requirements: *2157875520
 description: Intrinsic adds properties to your objects
 email:
 - kurtisrainboltgreene@gmail.com
@@ -74,7 +74,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1445375515393034073
+      hash: -3006681913647196833
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -83,7 +83,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1445375515393034073
+      hash: -3006681913647196833
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.10