cldwalker-alias 0.1.2 → 0.2.0

data/CHANGELOG.rdoc

@@ -0,0 +1,16 @@
+== 0.2.0
+* Complete refactoring.
+* New alias types can be created easily with the DSL for Creator classes.
+* Added two new alias types, any_to_instance_method and class_to_instance_method.
+* Better tests and docs.
+
+== 0.1.2
+* Added search and console functionality.
+* Added better tests.
+
+== 0.1.1
+* Added checking for existing aliases.
+* Added config block to Alias.init.
+
+== 0.1.0
+* Initial release

data/README.rdoc

@@ -1,9 +1,9 @@
 == Description
 
-Creates aliases for class methods, instance methods and constants by specifying
-them in a YAML config file. By storing your aliases, it becomes possible to easily
-share and search them. Although the default aliases are created with the irb user in mind,
-it's possible to create your own alias types. See 'Customize Alias' below.
+Creates aliases for class methods, instance methods, constants, delegated methods and more. Aliases
+can be easily searched or saved as YAML config files to load later. Custom alias types are easy to
+create with the DSL Alias provides.  Although Alias was created with the irb user in mind, any Ruby
+console program can hook into Alias for creating configurable aliases.
 
 == Setup
 
@@ -11,99 +11,78 @@ Install the gem with:
 
     sudo gem install cldwalker-alias -s http://gems.github.com
 
-The easiest setup simply involves dropping two lines in your .irbrc:
+The basic setup is simply drop two lines in your .irbrc:
 
     require 'alias' 
-    Alias.init
+    Alias.create
 
-This setup assumes you have an aliases.yml in the current directory or a config/aliases.yml.
-If neither is the case, pass a :file option to init():
+This will assume a file in config/alias.yml or ~/.alias.yml. If you want it somewhere else,
+pass a :file option to create():
 
-    Alias.init :file=>"/path/to/my/clandestine_aliases.yml"
+    Alias.create :file=>"/path/to/my/clandestine_aliases.yml"
 
-If you'd like to define your aliases without a config file, pass Alias.init() a block and
-call methods as if they were top level keys in the config:
+If you'd like to define your aliases without a config file, pass Alias.create() an :aliases option:
 
-    Alias.init do |a|
-      a.verbose = true
-      a.constant = {'Array' = 'A'}
-      a.instance_method = {'String'=>{'downcase'=>'dc' }, 'Array'=>{'select'=>'s'}}
-    end
+    Alias.create :verbose=>true, :aliases=>{
+      :constant=>{'Array' = 'A'},
+      :instance_method=>{'String'=>{'downcase'=>'dc' }, 'Array'=>{'select'=>'s'}}
+    }
 
-== Irb/Console Use
+== Usage
 
-To use in irb or your own console, simply include the console class:
+An example within Rails' script/console:
 
-    irb>>include Alias::Console
-    => Object
+    bash> script/console
+    >> require 'alias'
+    => true
 
-Currently only two methods are imported: search and create.
-Search lists your aliases and create, well, creates aliases.
+    # Import alias methods
+    >> extend Alias::Console
+    => main
 
-Create:
-  
-    irb>>create :constant, "Alias"=>"A"
-    =>nil
+    # First let's see what ruby code Alias generates to create an alias.
+    >> create_aliases :class_method, {"ActiveRecord::Base"=>{'find'=>'[]'}}, :pretend=>true
 
-    irb>>A
-    =>Alias
-  
-Search:
-    
-    # Searches all alias types for an Alias
-    irb>>search :alias=>'A'
-    A = Alias (type: constant)
+    class ::ActiveRecord::Base; class<< self; alias_method :[], :find; end; end
+    => true
 
-    #Searches all alias types for any aliases with an A
-    irb>>search :alias=>/A/
-    A = Alias (type: constant)
-    AB = ActiveRecord::Base (type: constant)
+    # Create the above class method alias
+    >> create_aliases :class_method, "ActiveRecord::Base"=>{'find'=>'[]'}
+    => true
 
