lightning 0.2.1

data/CHANGELOG.rdoc

@@ -0,0 +1,13 @@
+== 0.2.1
+* Rubyforge release
+* Removed monkey patches
+
+== 0.2.0
+* Added regex completion
+* Added global and local aliases
+
+== 0.1.2
+* Major refactoring
+
+== 0.1.1
+* 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,150 @@
+== Description
+
+Autocomplete a group of files and directories simply by listing their globbable paths
+in a config file. Generate completions from your config, source them into your shell
+and you're ready to rock.
+
+So instead of carpal-typing
+
+    bash> vim /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/irb.rb
+
+you type or complete
+
+    bash> rvim irb.rb
+
+Uneasy about what lightning will execute? Test/print it out with a -test flag
+
+    bash> rvim -test irb.rb
+    rvim '/System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/irb.rb'
+
+Want to autocomplete but don't remember how the basename starts? Just use a ruby regular expression:
+
+    # *'s are converted to .*'s for convience sakes
+    bash> rvim *dialog [TAB TAB]
+    canvasprintdialog.rb
+    extfileselectiondialog.rb
+    dialog.rb//System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/tk
+    fileselectiondialog.rb
+    dialog.rb//System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/tkextlib/bwidget
+    finddialog.rb
+
+    #re-edit your line to narrow down your completion to one entry
+    bash> rvim ca*dialog [TAB TAB]
+
+    #once the basename completes, you can execute your command
+    bash> rvim canvasprintdialog.rb
+
+As you can see, you only need to autocomplete the basenames of paths and lightning will resolve their
+full paths.  In these examples, rvim is a lightning command configured to autocomplete a certain group of paths for vim.
+In my case, rvim is configured to complete my ruby core and standard library files.
+
+
+== Install
+
+For newcomers to github, install this gem with: `gem install lightning`
+
+To make your own commands, you'll need to:
+
+1. Create ~/.lightning.yml or a lightning.yml in the current directory.
+   Use the Configuration section below and the provided lightning.yml.example as guides.
+
+2. Execute `lightning-install` to generate ~/.lightning_completions from your config.
+   There is a config option for changing the location of the generated file. See Configuration
+   below. See lightning_completions.example for what would be generated for the enclosed example
+   config.
+
+3. Source the generated file in your bashrc ie `source ~/.lightning_completions`.
+
+
+== Globbable Paths
+
+Since the globbable paths are interpreted by ruby's Dir.glob(), you can:
+
+1. Autocomplete files and directories that don't start with specific letters.
+
+   Dir.glob("[^ls]*") -> Matches anything not starting with l or s
+
+2. Autocomplete files ending with specific file extensions for a given directory.
+
+   Dir.glob("/painfully/long/path/*.{rb,erb}") -> Matches files ending with .rb or .erb
+
+3. Autocomplete all directories however many levels deep under the current directory.
+
+   Dir.glob("**/")
+
+`ri Dir.glob` for more examples.
+
+== Aliases
+
+Lightning supports custom aliases for any path, globally and per command. So if there is some
+path that you access often but that's still too slow with completion, alias it away!
+
+== Configuration
+
+It helps to look at lightning.yml.example while reading this.
+
+Configuration options are:
+
+* generated_file: Location of shell script file generated from config. Defaults to
+  ~/.lightning_completions.
+* ignore_paths: List of paths to globally ignore when listing completions.
+* complete_regex: true or false (default is true)
+  Turns on/off Ruby regular expression matching when completing. One convience
+  is that a '*' is converted to '.*' ie glob-like behavior.
+
+  Note: Realize your regular expression normally just match the basename. However, since duplicates
+  list their full paths, their full paths are subject to regex matching.
+* shell: Specifies shell script generator used for generating completions. Defaults to bash.
+* aliases: A hash (pairs) of custom aliases pointing to full paths. These aliases will be globally
+  recognized by any lightning command.
+* commands: A list of lightning commands. A lightning command is just a shell function
+  which executes a specified shell function with a defined set of paths to autocomplete on.
+  A command consists of the following options/keys:
+  
+  * name (required): Name of the lightning command you'll be typing.
+  * map_to (required): Shell command which the lightning command passes arguments to.
+  * description: Description which is placed as a comment in the generated shell script.
+  * paths (required): A list of globbable paths, whose basenames are autocompleted. You can also
+    pass this a path name that has been defined in the paths option. 
+  * aliases: A hash (pairs) of custom aliases and full paths only for this command.
+
+* paths: This takes a hash (pairs) of path names and globbable paths. This should be used when
+  you have a group of paths that are used in multiple commands. When doing that, you would specify
+  the path name defined here in the command's paths key.
+  Note: path names should only be alphanumeric
+
+* post_path: Text to add immediately after a resolved path. lightning.yml.example contains
+  an example used for opening gem documentation in your browser.
+
+== Duplicate Basenames
+
+So what happens when their are multiple matches for the same basename?
+Lightning appends a '/' + the full directory to each of the basenames.
+
+For example, if I autocomplete button.rb for my ruby standard libraries I get:
+
+      bash> rvim button.rb
+      button.rb//System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/tk
+      button.rb//System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/tkextlib/bwidget
+      button.rb//System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/tkextlib/blt/tile
+
+This isn't the prettiest completion but it resolves duplicates, displays the path differences
+between each and easily autocompletes. I'm open to suggestions on this syntax.
+
+== Limitations
+* The generated shell scripts default to bash but could easily be extended for other shell languages. Patches welcome.
+* All arguments passed to a lightning command are considered part of the basename to resolve. So
+  it's not yet possible to resolve some arguments and not others.
+
+== Motivation
+
+I've seen dotfiles on github and on blogs which accomplish this kind of autocompletion for gem
+documentation. There's even a gem just for gem editing: http://gemedit.rubyforge.org/.
+But once I saw how easy it was to manipulate completion through ruby,
+http://github.com/ryanb/dotfiles/blob/master/bash/completion_scripts/project_completion,
+I had to do something.
+
+== Todo
+* Binary to interact with common config operations including add/remove current directory or globs from a command
+* Allow lightning commands to only path-resolve one of multiple arguments given.
+* An irb generator

