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 git://github.com/cldwalker/lightning.git
  # OR
  $ sudo gem install yard # if you want lightning's documentation generated correctly
  $ sudo 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 ~/.lightning_yml
  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
  $ LDIR=`ruby -rrip -e 'puts Rip::PackageManager.new.package("lightning").cache_path'`
  # Assumes /usr/local/man is in $MANPATH
  $ cp $LDIR/man/lightning.1 /usr/local/man/man1/
  $ man lightning

  # If installed with rubygems
  $ sudo gem install gem-man
  $ gem man lightning

Bugs/Issues

Please report them on github.

Limitations

Credits

Links

Todo