lightning 0.2.1 → 0.3.0

data/CHANGELOG.rdoc

@@ -1,3 +1,12 @@
+== 0.3.0
+* Major refactoring
+* Added pluggable commands and generators
+* Added several commands to completely configure lightning from commandline
+* Improved autocompletion including white space escaping and remote completion
+* Added support for zsh
+* Added more thorough error handling
+* Switched to yardoc and bacon for docs + tests
+
 == 0.2.1
 * Rubyforge release
 * Removed monkey patches

data/README.rdoc

@@ -1,150 +1,78 @@
 == Description
+Lightning is a commandline framework that could revolutionize how fast you are on the commandline. Lightning let’s you easily define and generate shell functions which autocomplete and interpret paths (files and directories) by their basenames. With these functions you don’t have to ever type the full path to any file for any command again.
 
-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.
+== Intro
+Lightning generates shell functions which can interpret paths by their basenames. So instead of carpal-typing
 
-So instead of carpal-typing
+  $ less /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/irb.rb
 
-    bash> vim /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/irb.rb
+just type
 
-you type or complete
+  $ less-ruby irb.rb
 
-    bash> rvim irb.rb
+less-ruby is a lightning function which wraps `less` with the ability to refer to system ruby files by their basenames. Being a lightning function, it can also autocomplete system ruby files:
 
-Uneasy about what lightning will execute? Test/print it out with a -test flag
+  # 1112 available system ruby files
+  $ less-ruby [TAB]
+  Display all 1112 possibilities? (y or n)
 
-    bash> rvim -test irb.rb
-    rvim '/System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/irb.rb'
+  $ less-ruby a[TAB]
+  abbrev.rb                  abstract.rb                abstract_index_builder.rb
+  $ less-ruby abb[TAB]
+  $ less-ruby abbrev.rb
+  # Pages /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/abbrev.rb ...
 
-Want to autocomplete but don't remember how the basename starts? Just use a ruby regular expression:
+  # Autocompletion works regardless of the number of arguments
+  $ less-ruby -I abbrev.rb y[TAB]
+  yaml.rb      yamlnode.rb  ypath.rb
+  $ less-ruby -I abbrev.rb yp[TAB]
+  $ less-ruby -I abbrev.rb ypath.rb
+  # Pages /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/abbrev.rb and
+    /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/yaml/ypath.rb ...
 
-    # *'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.
+And here's the one-liner that creates this function:
 
+  $ lightning function create less ruby && lightning-reload
 
 == 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.
+Install with either rip or rubygems:
+  $ rip install git://github.com/cldwalker/lightning.git
+  # OR
+  $ sudo gem install yard # if you want lightning's documentation generated correctly
+  $ sudo gem install lightning
 
-   Dir.glob("/painfully/long/path/*.{rb,erb}") -> Matches files ending with .rb or .erb
+If you've installed with rubygems and `time lightning` takes longer than 0.05 seconds, I *strongly recommend* installing with rip. Your startup time directly effects your autocompletion speed with lightning.
 
-3. Autocomplete all directories however many levels deep under the current directory.
+Once lightning is installed, we need to do a one-time setup:
 
-   Dir.glob("**/")
+  # To see available install options
+  $ lightning install -h
 
-`ri Dir.glob` for more examples.
+  # Installs lightning's core files and sources the needed lightning functions
+  $ lightning install && source ~/.lightning/functions.sh
+  Created ~/.lightning_yml
+  Created ~/.lightning/functions.sh
 
-== Aliases
+  # To have lightning's functionality loaded when your shell starts up
+  echo source ~/.lightning/functions.sh >> ~/.bashrc
+  # or for zsh
+  echo source ~/.lightning/functions.sh >> ~/.zshrc
 
-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.
+== Bugs/Issues
+Please report them {on github}[http://github.com/cldwalker/lightning/issues].
 
 == 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
+* Completions that are a directory above or below a basename don't work for zsh.
+* Only bash and zsh shells are supported. Patches are welcome to support other shells.
 
-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.
+== Credits
+* ryanb's dotfiles inspired tinkering with autocompletion in ruby: http://github.com/ryanb/dotfiles/blob/master/bash/completion_scripts/project_completion
+* defunkt's rip, http://github.com/defunkt/rip, was inflential in designing plugins
 
 == 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
+* More tests
+* Manpage
+* Consider underscore anchored autocompletion i.e. textmate style file search
+* Possible aliasing of paths per function, bolt or global
+* Possible irb builder using bond

data/Rakefile

@@ -1,6 +1,4 @@
 require 'rake'
-require 'rake/testtask'
-require 'rake/rdoctask'
 begin
   require 'rcov/rcovtask'
 
@@ -11,21 +9,24 @@ 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/lightning/version"
+
   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.version = Lightning::VERSION
+    s.executables = ['lightning', 'lightning-complete', 'lightning-translate']
+    s.summary = "Lightning is a commandline framework that generates shell functions which wrap around commands to autocomplete and translate full paths by their basenames."
+    s.description = "Lightning is a commandline framework that changes how you use paths in your filesystem. Lightning generates shell functions which wrap any command with the ability to autocomplete and interpret paths simply by their basenames. With these functions you don't have to ever type the full path to any file for any command again."
     s.email = "gabriel.horner@gmail.com"
-    s.homepage = "http://github.com/cldwalker/lightning"
+    s.homepage = "http://tagaholic.me/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.files =  FileList["CHANGELOG.rdoc", "Rakefile","README.rdoc", "LICENSE.txt", "{bin,lib,test}/**/*"]
+    s.has_rdoc = 'yard'
+    s.rdoc_options = ['--title', "Lightning #{Lightning::VERSION} Documentation"]
     s.rubyforge_project = 'tagaholic'
     s.extra_rdoc_files = ["README.rdoc", "LICENSE.txt"]
   end
@@ -34,36 +35,9 @@ 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
+task :default => :test
 
-  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
+desc 'Run specs with unit test style output'
+task :test do |t|
+  sh 'bacon -q -Ilib test/*_test.rb'
 end
-
-task :default => :test

data/bin/lightning

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.join(File.dirname(__FILE__), "..","lib","lightning"))
+Lightning::Commands.run