data/Rakefile

@@ -0,0 +1,69 @@
+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 = "lightning"
+    s.executables = ["lightning-complete", "lightning-full_path", "lightning-install"]
+    s.summary = "Path completions for your shell that will let you navigate like lightning."
+    s.description = "Lightning creates shell commands that each autocomplete to a configured group of files and directories. Autocompleting is quick since you only need to type the basename and can even use regex completion." 
+    s.email = "gabriel.horner@gmail.com"
+    s.homepage = "http://github.com/cldwalker/lightning"
+    s.authors = ["Gabriel Horner"]
+    s.files =  FileList["CHANGELOG.rdoc", "Rakefile", "VERSION.yml", "lightning_completions.example", "lightning.yml.example","README.rdoc", "LICENSE.txt", "{bin,lib,test}/**/*"]
+    s.has_rdoc = true
+    s.rubyforge_project = 'tagaholic'
+    s.extra_rdoc_files = ["README.rdoc", "LICENSE.txt"]
+  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
+
+namespace :dev do
+  desc "Generates completion, modifies it for local development"
+  task :reload=>:generate_completions do
+    file = 'lightning_completions'
+    string = File.read(file)
+    string.sub!(/^LBIN_PATH/,'#LBIN_PATH')
+    string.sub!(/^#LBIN_PATH/,'LBIN_PATH')
+    File.open(file,'w') {|f| f.write(string) }
+  end
+
+  desc "Generates local completion file to be sourced by your shell"
+  task :generate_completions do
+    $:.unshift 'lib'
+    require 'lightning'
+    Lightning::Generator.generate_completions 'lightning_completions'
+  end
+end
+
+task :default => :test

data/VERSION.yml

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

data/bin/lightning-complete

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+#  == Description
+#  Used to complete a lightning command
+require File.expand_path(File.join(File.dirname(__FILE__), "..","lib","lightning"))
+
+if (command = ARGV.shift)
+  puts Lightning.complete(command, ENV["COMP_LINE"])
+  exit 0
+else
+  puts "No command given"
+  exit 1
+end

data/bin/lightning-full_path

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+
+# == Description
+# Used by path completion functions to return first possible full path which matches the given basename for the given command.
+
+require File.expand_path(File.join(File.dirname(__FILE__), "..","lib","lightning"))
+
+command = ARGV.shift 
+if command.nil?
+  puts "No command given"
+  exit 1
+end
+if ARGV.empty?
+  puts "No arguments given" 
+  exit 1
+end
+puts Lightning.translate(command, ARGV)
+exit 0

data/bin/lightning-install

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+# == Description
+# Used to generate shell file from configuration
+
+require File.expand_path(File.join(File.dirname(__FILE__), "..","lib","lightning"))
+Lightning::Generator.generate_completions ARGV.shift

data/lib/lightning.rb

@@ -0,0 +1,68 @@
+$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__))
+require 'yaml'
+require 'lightning/bolt'
+require 'lightning/bolts'
+require 'lightning/completion'
+require 'lightning/config'
+require 'lightning/completion_map'
+require 'lightning/generator'
+
+class Lightning
+  TEST_FLAG = '-test'
+  class<<self
+    attr_accessor :current_command
+    def config(options={})
+      @config ||= Config.create(options)
+    end
+    
+    def load_read_only_config
+      @config = Config.create(:read_only=>true)
+    end
+    
+    def config=(value)
+      @config = Config.new(value)
+    end
+    
+    def complete(command, text_to_complete)
+      load_read_only_config
+      @current_command = command
+      if bolt_key = config_command(command)['bolt_key']
+        Completion.complete(text_to_complete, bolt_key)
+      else
+        ["#Error: No paths found for this command.", "If this is a bug contact me."]
+      end
+    end
+    
+    def translate(command, argv)
+      load_read_only_config
+      @current_command = command
+      if bolt_key = config_command(command)['bolt_key']
+        bolts[bolt_key].resolve_completion(argv)
+      else
+        '#Error-no_paths_found_for_this_command'
+      end
+    end
+    
+    def bolts
+      @bolts ||= Bolts.new
+    end
+
+    def config_command(name, hardcheck=false)
+      command = config[:commands].find {|e| e['name'] == name} || {}
+      if hardcheck && command.empty?
+        puts "Command '#{name}' not found"
+        nil
+      else
+        command
+      end
+    end
+
+    def ignore_paths
+      unless @ignore_paths
+        @ignore_paths = []
+        @ignore_paths += config[:ignore_paths] if config[:ignore_paths] && !config[:ignore_paths].empty?
+      end
+      @ignore_paths
+    end
+  end
+end