-    #Searches only class_method types named 'find'
-    irb>>search :type=>'class_method', :name=>'find'
-    [] = find (type: class_method, class: ActiveRecord::Base)
-  
+    # Create the above constant alias
+    >> create_aliases :constant, "ActiveRecord::Base"=>"AB"
+    => true
+    # Verify that it worked
+    >> AB
+    => ActiveRecord::Base
 
+    # If we try to create the constant alias again, Alias prevents us and warns us
+    >> create_aliases :constant, "ActiveRecord::Base"=>"AB"
+    Constant 'AB' not created since it already exists
+    => false
+    # We can force Alias to override a method, class or constant that already exists
+    >> create_aliases :constant, {"ActiveRecord::Base"=>"AB"}, :force=>true
+    => true
 
-== Configuration
+    # Create the above instance method alias
+    >> create_aliases :instance_method, "ActiveRecord::Base"=>{"update_attribute"=>'ua'}
+    => true
 
-For an example config file see aliases.yml.example.
+    # By default aliases are saved to config/alias.yml in rails or ~/.alias.yml if not.
+    >> save_aliases
+    Saved created aliases to config/alias.yml.
+    => true
 
-Options are: 
+== Configuration
 
-* verbose : true or false
-* constant: Alias constants no matter how many levels down. Takes a hash of constants as strings,
-  mapping constants to their aliases.
-    Example: {'Date'=>'D', 'ActiveRecord::Base'=>'AB'}
-* instance_method : Alias methods for the instances of specified classes. Takes a nested hash with Ruby classes as string keys. Each class should point
-  to a hash of methods, with the original methods mapping to the alias method.
-    Example: {'String'=>{'downcase'=>'dc'}}
-* class_method : Alias class methods. Takes the same format as instance_method.
-    Example: {'Date'=>{'day_fraction_to_time'=>'dftt'}}
+For an example config file see test/aliases.yml.
+For an explanation of the config file format see Alias.config_file.
  
-== Customize Alias
-
-You can create your own alias type by creating an Alias::*Creator Class. The * is there for the alias type name.
-Suppose you want to create a my_instance_method alias type. Simply pass a my_instance_method key
-with its appropriate aliases hash in the config. Then create your my_instance_method_creator class:
+== Creating Custom Alias Types
 
-    module Alias
-      class MyInstanceMethodCreator < Creator
-        def create_aliases(aliases_hash)
-          # My way of aliasing
-          # ...
-        end
-      end
-    end
-
-Notice that the class should be a camelized version of the alias type and inherit from Alias::Creator.
-At a minimum, make a create_aliases() to make custom aliases from the config data.
-See creator.rb for more methods you can hook into.
+See Alias::Creator.
 
 ==  Todo
-
-* Alias/forward methods from one object to another. This will be useful for creating
-  'commands' in irb.
-* Provide an auto_alias method for creators.
-* Save aliases to file (for console use).
-* Add more RDoc documentation. 
+* Allow loading of select aliases in a file.
+* Provide a way to autogenerate aliases with a given proc.

data/Rakefile

@@ -18,14 +18,14 @@ begin
   require 'jeweler'
   Jeweler::Tasks.new do |s|
     s.name = "alias"
-    s.description = "Provides aliases for class names, class methods, instance methods and more. Mainly for console use."
+    s.summary = "Creates, manages and saves aliases for class methods, instance methods, constants, delegated methods and more."
+    s.description = "Creates aliases for class methods, instance methods, constants, delegated methods and more. Aliases can be easily searched or saved as YAML config files to load later. Custom alias types are easy to create with the DSL Alias provides.  Although Alias was created with the irb user in mind, any Ruby console program can hook into Alias for creating configurable aliases."
     s.email = "gabriel.horner@gmail.com"
-    s.homepage = "http://github.com/cldwalker/alias"
-    s.summary = s.description
+    s.homepage = "http://tagaholic.me/alias/"
     s.authors = ["Gabriel Horner"]
     s.has_rdoc = true
     s.extra_rdoc_files = ["README.rdoc", "LICENSE.txt"]