data/bin/lightning-complete

@@ -1,13 +1,4 @@
 #!/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
+Lightning::Commands.run_command :complete, ARGV

data/bin/lightning-translate

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.join(File.dirname(__FILE__), "..","lib","lightning"))
+Lightning::Commands.run_command :translate, ARGV

data/lib/lightning.rb

@@ -1,68 +1,54 @@
-$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__))
-require 'yaml'
 require 'lightning/bolt'
-require 'lightning/bolts'
+require 'lightning/util'
+require 'lightning/commands_util'
+require 'lightning/commands'
 require 'lightning/completion'
 require 'lightning/config'
+require 'lightning/function'
 require 'lightning/completion_map'
+require 'lightning/builder'
+require 'lightning/generators'
 require 'lightning/generator'
+require 'lightning/version'
 
-class Lightning
-  TEST_FLAG = '-test'
+module Lightning
   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)
+    attr_accessor :config, :functions
+
+    # @return [Config] Contains all user configuration
+    def config
+      @config ||= Config.new
     end
-    
-    def config=(value)
-      @config = Config.new(value)
+
+    # @return [Hash] Maps bolt names to Bolt objects
+    def bolts
+      @bolts ||= Hash.new {|h,k| h[k] = Bolt.new(k) }
     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
+
+    # @return [Hash] Maps function names to Function objects
+    def functions
+      @functions ||= create_functions
     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'
+
+    # @return [String] Directory for most of lightning's files, ~/.lightning
+    def dir
+      @dir ||= begin
+        require 'fileutils'
+        FileUtils.mkdir_p File.join(home, '.lightning')
+        File.join(home, '.lightning')
       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
+    # @return [String] User's home directory, ~
+    def home
+      @home ||= Util.find_home
     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
+    protected
+    def create_functions
+      config.bolts.inject({}) {|h,(k,v)|
+        bolts[k].generate_functions.each {|f| h[f['name']] = Function.new(f) } ; h
+      }
     end
   end
 end

data/lib/lightning/bolt.rb

@@ -1,33 +1,60 @@
-# A bolt, referenced by a key, is the basic unit needed to access a lightning command's functionality.
-class Lightning
+module Lightning
+  # A Bolt object is mainly a user-defined set of globs required by a {Function} object to translate paths.
+  #
+  # == Globs
+  # Globs are interpreted by Dir.glob and are fairly similar to shell globs. Some glob examples:
+  #
+  # * Files ending with specific file extensions for a given directory.
+  #    "/some/path/*.{rb,erb}"-> Matches files ending with .rb or .erb
+  #
+  # * Files and directories that don't start with specific letters.
+  #    "[^ls]*" -> Matches anything not starting with l or s
+  #
+  # * All directories, however many levels deep, under the current directory.
+  #    "**/"
   class Bolt
-    attr_reader :key
-    def initialize(bolt_key)
-      @key = bolt_key
+    # @return [String] Unique alphanumeric name
+    attr_reader :name
+    # @return [Hash] Maps aliases to full paths. Aliases are valid for a bolt's functions
+    attr_reader :aliases
+    # @return [Boolean] When true adds global commands to list of commands used to generate a bolt's functions
+    attr_reader :global
+    # @return [Array] User-defined globs that are translated by Dir.glob().
+    attr_accessor :globs
+    # Used to generate functions.
+    # @return [Array<Hash, String>] An array element can be a hash of function attributes or a shell command
+    attr_accessor :functions
+    def initialize(name)
+      @name = name
+      @globs = []
+      @functions = []
+      @aliases = {}
+      (Lightning.config.bolts[@name] || {}).each do |k,v|
+        instance_variable_set("@#{k}", v)
+      end
     end
-    
-    def completions
-      completion_map.keys
+
+    # Generates functions from a bolt's functions and global shell commands
+    # @return [Array]
+    def generate_functions
+      @functions += Lightning.config.global_commands if @global
+      @functions.inject({}) {|acc, e|
+        cmd = e.is_a?(Hash) ? e.dup : {'shell_command'=>e}
+        cmd['bolt'] = self
+        cmd['name'] ||= function_name(cmd['shell_command'])
+        acc[cmd['name']] ||= cmd if cmd['shell_command']
+        acc
+      }.values
     end
-    
-    def completion_map
-      @completion_map ||= Lightning::CompletionMap.new(self.paths,
-        :global_aliases=>Lightning.config[:aliases], 
-        :aliases=>Lightning.config_command(Lightning.current_command)['aliases'])
+
+    # Creates function name for a bolt given a shell command
+    def function_name(scmd)
+      Lightning.config.function_name(scmd, alias_or_name)
     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] || []
+
+    protected
+    def alias_or_name
+      @alias || @name
     end
   end
 end