data/lib/lightning/bolt.rb

@@ -0,0 +1,33 @@
+# A bolt, referenced by a key, is the basic unit needed to access a lightning command's functionality.
+class Lightning
+  class Bolt
+    attr_reader :key
+    def initialize(bolt_key)
+      @key = bolt_key
+    end
+    
+    def completions
+      completion_map.keys
+    end
+    
+    def completion_map
+      @completion_map ||= Lightning::CompletionMap.new(self.paths,
+        :global_aliases=>Lightning.config[:aliases], 
+        :aliases=>Lightning.config_command(Lightning.current_command)['aliases'])
+    end
+    
+    def resolve_completion(basename)
+      basename = basename.join(" ") if basename.is_a?(Array)
+      basename.gsub!(/\s*#{TEST_FLAG}\s*/,'')
+      #TODO
+      # if (regex = Lightning.config_command(Lightning.current_command)['completion_regex'])
+      #   basename = basename[/#{regex}/]
+      # end
+      completion_map[basename] || ''
+    end
+    
+    def paths
+      @paths ||= Lightning.config[:paths][key] || []
+    end
+  end
+end

data/lib/lightning/bolts.rb

@@ -0,0 +1,12 @@
+# Hash of bolts accessed by their keys
+class Lightning
+  class Bolts
+    def initialize
+      @hash = {}
+    end
+  
+    def [](key)
+      @hash[key] ||= Lightning::Bolt.new(key)
+    end    
+  end
+end

data/lib/lightning/commands.rb

@@ -0,0 +1,92 @@
+class Lightning
+  # TODO: Provide commands for the lightning binary.
+  module Commands
+    # @options :search=>:string, :command=>:string
+    def lightning_command(*args)
+      puts "Lightning Commands"
+      if options[:command]
+        lightning_commands = Lightning.config[:commands].select {|e| e['map_to'] == options['command']}
+      else
+        lightning_commands = Lightning.config[:commands]
+      end
+      puts lightning_commands.map {|e| e['name'] }.join("\n")
+    end
+
+    #@options :add=>:boolean, :delete=>:boolean
+    def path(*args)
+      command_name = args.shift
+      if options['delete']
+        return puts("Path needed") if args[0].nil?
+        delete_path(command_name, args[0])
+      elsif options['add']
+        return puts("Path needed") if args[0].nil?
+        add_path(command_name, args[0])
+      else
+        puts "Paths for command '#{command_name}'"
+        puts config_command_paths(command_name).join("\n")
+      end
+    end
+
+    #@options :delete=>:boolean, :add=>:boolean, :global=>:boolean
+    def alias(*args)
+      if options['delete']
+        delete_command_alias(*args.slice(0,2))
+      elsif options['add']
+        add_command_alias(*args.slice(0,3))
+      else
+        puts "Aliases"
+        (Lightning.config[:aliases] || []).each do |path_alias, path|
+          puts "#{path_alias} : #{path}"
+        end
+      end
+    end
+
+    private
+    def config_command_paths(name)
+      if command = Lightning.config_command(name, true)
+        if command['paths'].is_a?(String)
+           Lightning.config[:paths][command['paths']]
+        else
+          command['paths']
+        end
+      else
+        []
+      end
+    end
+
+    def add_command_alias(command_name, path_alias, path)
+      if (command = Lightning.config_command(command_name, true))
+        path = File.expand_path(path)
+        command['aliases'][path_alias] = path
+        Lightning.config.save
+        puts "Path alias '#{path_alias}' added"
+      end
+    end
+
+    def delete_command_alias(command_name, path_alias)
+      if (command = Lightning.config_command(command_name, true))
+        command['aliases'].delete(path_alias)
+        Lightning.config.save
+        puts "Path alias '#{path_alias}' deleted"
+      end
+    end
+
+    def add_path(command_name, path)
+      if (command = Lightning.config_command(command_name, true))
+        path = File.expand_path(path)
+        config_command_paths(command_name) << path
+        Lightning.config.save
+        puts "Path '#{path}' added"
+      end
+    end
+
+    def delete_path(command_name, path)
+      if (command = Lightning.config_command(command_name, true))
+        path = File.expand_path(path)
+        config_command_paths(command_name).delete(path)
+        Lightning.config.save
+        puts "Path '#{path}' deleted"
+      end
+    end
+  end
+end