-    s.files = FileList["Rakefile", "VERSION.yml", "README.rdoc", "LICENSE.txt", "aliases.yml.example", "{lib,test}/**/*"]
+    s.files = FileList["Rakefile", "VERSION.yml", "README.rdoc", "CHANGELOG.rdoc", "LICENSE.txt", "{lib,test}/**/*"]
   end
 
 rescue LoadError

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :major: 0
-:minor: 1
-:patch: 2
+:minor: 2
+:patch: 0

data/lib/alias/console.rb

@@ -1,56 +1,20 @@
-#Usage: include Alias::Console wherever you want to use these methods
 module Alias
+  # This module contains the main methods to be accessed from a ruby shell i.e. irb. Simply extend Alias::Console in your ruby shell.
   module Console
-    def self.included(base)
-      base.extend self
+    # See Alias::Manager.create_aliases for usage.
+    def create_aliases(*args)
+      Alias.manager.console_create_aliases(*args)
     end
-    
-    def create(*args)
-      Alias.manager.create_aliases(*args)
+
+    # Saves aliases to a file. If no file is given, defaults to config/alias.yml if the config directory exists (for Rails).
+    # Otherwise defaults to ~/.alias.yml.
+    def save_aliases(file=nil)
+      Alias.manager.save_aliases(file)
     end
-    
-    #options: type, raw, class, sort
-    #s 'man', :type=>'instance_method'
-    #s /ma/, :raw=>true
-    def search(*args)
-      options = args[-1].is_a?(Hash) ? args[-1].slice_off!(:raw, :sort) : {}
-      if args[0] && ! (args[0].is_a?(Hash) && args[0].empty?)
-        if args[0].is_a?(String) or args[0].is_a?(Regexp)
-          search_hash = {:name=>args[0]}
-          search_hash.merge!(args[1]) if args[1].is_a?(Hash)
-        elsif args[0].is_a?(Hash)
-          search_hash = args[0]
-        end
-        result = Alias.manager.search(search_hash)
-      else
-        result = Alias.manager.list
-      end
-      
-      if options[:sort]
-        result = result.sort {|a,b| 
-          (a[options[:sort]].nil? || b[options[:sort]].nil?) ? 1 :
-            (a[options[:sort]]) <=> b[options[:sort]]
-        }
-      end
-      if options[:raw]
-        result
-      else
-        format_search(result, options)
-        nil
-      end
+
+    # Searches aliases with a search term as defined by Alias::Manager.search. If no arguments given, all aliases are listed.
+    def search_aliases(*args)
+      args.empty? ? Alias.manager.all_aliases : Alias.manager.search(*args)
     end
-    
-    def format_search(result, options)
-      body = ''
-      if result.empty?
-        body = "No results"
-      else
-        result.each do |e|
-          h = e.slice_off!(:name, :alias)
-          body += "#{h[:alias]} = #{h[:name]}  (" + e.map {|k,v| "#{k}: #{v}"}.join(", ") + ")\n" 
-        end
-      end
-      puts body
-    end    
   end
 end

data/lib/alias/creator.rb

@@ -1,91 +1,112 @@
-# This is the base creator class from which other *Creator classes inherit.
-# Methods this class provides to non-creator classes are: Creator.create()
-# Methods this class provides to creator classes to be overridden: @creator.delete_invalid_aliases
-# and @creator.create_aliases
-
 module Alias
+  # Namespace for subclasses of Alias::Creator.
+  class Creators; end
+  # This is the base creator class. To be a valid subclass, the creator must define Alias::Creator.map and Alias::Creator.generate.
+  # Although not required, creators should enforce validation of their aliases with Alias::Creator.valid. Also, the creator should
+  # be named in the format Alias::Creators::*Creator where the asterisk stands for any unique string. Since that string is converted
+  # to an underscored version when referenced in the console, it's recommended to make it camel case. For example,
+  # Alias::Creators::InstanceMethodCreator is referenced by it's underscored version :instance_method.
+  # 
+  # To better understand how a creator works, here's the steps a creator goes through when creating aliases:
+  # * map() : Maps the hash from a config file or console input into an array of alias hashes.
+  # * valid() : Defines a validation that each alias hash must pass.
+  # * generate() : Given the array of alias hashes, generates the string of ruby code to be evaled for alias creation.
   class Creator
