core_utilities 0.1.1 → 0.1.3

data/README.rdoc

@@ -1,6 +1,118 @@
 = CoreUtilities
 
-This project rocks and uses MIT-LICENSE.
+Ruby-level extensions, utilities, convenience methods that I've found I'm constantly using in all my projects.
+
+== Usage:
+
+    gem 'core_utilities', :git => "git://github.com/caleon/core_utilities.git"
+
+== Selected Examples:
+
+=== Object
+
+==== Object#as
+
+    [ :donkey, { :class => 'list-item' } ].as { |arg, opts| link_to(arg, opts) }
+
+==== Object#is_included_in?
+
+		User.find(1).class.is_included_in?(User, Article, Authentication)
+		
+or alternatively:
+
+		@user.is_one_kind_of?(User, Article, Authentication)
+		
+which has the same effect as:
+
+    @user.is_one_kind_of?([User, Article, Authentication])
+
+by virtue of:
+
+=== Array
+
+==== Array#flatten_splat!
+
+#flatten_splat is for the common pattern of writing a method whose arguments are prepended by the splat operator, like the following:
+
+  def find(*types)
+    types = types.first if types.size == 1 and types.first.is_a?(Array)
+    # ...
+  end
+
+... which can now be written as:
+
+  def find(*types)
+    types.flatten_splat!
+  end
+
+==== array/base, array/filters
+
+These contain further convenience methods, none of them really novel or anything.
+
+==== Array#extract_options(!)
+
+Extending the behavior introduced by ActiveSupport, this one goes further to define Array#extract_options as the non-destructive analog, and also introduces Array#extract_options_with_merge. Previously you may have written:
+
+  def find(*args)
+    opts = args.extract_options!
+    opts[:user_id] = self.article.user_id
+    opts[:found_at] = Time.now
+  end
+		
+but now you can write:
+
+  def find(*args)
+    opts = args.extract_options_with_merge(:user_id => self.article.user_id, :found_at => Time.now)
+  end
+
+Note: The inclusion of this gem makes the *_with_merge methods the default behavior for extract_options(!) via alias_method_chain.
+
+==== Array#merge_options(!)
+
+If you find yourself extracting options as above only to re-inject that hash back into the original array to pass the arguments to a helper method (after some merging of the options hash), you may consider utilizing #merge_options:
+
+  def find(*args)
+    find_helper(*args.merge_options(:user_id => self.article.user_id, :found_at => Time.now))
+  end
+
+==== Array #arguments_and_options (a.k.a. #args_and_opts)
+
+The above Array methods lead to this handy method whose utility, in essence, is in its shortening a common Ruby pattern into a single line. Previously you may have written:
+
+  def find(*arguments)
+    mandatory_opts = { :user_id => self.article.user_id, :found_at => Time.now }
+    
+    opts = arguments.extract_options!
+    an_id = arguments.shift
+    
+    opts.merge!(mandatory_opts)
+  end
+		
+which, with the help of #args_and_opts (and the help of of #method_missing for extending its functionality) you can write:
+
+  def find(*arguments)
+    an_id, opts = arguments.args_with_shift_and_opts_with_merge!(:uer_id => self.article.user_id, :found_at => Time.now)
+  end
+
+Basically the format of the method call is arg(ument)?s(_with_[ARGMETHOD])?_and_opt(ion)?s(_with_[OPTSMETHOD])?!, where the ARGMETHOD is the name of the method which applies to the "args" part of the array, and OPTSMETHOD would be the name of the method which is called on the "opts" part of the array.
+
+Additionally, arguments can be passed to #args_and_opts, but as of now, in the event that both ARGMETHOD and OPTSMETHOD are defined, the arguments will be passed to the OPTSMETHOD only. Some effort was made to utilize arity to determine where the arguments should be passed to, but to my recollection this is still an unfinished aspect.
+
+
+=== Enumerable
+
+Has #map_select and #map_detect.
+
+=== Set
+
+Has #not_subset?(set)
+
+=== Hash
+
+Has #append_value which is similar to merging hashes, but in cases where you don't want to override the value of one of the hashes and would rather JOIN the values corresponding to the same key, (for example, wanting to add class names in a DOM element in Rails rather than overriding the original { :class => 'className' } hash):
+
+  { :id => "user_1-comments", :class => "user-comments" }.append_value!(:class, 'comments')
+  # => { :id => "user_1-comments", :class => "user-comments comments" }
 
 == Additional information
 

