bond 0.1.4 → 0.2.0

data/CHANGELOG.rdoc

@@ -1,3 +1,15 @@
+== 0.2.0
+* Added comprehensive argument completion per module, method and argument.
+* Added 60+ default method argument completions.
+* Added configuration system and DSL.
+* Added user-friendly completion error handling.
+* Improved Bond.spy.
+* Fixed several 1.9 bugs.
+* Replaced require 'bond/completion' with Bond.start.
+* Changed underscore_search to use '_' instead of '-'.
+* Removed Bond.debrief and Bond.reset.
+* Switched to bacon for tests.
+
 == 0.1.4
 * Added Bond.recomplete to make redefinition of completion missions easy.
 * Added flag to readline extension building so that installing bond doesn't fail for

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT LICENSE
 
-Copyright (c) 2009 Gabriel Horner
+Copyright (c) 2010 Gabriel Horner
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -1,186 +1,205 @@
+Note: To read a linked version of this README, {click here}[http://tagaholic.me/bond/doc/]
+
 == Description
 
-Bond is on a mission to make custom autocompletion easy in irb and other console/readline-like
-environments. Bond supports custom argument completion of methods, method completion of objects and
-anything else your wicked regex's can do. Bond comes armed with a Readline C extension to get the
-full line of input as opposed to irb's last-word based completion. Bond makes custom searching of
-possible completions easy which allows for nontraditional ways of autocompleting i.e. instant
-aliasing of multi worded methods.
+Bond is on a mission to improve irb's autocompletion. Aside from doing everything irb's can do and fixing its quirks,
+Bond can autocomplete argument(s) to methods, uniquely completing per module, per method and per argument. Bond brings
+irb's completion closer to bash/zsh as it provides a configuration system and a DSL for creating custom completions
+and completion rules. With this configuration system, users can customize their irb autocompletions and share
+it with others. Bond is able to offer more than irb's completion since it uses a Readline C extension to get the full
+line of input when completing as opposed to irb's last-word approach.
 
 == Install
 
 Install the gem with:
 
-    sudo gem install cldwalker-bond --source http://gems.github.com
+    sudo gem install bond
 
-== Usage
+== Setup
 
-To start of with, you may want to replace irb's completion (irb/completion) with Bond's enhanced version
-in your irbrc :
+To start off, replace irb's completion (require 'irb/completion') with Bond's enhanced version in your irbrc :
 
   require 'bond'
-  require 'bond/completion'
-
-This should give you more consistent method completion on any objects, file completion of strings
-and argument completion of Kernel#require, Kernel#system and the backtick (`).
-
-=== Argument Completion for Methods
-
-    bash> irb -rirb/completion -rubygems
-    # This loads Bond but it doesn't take over completion yet.
-    >> require 'bond'
-
-    # For Bond to handle completions, we must explicitly define a completion mission.
-    # Order matters since the order they're declared in is the order they're searched.
-    >> Bond.complete(:method=>'method1') {|input|  %w{some args to autocomplete} }
-    => true
-    >> Bond.complete(:method=>'method2') {|input|  %w{more args to autocomplete} }
-    => true
-
-    # Works as above
-    >> method1 [TAB]
-    args   autocomplete   some   to
-    >> method1 'a[TAB]
-    args   autocomplete
-    >> method1 'au[TAB]
-    >> method1 'autocomplete'
-
-    # Anything not matched by the above completion missions defaults to irb completion
-    >> $std[TAB]
-    $stderr  $stdin   $stdout
-    
-=== File Argument Completion for Methods
-
-    # Pass :search=>false to turn off Bond searching since FILENAME_COMPLETION_PROC does it for us.
-    >> Bond.complete(:method=>"File.read", :search=>false) {|input| 
-        Readline::FILENAME_COMPLETION_PROC.call(input) || [] }
-    => true
-
-    # Test drive it
-    >> File.read '[TAB]
-    .git/   LICENSE.txt   README.rdoc   Rakefile      VERSION.yml   bond.gemspec  ext/    lib/     test/
-    >> File.read 'l[TAB]
-    >> File.read 'lib/
-    >> File.read 'lib/bond.[TAB]
-    >> File.read 'lib/bond.rb'
-
-    # Since File.read doesn't understand ~, let's improve the above completion proc
-    >> file_completion = proc {|input| (Readline::FILENAME_COMPLETION_PROC.call(input) ||
-        []).map {|f| f =~ /^~/ ?  File.expand_path(f) : f } }
-    => #< Proc:0x0100f1d0@(irb):20>
-    >> Bond.reset; Bond.complete :method=>"File.read", :search=>false, &file_completion
-    => true
-
-    # Tilda test driving
-    >> File.read "~/[TAB]
-    >> File.read "/Users/bozo/
-    >> File.read "/Users/bozo/.alias.[TAB]
-    >> File.read "/Users/bozo/.alias.yml"
-    
-    # Let's add this to *all* our File methods:
-    >> Bond.reset; Bond.complete :method=>/File\.(#{Regexp.union(*File.methods(false))})/,
-        :search=>false, &file_completion
-    => true
-
-=== Method Autocompletion on Specified Objects
-    # Let's explore Bond::Agent's functionality
-     >> ba = Bond.agent; nil
-     => nil
-     # Irb let's you autocomplete everything that an object responds to for better or worse.
-     >> ba.[TAB]
-     ba.__id__                      ba.eql?                        ba.instance_eval               ba.method                      ba.send                        ba.to_yaml
-     ba.__send__                    ba.equal?                      ba.instance_of?                ba.methods                     ba.setup                       ba.to_yaml_properties
-     ba.call                        ba.extend                      ba.instance_variable_defined?  ba.missions                    ba.singleton_methods           ba.to_yaml_style
-     ba.class                       ba.find_mission                ba.instance_variable_get       ba.nil?                        ba.taguri                      ba.type
-     ba.clone                       ba.freeze                      ba.instance_variable_set       ba.object_id                   ba.taguri=                     ba.untaint
-     ba.complete                    ba.frozen?                     ba.instance_variables          ba.private_methods             ba.taint                       
-     ba.default_mission             ba.hash                        ba.is_a?                       ba.protected_methods           ba.tainted?                    
-     ba.display                     ba.id                          ba.kind_of?                    ba.public_methods              ba.to_a                        
-     ba.dup                         ba.inspect                     ba.line_buffer                 ba.respond_to?                 ba.to_s                        
-
-
-     # Since it's hard to see Bond::Agent's functionality amidst all the Object and Kernel methods, 
-     # let's autocomplete just it's instance methods.
-     >> Bond.complete(:object=>Bond::Agent) {|input| input.object.class.instance_methods(false) }
-     => true
-
-     # A less cluttered display of Bond::Agent's functionality.
-     >> ba.[TAB]
-     ba.call             ba.complete         ba.default_mission  ba.find_mission     ba.missions
-
-     # Let's have all Bond::* objects do this.
-     >> Bond.reset; Bond.complete(:object=>/^Bond::/) {|input| input.object.class.instance_methods(false) }
-     => true
-
-    # Let's revert method autocompletion back to irb's defaults for Bond::* objects.
-    >> Bond.reset; Bond.complete :object=>/^Bond::/
-    
-=== Underscore Search
-
-    # Firing up a rails console
-    bash> script/console
-    >> require 'bond'
-    => true
-
-    # Set all ActiveRecord::Base descendants to use the predefined underscore search
-    >> Bond.complete :object=>ActiveRecord::Base, :search=>:underscore
-    => true
-
-    # With this search we can still autocomplete the traditional way.
-    # Url is a model object
-    >> Url.first.tag_[TAB]
-    Url.first.tag_add_and_remove   Url.first.tag_and_save         Url.first.tag_ids=             Url.first.tag_list=            
-    Url.first.tag_add_and_save     Url.first.tag_ids              Url.first.tag_list             Url.first.tag_remove_and_save
-    >> Url.tag_ad[TAB]
-    >> Url.tag_add_and_
-    >> Url.tag_add_and_[TAB]
-    Url.first.tag_add_and_remove  Url.first.tag_add_and_save 
-    >> Url.tag_add_and_s[TAB]
-    >> Url.tag_add_and_save
-
-    # But this search goes the extra mile with textmate-like searching.
-    # Type just the first letter of each underscored word separated by '-'
-    >> Url.first.t-a-a-s[TAB]
-    >> Url.first.tag_add_and_save
-
-    # With this search, most multi-worded methods are just a few keystrokes away.
-    # If multiple methods match the underscore alias, it still autocompletes the beginning of the method:
-    >> Url.first.p[TAB]
-    Url.first.partial_updates                  Url.first.pretty_inspect                   Url.first.pretty_print_instance_variables  Url.first.public_methods
-    Url.first.partial_updates?                 Url.first.pretty_print                     Url.first.primary_key_prefix_type          
-    Url.first.pluralize_table_names            Url.first.pretty_print_cycle               Url.first.private_methods                  
-    Url.first.present?                         Url.first.pretty_print_inspect             Url.first.protected_methods
-    >> Url.first.p-p[TAB]
-    >> Url.first.pretty_print
-    >> Url.first.pretty_print_c[TAB]
-    >> Url.first.pretty_print_cycle
-
-
-=== Custom AutoCompletion
-
-    bash> irb -rirb/completion -rubygems -rbond
-    # Let's reuse the file completion from above
-    >> file_completion = proc {|input| (Readline::FILENAME_COMPLETION_PROC.call(input) ||
-        []).map {|f| f =~ /^~/ ?  File.expand_path(f) : f } }
-    => #< Proc:0x0100f1d0@(irb):1>
-
-    # But this time let's trigger it whenever the last word in the line is quoted
-    # fyi this is default behavior if you use irb without requiring irb/completion
-    >> Bond.complete(:on=>/\S+\s*["']([^'".]*)$/, :search=>false) {|input| file_completion.call(input.matched[1]) }
-    => true
-
-    # Now it doesn't matter what methods come before. If the last word is quoted we get file completion:
-    >> Dir.entries '[TAB]
-    .git/   LICENSE.txt   README.rdoc   Rakefile      VERSION.yml   bond.gemspec  ext/    lib/     test/
-    >> Dir.entries 'l[TAB]
-    >> Dir.entries 'lib/
-    >> `ls 't[TAB]
-    >> `ls 'test/
-    >> `ls 'test/'`
-
-    # String method completion still works
-    >> '007'.[TAB]
-    Display all 137 possibilities? (y or n)
+  Bond.start
+
+This gives you more consistent method completion on any object, customizable completions
+and argument completion of some 80+ methods including Hash#[], Kernel#system, Kernel#require and some Rails methods.
+
+== Method Argument Completion
+
+By default, Bond autocompletes arguments for a number of core methods:
+
+  $ irb
+  # require completes gems and anything in $LOAD_PATH
+  >> require 'rb[TAB]
+  rbconfig.rb          rbconfig/
+  >> require 'rbconfig
+  >> require 'rbconfig.rb'
+
+  # hash methods can complete their keys
+  >> CONFIG::CONFIG[TAB]
+  >> CONFIG::CONFIG['m[TAB]
+  >> CONFIG::CONFIG['mandir'
+  >> CONFIG::CONFIG['mandir']
+
+  >> ENV['CO[TAB]
+  COLUMNS       COMMAND_MODE
+  >> ENV['COL[TAB]
+  >> ENV['COLUMNS'
+  >> ENV['COLUMNS']
+
+  # array methods can complete their elements
+  >> %w{ab bc cd de}.delete '[TAB]
+  ab  bc  cd  de
+  >> %w{ab  bc  cd  de}.delete 'a[TAB]
+  >> %w{ab  bc  cd  de}.delete 'ab'
+
+  # system can complete shell commands
+  >> system 'ec[TAB]
+  >> system 'echo
+  >> system 'echo'
+
+Bond also comes with some basic Rails completions, mostly for attributes/columns of models:
+
+  $ script/console
+  >> Url.column_names
+  => ["id", "name", "description", "created_at", "updated_at"]
+  >> Url.create :n[TAB]
+  >> Url.create :name
+  ...
+  >> Url.first.update_attribute :d[TAB]
+  >> Url.first.update_attribute :description
+  ...
+
+To see more methods whose arguments can be completed:
+  >> puts Bond.list_methods
+  ActiveRecord::Base#[]
+  ActiveRecord::Base#attribute_for_inspect
+  ...
+
+== Multiple Arguments
+Every time a comma appears after a method, Bond starts a new completion. This allows a method to
+complete multiple arguments. *Each* argument can be have a unique set of completions since a completion action
+is aware of what argument it is currently completing. Take for example the completion for Object#send:
+
+  >> Bond.send :me[TAB]
+  >> Bond.send :method
+  >> Bond.send :method, [TAB]
+  agent       complete    config      recomplete  spy         start
+  >> Bond.send :method, :a[TAB]
+  >> Bond.send :method, :agent
+  => #<Method: Module#agent>
+
+Notice the arguments were completed differently: the first completing for Bond.send and the second for Bond.method. The second
+argument was only able to complete because there's a completion for Module#method. Using Object#send it's possible to
+use completions defined for private methods i.e. Module#remove_const:
+  >> Bond.send :remove_const, :A[TAB]
+  :Agent            :AnywhereMission
+  >> Bond.send :remove_const, :Ag[TAB]
+  >> Bond.send :remove_const, :Agent
+
+Since Bond uses a comma to delimit completions, methods whose last argument is a hash can have their hash keys
+autocompleted. Revisiting the above Rails example:
+  >> Url.create :n[TAB]
+  >> Url.create :name
+  >> Url.create :name=>'example.com', :d[TAB]
+  >> Url.create :name=>'example.com', :description
+  ...
+  >> Url.first.update_attributes :d[TAB]
+  >> Url.first.update_attributes :description
+  >> Url.first.update_attributes :description=>'zzz', :u[TAB]
+  >> Url.first.update_attributes :description=>'zzz', :updated_at
+  ...
+
+== Creating Completions
+Bond's completion resembles bash/zsh's. When Bond.start is called, Bond looks up completion files in multiple places:
+~/.bondrc and ~/.bond/completions/*.rb. Here's how bash and bond completion definitions compare in their config files:
+  # Bash
+  complete -W "one two three" example
+  complete -F _example example
+
+  # Bond
+  complete(:method=>'example') { %w{one two three} }
+  complete(:method=>'example', :action=>'_example')
+
+To read up on the wealth of completion types one can make, see the docs for Bond.complete.
+
+=== Creating Argument Completions for Methods
+While the above method completion was a static list, most completions will dynamically generate completions based on the method's
+receiver (object). Let's look at such an example with Hash#[] :
+  complete(:method=>"Hash#[]") {|e| e.object.keys }
+
+As you can see, the currently typed object is available as the :object attribute of the block's argument, a Bond::Input object.
+This object can offer other useful attributes describing what the user has typed. For example, the :argument attribute holds the
+current argument number being completed. Here's a completion that uses this attribute to complete differently for the first argument
+and remaining arguments:
+   complete(:method=>'example') {|e| e.argument > 1 ? %w{verbose force noop} : %w{one two three} }
+
+=== Creating Other Completions
+First you should know Bond works: A user creates completion missions with Bond.start and its config files (which are just
+Bond.complete calls). When a user autocompletes, Bond.agent looks up missions in the *order* they were defined and completes
+with the first one that matches. The exception to this ordering are :method completions.
+
+To create a completion, Bond.complete needs a regexp to match the user input and an action to generate completions when
+it matches. If the completion isn't working, use Bond.spy to see which completion is executing. If a completion needs to be placed
+before existing completions, use the :place option.
+
+== Irb's Incorrect Completions
+
+There are a number of incorrect completions irb gives for object methods. Bond fixes all of the ones described below.
+
+Irb completes anything surrounded with '{}' the same:
+
+  >> proc {}.c[TAB]
+  }.call     }.class    }.clear    }.clone    }.collect
+  >> %w{ab bc}.c[TAB]
+  }.call     }.class    }.clear    }.clone    }.collect
+  >> %r{ab bc}.c[TAB]
+  }.call     }.class    }.clear    }.clone    }.collect
+  >> {}.c[TAB]
+  }.call     }.class    }.clear    }.clone    }.collect
+  >> {}.call
+  NoMethodError: undefined method `call' for {}:Hash
+          from (irb):1
+
+There are a number of cases where irb gives a default completion because it doesn't know what else to do.
+  # The default completion
+  >> self.[TAB]
+  Display all 496 possibilities? (y or n)
+
+  # And all of these cases are apparently the same:
+  >> nil.[TAB]
+  Display all 496 possibilities? (y or n)
+  >> false.[TAB]
+  Display all 496 possibilities? (y or n)
+  >> true.[TAB]
+  Display all 496 possibilities? (y or n)
+  # Regular expressions with spaces
+  >> /man oh man/.[TAB]
+  Display all 496 possibilities? (y or n)
+  # Grouped expressions
+ >> (3 + 4).[TAB]
+ Display all 496 possibilities? (y or n)
+
+ # Nested hashes and arrays
+ >> {:a=>{:a=>1}}.[TAB]
+ Display all 496 possibilities? (y or n)
+ >> [[1,2], [3,4]].[TAB]
+ Display all 496 possibilities? (y or n)
+
+ # Any object produced from a method call
+ >> 'awesome'.to_sym.[TAB]
+ Display all 496 possibilities? (y or n)
+ >> :dude.to_s.[TAB]
+ Display all 496 possibilities? (y or n)
+ 
+Ranges don't get much love
+  >> (2..4).[TAB]
+  # Nothing happens
+
+== Limitations
+If on a Mac and using Editline as a Readline replacement (Readline::VERSION =~ /editline/i), Bond will probably not work consistently. I strongly recommend switching to the official Readline. If using rvm, {this post}[http://niwos.com/2010/03/19/rvm-on-osx-snow-leopard-readline-errors/]
+has good instructions for reinstalling ruby with the official Readline.
 
 == Credits
 Thanks to Csaba Hank for {providing the C extension}[http://www.creo.hu/~csaba/ruby/irb-enhancements/doc/files/README.html]
@@ -194,4 +213,7 @@ this Readline enhancement to ruby.
 * http://tagaholic.me/2009/07/23/mini-irb-and-mini-script-console.html
 
 == Todo
-* Allow usage of prefined Bond::Actions in action procs.
+* Load completions that come with a gem easily.
+* Make completion actions more synonymous with argument types.
+* Cache expensive completion actions.
+* Ensure completions work when there is additional, unrelated text to the right of a completion.

data/Rakefile

@@ -1,6 +1,4 @@
 require 'rake'
-require 'rake/testtask'
-require 'rake/rdoctask'
 begin
   require 'rcov/rcovtask'
 
@@ -11,15 +9,17 @@ begin
     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'
+  require File.dirname(__FILE__) + "/lib/bond/version"
+
   Jeweler::Tasks.new do |s|
     s.name = "bond"
+    s.version = Bond::VERSION
     s.summary = "Mission: Easy custom autocompletion for arguments, methods and beyond. Accomplished for irb and any other readline-like console environments."
-    s.description = "Bond is on a mission to make custom autocompletion easy in irb and other console/readline-like environments. Bond supports custom argument completion of methods, method completion of objects and anything else your wicked regex's can do. Bond comes armed with a Readline C extension to get the full line of input as opposed to irb's last-word based completion. Bond makes custom searching of possible completions easy which allows for nontraditional ways of autocompleting i.e. instant aliasing of multi worded methods."
+    s.description = "Bond is on a mission to improve irb’s autocompletion. Aside from doing everything irb’s can do and fixing its quirks, Bond can autocomplete argument(s) to methods, uniquely completing per module, per method and per argument. Bond brings irb’s completion closer to bash/zsh as it provides a configuration system and a DSL for creating custom completions and completion rules. With this configuration system, users can customize their irb autocompletions and share it with others. Bond is able to offer more than irb’s completion since it uses a Readline C extension to get the full line of input when completing as opposed to irb’s last-word approach."
     s.email = "gabriel.horner@gmail.com"
     s.homepage = "http://tagaholic.me/bond/"
     s.authors = ["Gabriel Horner"]
@@ -27,51 +27,15 @@ begin
     s.has_rdoc = true
     s.extra_rdoc_files = ["README.rdoc", "LICENSE.txt"]
     s.extensions = ["ext/readline_line_buffer/extconf.rb"]
-    s.files = FileList["CHANGELOG.rdoc", "Rakefile", "README.rdoc", "VERSION.yml", "LICENSE.txt", "{bin,lib,test,ext}/**/*"]
+    s.files = FileList["CHANGELOG.rdoc", "Rakefile", "README.rdoc", "LICENSE.txt", "{bin,lib,test,ext}/**/*"]
   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
 
-# I assume contributors can edit the gemspec for most attributes except for file-related ones.
-# For those attributes you can use the gemspec_update task. I prefer not to give you the gem-creator-specific rake
-# tasks I use to generate gemspecs to give you the choice of generating gemspecs however you'd like.
-# More about this here: http://tagaholic.me/2009/04/08/building-dry-gems-with-thor-and-jeweler.html .
-desc "Update gemspec from existing one by regenerating path globs specified in *.gemspec.yml or defaults to liberal path globs."
-task :gemspec_update  do
-  if (gemspec_file = Dir['*.gemspec'][0])
-    original_gemspec = eval(File.read(gemspec_file))
-    if File.exists?("#{gemspec_file}.yml")
-      require 'yaml'
-      YAML::load_file("#{gemspec_file}.yml").each do |attribute, globs|
-        original_gemspec.send("#{attribute}=", FileList[globs])
-      end
-    else
-      # liberal defaults
-      original_gemspec.files = FileList["**/*"]
-      test_directories = original_gemspec.test_files.grep(/\//).map {|e| e[/^[^\/]+/]}.compact.uniq
-      original_gemspec.test_files = FileList["{#{test_directories.join(',')}}/**/*"] unless test_directories.empty?
-    end
-    File.open(gemspec_file, 'w') {|f| f.write(original_gemspec.to_ruby) }
-    puts "Updated gemspec."
-  else
-    puts "No existing gemspec file found."
-  end
+desc 'Run specs with unit test style output'
+task :test do |t|
+  sh 'bacon -q -Ilib test/*_test.rb'
 end
-
-task :default => :test