alias 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/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT LICENSE
+
+Copyright (c) 2009 Gabriel Horner
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,88 @@
+== 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.
+
+== Setup
+
+Install the gem with:
+
+    sudo gem install cldwalker-alias -s http://gems.github.com
+
+The basic setup is simply drop two lines in your .irbrc:
+
+    require 'alias' 
+    Alias.create
+
+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.create :file=>"/path/to/my/clandestine_aliases.yml"
+
+If you'd like to define your aliases without a config file, pass Alias.create() an :aliases option:
+
+    Alias.create :verbose=>true, :aliases=>{
+      :constant=>{'Array' = 'A'},
+      :instance_method=>{'String'=>{'downcase'=>'dc' }, 'Array'=>{'select'=>'s'}}
+    }
+
+== Usage
+
+An example within Rails' script/console:
+
+    bash> script/console
+    >> require 'alias'
+    => true
+
+    # Import alias methods
+    >> extend Alias::Console
+    => main
+
+    # First let's see what ruby code Alias generates to create an alias.
+    >> create_aliases :class_method, {"ActiveRecord::Base"=>{'find'=>'[]'}}, :pretend=>true
+
+    class ::ActiveRecord::Base; class<< self; alias_method :[], :find; end; end
+    => true
+
+    # Create the above class method alias
+    >> create_aliases :class_method, "ActiveRecord::Base"=>{'find'=>'[]'}
+    => true
+
+    # 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
+
+    # Create the above instance method alias
+    >> create_aliases :instance_method, "ActiveRecord::Base"=>{"update_attribute"=>'ua'}
+    => true
+
+    # 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
+
+== Configuration
+
+For an example config file see test/aliases.yml.
+For an explanation of the config file format see Alias.config_file.
+ 
+== Creating Custom Alias Types
+
+See Alias::Creator.
+
+==  Todo
+* Allow loading of select aliases in a file.
+* Provide a way to autogenerate aliases with a given proc.

data/Rakefile

@@ -0,0 +1,50 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+begin
+  require 'rcov/rcovtask'
+
+  Rcov::RcovTask.new do |t|
+    t.libs << 'test'
+    t.test_files = FileList['test/**/*_test.rb']
+    t.rcov_opts = ["-T -x '/Library/Ruby/*'"]
+    t.verbose = true
+  end
+rescue LoadError
+  puts "Rcov not available. Install it for rcov-related tasks with: sudo gem install rcov"
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "alias"
+    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://tagaholic.me/alias/"
+    s.authors = ["Gabriel Horner"]
+    s.rubyforge_project = 'tagaholic'
+    s.has_rdoc = true
+    s.extra_rdoc_files = ["README.rdoc", "LICENSE.txt"]
+    s.files = FileList["Rakefile", "VERSION.yml", "README.rdoc", "CHANGELOG.rdoc", "LICENSE.txt", "{lib,test}/**/*"]
+  end
+
+rescue LoadError
+  puts "Jeweler not available. Install it for jeweler-related tasks with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'test'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+task :default => :test

data/VERSION.yml

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

data/lib/alias.rb

@@ -0,0 +1,85 @@
+$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__)) ||
+  $:.include?(File.expand_path(File.dirname(__FILE__)))
+require 'yaml'
+require 'alias/manager'
+require 'alias/validator'
+require 'alias/creator'
+require 'alias/creators/constant_creator'
+require 'alias/creators/instance_method_creator'
+require 'alias/creators/class_method_creator'
+require 'alias/creators/class_to_instance_method_creator'
+require 'alias/creators/any_to_instance_method_creator'
+require 'alias/util'
+require 'alias/console'
+
+# Most of the core Alias actions are run through Alias::Manager except for Alias.create. 
+# See Alias::Manager for an explanation of how aliases are created.
+module Alias
+  extend self
+
+  # Creates aliases from Alias.config_file if it exists and merges them with any explicit aliases. This method takes
+  # the same keys used by config files (see Alias.config_file) and also the following options:
+  # * :file : Specifies a config file to override Alias.config_file. If set to false, no config file is loaded.
+  # Examples:
+  #   # Loads any default files and the ones in :aliases. 
+  #   # Sets global verbosity for creators.
+  #   create :aliases=>{:constant=>{"Array"=>"A"}}, :verbose=>true
+  #   # Loads the given file and sets verbosity just for the :instance_method creator.
+  #   create :file=>"some file", :verbose=>[:instance_method]
+  def create(options={})
+    file_config = load_config_file(options.delete(:file))
+    new_config = Util.recursive_hash_merge(file_config, options)
+    manager.verbose = new_config[:verbose] if new_config[:verbose]
+    manager.force = new_config[:force] if new_config[:force]
+    (new_config[:aliases] || {}).each do |creator_type, aliases|
+      manager.create_aliases(creator_type, aliases)
+    end
+    @config = Util.recursive_hash_merge(config, new_config)
+  end
+
+  # By default, looks for existing files in config/alias.yml and then ~/.alias.yml. A config file has the following keys:
+  # [:aliases] This takes a hash mapping creators to their config hashes. Valid creators are :instance_method, :class_method, :constant,
+  #            :class_to_instance_method and :any_to_instance_method.
+  # [:verbose] Sets whether creators are verbose with boolean or array of creator symbols. A boolean sets verbosity for all creators whereas
+  #            the array specifies which creators. Default is false.
+  # [:force] Sets whether creators force optional validations with boolean or array of creator symbols. Works the same as :verbose. Default is false.
+  def config_file
+    @config_file ||= File.exists?("config/alias.yml") ? 'config/alias.yml' : "#{ENV['HOME']}/.alias.yml"
+  end
+
+  # Contains primary Alias::Manager object which is used throughout Alias.
+  def manager
+    @manager ||= Manager.new
+  end
+
+  #:stopdoc:
+  def add_to_config_file(new_aliases, file)
+    file ||= File.directory?('config') ? 'config/alias.yml' : "#{ENV['HOME']}/.alias.yml"
+    existing_aliases = read_config_file(file)
+    existing_aliases[:aliases] = Util.recursive_hash_merge existing_aliases[:aliases], new_aliases
+    save_to_file file, existing_aliases.to_yaml
+    puts "Saved created aliases to #{file}."
+  end
+
+  def save_to_file(file, string)
+    File.open(File.expand_path(file), 'w') {|f| f.write string }
+  end
+
+  def read_config_file(file)
+    file_config = File.exists?(File.expand_path(file)) ? YAML::load_file(File.expand_path(file)) : {}
+    file_config = Util.symbolize_keys file_config
+    file_config[:aliases] = file_config[:aliases] ? Util.symbolize_keys(file_config.delete(:aliases)) : {}
+    file_config
+  end
+
+  def load_config_file(file)
+    return {} if file == false
+    @config_file = file if file
+    read_config_file(config_file)
+  end
+  
+  def config
+    @config ||= {}
+  end
+  #:startdoc:
+end

data/lib/alias/console.rb

@@ -0,0 +1,20 @@
+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
+    # See Alias::Manager.create_aliases for usage.
+    def create_aliases(*args)
+      Alias.manager.console_create_aliases(*args)
+    end
+
+    # 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
+
+    # 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
+  end
+end

data/lib/alias/creator.rb

@@ -0,0 +1,112 @@
+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
+    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
+
+    # 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
+
+    # 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
+  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