-    
-    attr_accessor :verbose, :force, :searched_at, :modified_at, :alias_map
-    def initialize(aliases_hash={})
-      self.alias_map = aliases_hash
+    class AbstractMethodError < StandardError; end
+    class FailedAliasCreationError < StandardError; end
+    class<<self
+      # Creates a validation expectation for the creator by giving it an Alias::Validator object aka validator. 
+      # This method must be given an :if or :unless option. If the :if option returns false or :unless option
+      # returns true for an alias, the alias is skipped.
+      # ==== Options:
+      # [:if] Takes a proc or a symbol referencing a registered validator. This proc must evaluate to true
+      #       for the validation to pass. See Alias::Validator.validate for what arguments this proc receives by default. See
+      #       Alias::Validator.default_validators for validators that can be referenced by symbol.
+      # [:unless] Same as :if option but the result is negated.
+      # [:message] A proc to print a message if the creator's verbose flag is set. Receives same arguments as :if and :unless procs. 
+      #            If a previous validator is referenced in :unless or :if, then their :message is inherited.
+      # [:with]  An array of alias attributes/keys which specify the current alias attributes to pass to the validator procs.
+      #          Overrides default argument a validator proc receives.
+      # [:optional] When set to true, this option can be overridden in conjunction with a creator's force flag. Default is false.
+      def valid(key, options={})
+        begin
+          validators[key] = Validator.new(options.merge(:key=>key, :creator=>self))
+        rescue Validator::MissingConditionError
+          raise ArgumentError, "A :unless or :if option is required."
+        rescue Validator::InvalidValidatorError
+          $stderr.puts "Validator not set for #{key}"
+          @validators.delete(key)
+        end
+      end
+
+      # Stores validators per alias attribute/key.
+      def validators #:nodoc:
+        @validators ||= {}
+      end
+
+      def maps_config(config) #:nodoc:
+        @map ? @map.call(config) : raise(AbstractMethodError, "No map() defined for #{self}")
+      end
+
+      # Takes a block which converts the creator's config to an array of aliases.
+      def map(&block)
+        @map = block
+      end
+
+      def generates_aliases(aliases) #:nodoc:
+        @generate ? @generate.call(aliases) : raise(AbstractMethodError, "No generate() defined for #{self}")
+      end
+
+      # Takes a block which converts aliases to a string of ruby code to run through Kernel#eval.
+      def generate(&block)
+        @generate = block
+      end
+
+      def class_or_module(klass) #:nodoc:
+        Util.any_const_get(klass).is_a?(Class) ? 'class' : 'module'
+      end
+
+      def inherited(subclass) #:nodoc:
+        @creators ||= []
+        @creators << subclass
+      end
+
+      # Array of all Creator subclasses.
+      def creators; @creators; end
+    end
+
+    # Same purpose as Alias::Manager.verbose and Alias::Manager.force but unlike them these only take a boolean.
+    attr_accessor :verbose, :force
+    # Array of alias hashes that have been created.
+    attr_accessor :aliases
+
+    def initialize(options={}) #:nodoc:
       @verbose = false
       @force = false
+      @aliases = []
     end
