lightning

== Description Lightning is a commandline framework that lets users wrap commands with shell functions that are able to refer to any filesystem path by its basename. To achieve this, a group of paths to be translated are defined with shell globs. These shell globs, known as a lightning bolt, are then applied to commands to produce functions. In addition to translating basenames to full paths, lightning functions can autocomplete these basenames, resolve conflicts if they have the same name, leave any non-basename arguments untouched, and autocomplete directories above and below a basename. To make bolts shareable between users and functions easier to create, lightning has generators. A generator generates filesystem-specific globs for a bolt. Lightning comes with some default generators. Users can make their own generators with generator plugins placed under ~/.lightning/generators/.

== Intro Lightning generates shell functions which can interpret paths by their basenames. So instead of carpal-typing

$ less /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/irb.rb

just type

$ less-ruby 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:

1112 available system ruby files

$ less-ruby [TAB] Display all 1112 possibilities? (y or n)

$ 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 ...

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 ...

And here's the one-liner that creates this function:

$ lightning function create less ruby && lightning-reload

== Install

Install with either rip or rubygems: $ rip install lightning

OR

$ gem install yard # if you want lightning's documentation generated correctly $ gem install lightning

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.

Once lightning is installed, we need to do a one-time setup:

To see available install options

$ lightning install -h

Installs lightning's core files and sources the needed lightning functions

$ lightning install && source ~/.lightning/functions.sh Created ~/.lightningrc Created ~/.lightning/functions.sh

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

To install and view lightning's man page:

If installed with rip, man pages are automatically installed

$ man lightning

If installed with rubygems

$ gem install gem-man $ gem man lightning

== Bugs/Issues Please report them {on github}[http://github.com/cldwalker/lightning/issues].

== Limitations

• 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.

== 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 influential in designing plugins
• Bug fixes: ljsc

== Links

• http://tagaholic.me/2010/04/08/lightning-speed-for-your-shell.html
• http://tagaholic.me/2010/04/09/lightning-speed-for-the-user.html

== Todo

• Possible aliasing of paths per function, bolt or global
• Possible irb builder using bond