arspy 0.0.3 → 0.0.4

data/README.rdoc

@@ -0,0 +1,205 @@
+= ARSpy
+
+A Rails console command line tool for exploring, browsing and inspecting 
+the structure, associations and data of ActiveRecord data models.
+
+== Resources
+
+Install
+
+* sudo gem install arspy
+
+Use
+
+* require 'arspy'
+
+	
+== Description
+
+ARSpy provides a number of functions for inspecting a Rails application's 
+ActiveRecord model.  To use the gem all you need to to is the following:
+
+  sudo gem install arspy
+  ruby script/console
+  require 'arspy'
+
+With ARSpy, you can view associations, fields and data related to tables and relations
+in an easy-to-read format.
+
+== Inspecting ActiveRecord Associations and Attributes (Fields)
+
+=== 'Listing fields' with the 'lf' command
+
+Append the 'lf' command to an ActiveRecord object, class, or association method to
+print the name, type and database variable type for each attribute. 
+
+  User.lf
+  first_name  :string   (varchar(50))
+  last_name   :string   (varchar(50))
+  active      :boolean  (boolean)
+  age         :age      (int(11))
+
+
+=== 'Listing associations' with the 'la' command
+
+Append the 'la' command to an ActiveRecord object, class or association method to 
+print the name, type, class and configuration information for each association.
+
+  User.la
+  blogs        has_many  (Blog)
+  comments     has_many  (Comment)
+  friendships  has_many  (Friendship)  
+  friends      has_many  (User)        {:through=>:friendships}
+  assets       has_many  (Asset)       {:as=>:asset}
+
+=== Applying 'lf' and 'la' commands
+
+The 'la' and 'lf' command can be used on any ActiveRecord object, class, association
+or array of these. 
+
+  u = User.find_by_last_name('Smith')
+  u.la
+  u.blogs.lf
+  u.blogs.title
+  u.blogs.la
+  u.blogs.comments.la
+  u.blogs.comments.user.lf
+  u.blogs.comments.user.pr(:first_name, :last_name)  #see 'pr' command below
+ 
+
+== Printing in Columns
+
+=== Printing arrays with the 'pr' command
+
+Array data in the console is not so easy to read.
+
+  names
+  ["Peter Smith", "Sarah Johnson", "Randy Wade", "Alex Parsons", "Beth Silverton",
+  "Jenny Westmeyers", "Benjamin Grant", "Maria Stone"]
+
+Use the 'pr' command to print in a column.
+
+  names.pr
+  Peter Smith
+  Sara Johnson
+  ...
+
+=== Print columns of object attributes with the 'pr' command
+
+Arrays of ActiveRecord objects are even more difficult to read and analyze.  Use
+'pr' command to print attributes (fields) in columns.
+
+  User.find(2).friends.pr :first_name, :last_name 
+  Randy     Wade
+  Benjamin  Grant
+  Jenny     Westmeyers
+  Maria     Stone
+
+=== Printing expressions with 'pr' command
+
+Pass an expression as one of the columns to the 'pr' command.
+
+  User.find(2).friends.pr '"#{last_name}, #{first_name}"', :age
+  Wade, Randy        25
+  Grant, Benjamin    28
+  Westmeyers, Jenny  24
+  Stone, Maria       33
+
+Expressions using associations
+
+  User.find(2).friends.pr :first_name, :last_name, 'comments.count', 'blogs.count'
+  Randy     Wade        23   3
+  Benjamin  Grant       98   20
+  Jenny     Westmeyers  213  2
+  Maria     Stone       8    88
+
+
+== Iterating Associations and Data
+
+=== Chaining associations to get data sets
+
+Chain associations to get an array of the results.  For example, the following will
+collect all of the comment objects for all blogs written by User with ID=2.
+
+  User.find(2).blogs.comments
+  [#<Comment id: 21, user_id: 8, blog_id: 85, rating: 5, ... 
+
+Clean this up by further chainging to return an array of the 'comment' field 
+of each comment object and use 'pr' to print in a column.
+
+  User.find(2).blogs.comments.comment.pr
+  I agree with the blogger
+  I'm new to ActiveRecord.  Is there anyway to...
+  How do you use polymorphic associations to...
+  ...
+
+Note that chaining is accumulative.  To limit the results set, use the 'wi' or 'wo'
+commands.
+
+== Limiting data sets
+
+=== Limiting with the 'with' command
+
+The 'with' command is abbreviated to 'wi' in an expression.  It's like saying only show
+me the results with this condition OR this condition, etc.
+
+Say we want to limit comments in the above example to only those written by Randy Wade
+and Maria Stone.  If their user ids are [5, 9], then we can write
+
+  User.find(2).blogs.comments.wi(:user_id=>[5, 9]).comments.pr
+
+We could use ARSpy to look up the user ids.
+
+  User.find(2).blogs.comments.user.pr :first_name, :last_name, :id
+
+Note in this example, the 'wi' command is acting on attributes of the object immediately
+preceding it, namely, the Comment object.
+
+=== ORing and ANDing with the 'wi' command
+
+The 'wi' command can take an unlimited number of parameters.  Multiple parameters
+works as an OR operation on the results.  So the above example could have been written 
+
+  User.find(2).blogs.comments.wi(:user_id=>5, :user_id=>9).comments.pr
+
+with the same results.
+
+To get an AND operation, chain the 'wi' command.
+
+  User.find(2).blogs.comments.wi(:blog_id=>6).wi(:user_id=>5).comments.pr
+
+This example returns only comments for blog with ID 6 and user associated with
+the comment with ID 5.  On the other hand,
+
+  User.find(2).blogs.comments.wi(:blog_id=>6, :user_id=>5).comments.pr
+
+returns all comments associated with blog id 6 OR user id 5.
+
+=== Parameters of the 'wi' command
+
+The 'wi' command can take integers, strings and a hash of conditions.
+
+Strings are expressions evaluated against the preceding object.
+
+  User.find(2).blogs.comments.wi('user.last_name.include?("Grant")').comment.pr
+
+Integers are IDs for the object.
+
+  User.find(2).blogs.comments.wi(20,21,22).comment.pr
+
+A hash of {attribute=>[values]}.  The following displays comments belonging 
+to blogs with ids 6, 7 or 8.
+  
+  User.find(2).blogs.comments.wi(:blog_id=>[6,7,8]).comments.pr
+
+
+=== Excluding with the 'wo' (without) command
+
+The 'wo' command does the exact opposite of the 'wi' command, showing only those
+results that do not meet the conditions passed in the parameters.
+
+
+== Dependencies
+
+* ActiveRecord
+* ActiveSupport

data/lib/arspy/operators.rb

@@ -2,31 +2,31 @@ module Arspy
   module Operators
     def self.list_associations(active_record_klass)
       counts = {}
-      rows = active_record_klass.reflect_on_all_associations.map do |a|
-        counts[a.macro] ||= 0
-        counts[a.macro] += 1
-        self.format_column_association(a)
+      rows = active_record_klass.reflect_on_all_associations.map do |assoc|
+        counts[assoc.macro] ||= 0
+        counts[assoc.macro] += 1
+        self.format_column_association(assoc)
       end
-      rows.sort!{|a,b| a.first <=> b.first}
+      rows.sort!{|row1,row2| row1.first <=> row2.first}
       self.print_matrix(rows)
-      "Total: #{counts.inject(0){|sum, c| sum+c.last}} (" + counts.map{|c| "#{c.last} #{c.first}" }.join(', ') + ")"
+      "Total: #{counts.inject(0){|sum, count| sum+count.last}} (" + counts.map{|count| "#{count.last} #{count.first}" }.join(', ') + ")"
     end
 
     def self.list_fields(active_record_klass)
-      rows = active_record_klass.columns.map do |c|
-        self.format_column_field(c)
+      rows = active_record_klass.columns.map do |column|
+        self.format_column_field(column)
       end
-      rows.sort!{|a,b| a.first <=> b.first}
+      rows.sort!{|row1,row2| row1.first <=> row2.first}
       self.print_matrix(rows)
       "Total #{active_record_klass.columns.size} field#{active_record_klass.columns.size == 1 ? '' : 's'}"
     end
 
-    def self.format_column_association(a)
-      select_options = a.options.select{|k,v| [:through, :as, :polymorphic].include?(k)}
-      [a.name.to_s, a.macro.to_s, "(#{a.options[:class_name] || a.name.to_s.singularize.camelize})", select_options.empty? ? '' : Hash[*select_options.flatten].inspect]
+    def self.format_column_association(assoc)
+      select_options = assoc.options.select{|k,v| [:through, :as, :polymorphic].include?(k)}
+      [assoc.name.to_s, assoc.macro.to_s, "(#{assoc.options[:class_name] || assoc.name.to_s.singularize.camelize})", select_options.empty? ? '' : Hash[*select_options.flatten].inspect]
     end
-    def self.format_column_field(f)
-      [f.name.to_s, ":#{f.type}", "(#{f.sql_type})"]
+    def self.format_column_field(field)
+      [field.name.to_s, ":#{field.type}", "(#{field.sql_type})"]
     end
 
     def self.print_array(array, *args)
@@ -46,7 +46,7 @@ module Arspy
     end
 
     def self.print_object(object, *args)
-      print_matrix([args.map{|a| object[a]}]) if args
+      print_matrix([args.map{|arg| object[arg]}]) if args
       puts(object.inspect) unless args
       nil
     end
@@ -56,7 +56,7 @@ module Arspy
         when String then obj.instance_eval(arg) rescue false
         when Integer then obj.id == arg
         when Hash
-          arg.any?{|k,v| self.test_attribute(obj, k, (v.is_a?(Array) ? v : [v]) ) }
+          arg.any?{|key,val| self.test_attribute(obj, key, (val.is_a?(Array) ? val : [val]) ) }
         else
           false
         end
@@ -64,11 +64,11 @@ module Arspy
     end
     def self.with(array, *args)
       return array if (args.empty? || array.nil? || array.empty?)
-      array.select{|o| o && self.test_object(o, args)}
+      array.select{|obj| obj && self.test_object(obj, args)}
     end
     def self.without(array, *args)
       return array if (args.empty? || array.nil? || array.empty?)
-      array.select{|o| o && !self.test_object(o, args)}
+      array.select{|obj| obj && !self.test_object(obj, args)}
     end
     def self.enable_abbreviations; @@abbreviations_enabled = true; end
     def self.disable_abbreviations; @@abbreviations_enabled = false; end
@@ -110,35 +110,35 @@ module Arspy
       attrib_descriptors = attributes.map{|method_name| {:method_name=>method_name, :type=>:attribute, :abbr=>abbreviate_method_name(method_name)}}
       all_descriptors = assoc_descriptors + attrib_descriptors
       object.class.instance_variable_set('@arspy_ambiguous_abbreviations', remove_ambiguities(all_descriptors))
-      object.class.instance_variable_set('@arspy_abbreviations', Hash[*all_descriptors.map{|d| [d[:abbr], d] }.flatten])
+      object.class.instance_variable_set('@arspy_abbreviations', Hash[*all_descriptors.map{|desc| [desc[:abbr], desc] }.flatten])
     end
     def self.remove_ambiguities(descriptors)
       list={}
       ambiguities = {}
-      descriptors.each do |d|
-        if list.include?(d[:abbr])
-          if ambiguities[d[:abbr]]
-            ambiguities[d[:abbr]][:methods] << d[:method_name]
+      descriptors.each do |desc|
+        if list.include?(desc[:abbr])
+          if ambiguities[desc[:abbr]]
+            ambiguities[desc[:abbr]][:methods] << desc[:method_name]
           else            
-           ambiguities[d[:abbr]] = {:abbr=>d[:abbr], :methods=>[d[:method_name]]}
-           ambiguities[d[:abbr]][:methods] << list[d[:abbr]][:method_name]
+           ambiguities[desc[:abbr]] = {:abbr=>desc[:abbr], :methods=>[desc[:method_name]]}
+           ambiguities[desc[:abbr]][:methods] << list[desc[:abbr]][:method_name]
           end
         else
-          list[d[:abbr]] = d
+          list[desc[:abbr]] = desc
         end
       end
-      descriptors.reject!{|d| ambiguities.map{|h| h.first}.include?(d[:abbr])}
+      descriptors.reject!{|desc| ambiguities.map{|h| h.first}.include?(desc[:abbr])}
       ambiguities
     end
     def self.abbreviate_method_name(method_name)
-      splits = method_name.to_s.split('_')
+      words = method_name.to_s.split('_')
       abbr=[]
-      if splits.first == ''
+      if words.first == ''
         abbr << '_'
       end
-      splits.reject!{|s| s == ''}
-      abbr += splits.map do |s| 
-        chars = s.split(//)
+      words.reject!{|word| word == ''}
+      abbr += words.map do |word|
+        chars = word.split(//)
         first = chars.shift
         [first, chars.map{|ch| ch =~ /[0-9]/ ? ch : nil}].compact.flatten.join('')
       end
@@ -156,8 +156,8 @@ module Arspy
     end
     def self.interpret_attribute_or_method(array, method_name, *args)
       return array.map(&method_name) if args.empty?
-      raise 'Hash not allowed as attribute conditionals' if args.any?{|a| a.is_a?(Hash)}
-      array.select{|o| o && self.test_attribute(o, method_name, args)}
+      raise 'Hash not allowed as attribute conditionals' if args.any?{|arg| arg.is_a?(Hash)}
+      array.select{|obj| obj && self.test_attribute(obj, method_name, args)}
     end
     public
 

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 3
-  version: 0.0.3
+  - 4
+  version: 0.0.4
 platform: ruby
 authors: 
 - Jeff Patmon