-    
-    def modified_since_last_search?
-      (@searched_at && @modified_at) ? (@modified_at > @searched_at) : true
-    end
-    
-    def alias_map=(value)
-      @modified_at = Time.now
-      @alias_map = value
-    end
-    
-    def auto_create(array_to_alias)
-      aliases_hash = generate_aliases(array_to_alias)
-      create(aliases_hash)
-      aliases_hash
-    end
-    
-    # Options are:
-    # * :auto_alias : Array of constants to alias by shortest available constant. For example,
-    #   if the constant A already exists, then Aardvark would be aliased to Aa.
-    def manager_create(aliases_hash, options = {})
-      self.verbose = options['verbose'] if options['verbose']
-      self.force = options['force'] if options['force']
-      create(aliases_hash)
-      if options['auto_alias']
-        auto_create(options['auto_alias'])
+
+    # Main method used to create aliases. Handles mapping, validation and creation of aliases.
+    def create(aliases_hash, pretend=false)
+      aliases_array = self.class.maps_config(aliases_hash)
+      delete_invalid_aliases(aliases_array)
+      self.aliases = aliases + aliases_array unless pretend
+      begin
+        #td: create method for efficiently removing constants/methods in any namespace
+        eval_string = Util.silence_warnings { self.class.generates_aliases(aliases_array) }
+        pretend ? puts("\n", eval_string) : Kernel.eval(eval_string)
+      rescue
+        raise FailedAliasCreationError, $!
       end
     end