data/lib/core_utilities.rb

@@ -1,4 +1,5 @@
 require 'active_support'
+require 'active_support/core_ext'
 require 'core_utilities/core_ext'
 
 module CoreUtilities

data/lib/core_utilities/core_ext.rb

@@ -1,7 +1,4 @@
-%w(object enumerable set array hash).each do |file|
-  require File.expand_path("../core_ext/#{file}", __FILE__)
-end
-
+require 'core_utilities/core_ext/class'
 require 'core_utilities/core_ext/object'
 require 'core_utilities/core_ext/enumerable'
 require 'core_utilities/core_ext/set'

data/lib/core_utilities/core_ext/class.rb

@@ -0,0 +1,37 @@
+require 'active_support/core_ext/class/attribute'
+require 'active_support/core_ext/module/aliasing'
+
+class Class
+  # Purpose is to be able to define a default value for a class_attribute when one isn't initially set.
+  def class_attribute_with_default(*attrs) # Actually, this IS being used currently by gems in lib/
+    hash = attrs.last.is_a?(Hash) ? attrs.pop : {}
+    my_default = hash.delete(:default)
+    instance_writer = hash.blank? || hash[:instance_writer]
+
+    attrs.each do |name| # By the way, FIXME: i think this should be broken because if i want to use a string as a default, that will not be reflected.
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def self.#{name}() #{my_default || 'nil'} end
+        def self.#{name}?() !!#{name} end
+
+        def self.#{name}=(val)
+          singleton_class.class_eval do
+            remove_possible_method(:#{name})
+            define_method(:#{name}) { val }
+          end
+          val
+        end
+
+        def #{name}
+          defined?(@#{name}) ? @#{name} : singleton_class.#{name}
+        end
+
+        def #{name}?
+          !!#{name}
+        end
+      RUBY
+
+      attr_writer name if instance_writer
+    end
+  end
+  alias_method_chain :class_attribute, :default
+end

data/lib/core_utilities/version.rb

@@ -1,3 +1,3 @@
 module CoreUtilities
-  VERSION = "0.1.1"
+  VERSION = "0.1.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: core_utilities
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-11-16 00:00:00.000000000Z
+date: 2011-11-17 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &70141262027680 !ruby/object:Gem::Requirement
+  requirement: &70095083659380 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: 3.1.1
   type: :development
   prerelease: false
-  version_requirements: *70141262027680
+  version_requirements: *70095083659380
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &70141262025480 !ruby/object:Gem::Requirement
+  requirement: &70095083658880 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: 3.1.1
   type: :runtime
   prerelease: false
-  version_requirements: *70141262025480
+  version_requirements: *70095083658880
 - !ruby/object:Gem::Dependency
   name: sqlite3
-  requirement: &70141262024300 !ruby/object:Gem::Requirement
+  requirement: &70095083658500 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +43,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70141262024300
+  version_requirements: *70095083658500
 description: Core extensions with lots of handy methods
 email:
 - caleon@gmail.com
@@ -58,6 +58,7 @@ files:
 - lib/core_utilities/core_ext/array/flatten_splat.rb
 - lib/core_utilities/core_ext/array/merge_options.rb
 - lib/core_utilities/core_ext/array.rb
+- lib/core_utilities/core_ext/class.rb
 - lib/core_utilities/core_ext/enumerable.rb
 - lib/core_utilities/core_ext/hash.rb
 - lib/core_utilities/core_ext/object.rb