-    
-    def create(aliases_hash)
-      delete_invalid_aliases(aliases_hash)
-      delete_existing_aliases(aliases_hash) unless self.force
-      self.alias_map = alias_map.merge aliases_hash
-      
-      #td: create method for efficiently removing constants/methods in any namespace
-      silence_warnings {
-        create_aliases(aliases_hash)
-      }
-    end
-    
-    # Should be overridden to delete aliases that point to invalid/nonexistent classes, methods ...
-    def delete_invalid_aliases(aliases_hash); end
-    
-    # Should be overridden to delete aliases that already exist. This method can be bypassed by passing
-    # a force option to the creator.
-    def delete_existing_aliases(aliases_hash); end
-    
-    # Must be overridden to use create()
-    def create_aliases(aliases_hash); 
-      raise "This abstract method must be overridden."
-    end
-    
-    # Must be overridden to use auto_create()
-    def generate_aliases(array_to_alias);
-      raise "This abstract method must be overridden."
-    end
-    
-    #Should be overridden to support search
-    def to_searchable_array; []; end
-    
-    def delete_invalid_class_keys(klass_hash)
-      klass_hash.each {|k,v| 
-        if Object.any_const_get(k).nil?
-          puts "deleted nonexistent klass #{k} #{caller[2].split(/:/)[2]}" if self.verbose
-          klass_hash.delete(k)
-        end
+
+    # Deletes invalid alias hashes that fail defined validators for a creator.
+    def delete_invalid_aliases(arr)
+      arr.delete_if {|alias_hash|
+        !self.class.validators.all? {|attribute, validator|
+          validator.validate(self, alias_hash, attribute)
+        }
       }
     end
-    
-    private
-    def silence_warnings
-      old_verbose, $VERBOSE = $VERBOSE, nil
-      yield
-    ensure
-      $VERBOSE = old_verbose
-    end
   end
-end
+end

data/lib/alias/creators/any_to_instance_method_creator.rb

@@ -0,0 +1,22 @@
+# Creates instance methods which can call any string of ruby code which ends in a method. This class provides the same 
+# functionality that Alias::Creators::ClassToInstanceMethodCreator provides and more but at the cost of less validation.
+# Expects a hash of classes/modules of the instance method mapped to a hash of ruby code strings and the instance method names.
+# For example, the hash {"MyDate"=>{'Date.today.to_s.gsub'=>'t'}} creates a MyDate.t method which directly calls Date.today.to_s.gsub.
+class Alias::Creators::AnyToInstanceMethodCreator < Alias::Creator
+  map do |config|
+    config.inject([]) {|t,(klass,hash)|
+      t += hash.map {|k,v|
+        {:class=>klass, :any_method=>k, :alias=>v}
+      }
+    }
+  end
+
+  valid :class, :if=>:class
+  valid :alias, :unless=>:instance_method, :with=>[:class, :alias], :optional=>true
+
+  generate do |aliases|
+    aliases.map {|e|
+      %[#{class_or_module(e[:class])} ::#{e[:class]}; def #{e[:alias]}(*args, &block); #{e[:any_method]}(*args, &block); end; end]
+    }.join("\n")
+  end
+end

data/lib/alias/creators/class_method_creator.rb

@@ -0,0 +1,19 @@
+# Creates aliases of class methods. Expects a hash of classes/modules mapped to a hash of class methods and their aliases
+# i.e. {'Date'=>{'today'=>'t'}}.
+class Alias::Creators::ClassMethodCreator < Alias::Creator
+  map do |config|
+    config.inject([]) {|t,(klass,aliases)|
+      t += aliases.map {|k,v| {:class=>klass, :name=>k, :alias=>v} }
+    }
+  end
+
+  valid :class, :if=>:class
+  valid :class_method, :if=>:class_method, :with=>[:class, :name]
+  valid :alias, :unless=>:class_method, :with=>[:class, :alias], :optional=>true
+
+  generate do |aliases|
+    aliases.map {|e|
+      "#{class_or_module(e[:class])} ::#{e[:class]}; class<<self; alias_method :#{e[:alias]}, :#{e[:name]}; end; end"
+    }.join("\n")
+  end
+end

data/lib/alias/creators/class_to_instance_method_creator.rb

@@ -0,0 +1,25 @@
+# Creates instance methods which call class methods. These are delegations rather than aliases.
+# Expects a hash of classes/modules of the instance method mapped
+# to a hash of the class methods and the instance method names. 
+# For example, the hash {"MyDate"=>{'Date.today'=>'t'}} would create a MyDate.t instance method
+# which directly calls Date.today.
+class Alias::Creators::ClassToInstanceMethodCreator < Alias::Creator
+  map do |config|
+    config.inject([]) {|t,(klass,hash)|
+      t += hash.map {|k,v|
+        {:class=>klass, :to_class=>k.split('.')[0], :name=>k.split('.')[1], :alias=>v}
+      }
+    }
+  end
+
+  valid :class, :if=>:class
+  valid :to_class, :if=>:class
+  valid :alias, :unless=>:instance_method, :with=>[:class, :alias], :optional=>true
+  valid :to_method, :if=>:class_method, :with=>[:to_class, :name]
+
+  generate do |aliases|
+    aliases.map {|e|
+      %[#{class_or_module(e[:class])} ::#{e[:class]}; def #{e[:alias]}(*args, &block); #{e[:to_class]}.__send__(:#{e[:name]}, *args, &block); end; end]
+    }.join("\n")
+  end
+end

data/lib/alias/creators/constant_creator.rb

@@ -0,0 +1,11 @@
+# Creates constants of aliases expecting a hash of existing constants mapped to their aliases.
+class Alias::Creators::ConstantCreator < Alias::Creator
+  map {|config| config.map {|k,v| {:name=>k, :alias=>v}} }
+
+  valid :alias, :unless=>:constant, :optional=>true
+  valid :name, :if=>:constant
+
+  generate do |aliases|
+    aliases.map {|e| "::#{e[:alias]} = ::#{e[:name]}"}.join("\n")
+  end
+end

data/lib/alias/creators/instance_method_creator.rb

@@ -0,0 +1,19 @@
+# Creates aliases of instance methods. Expects a hash of classes/modules mapped to a hash of instance methods and their aliases
+# i.e. {"String"=>{'to_s'=>'s'}}.
+class Alias::Creators::InstanceMethodCreator < Alias::Creator
+  map do |config|
+    config.inject([]) {|t,(klass,aliases)|
+      t += aliases.map {|k,v| {:class=>klass, :name=>k, :alias=>v} }
+    }
+  end
+
+  valid :class, :if=>:class
+  valid :instance_method, :if=>:instance_method, :with=>[:class, :name]
+  valid :alias, :unless=>:instance_method, :with=>[:class, :alias], :optional=>true
+
+  generate do |aliases|
+    aliases.map {|e|
+      "#{class_or_module(e[:class])} ::#{e[:class]}; alias_method :#{e[:alias]}, :#{e[:name]}; end"
+    }.join("\n")
+  end
+end