lightning 0.3.1 → 0.3.2

data/man/lightning.1.ronn

@@ -0,0 +1,167 @@
+lightning(1) -- Speed for your shell
+====================================
+
+## SYNOPSIS
+
+    lightning [-h|--help] [-v|--version] COMMAND [ARGS]
+
+## DESCRIPTION
+
+`lightning` is a commandline framework that lets users wrap commands with shell functions that are able to refer (translate) 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/.
+
+## COMMANDS
+
+`lightning` comes with the following commands, some which have subcommands. Commands and subcommands can be abbreviated i.e. 'function create grep ruby' -> 'f c grep ruby'. Users can define their own commands by placing command plugins under ~/.lightning/commands/.
+
+* `bolt`:
+  Commands for managing bolts. Defaults to listing them.
+* `complete`:
+  Prints a function's completions based on the last argument.
+
+* `function`:
+  Commands for managing functions. Defaults to listing them.
+* `generator`:
+  Lists available generators.
+* `install`:
+  Builds shell functions and installs them into FILE to be sourced by shell.
+* `shell_command`:
+  Commands for managing shell commands. Defaults to listing them.
+* `translate`:
+  Translates each argument and prints it on a separate line.
+
+## CREATE FUNCTIONS
+
+There are two nonexclusive ways of creating functions. The first involves combining bolts with individual shell commands. Here are the steps involved:
+
+* Create a bolt with shell globs. This step can be skipped if a bolt has a generator with the same name.
+    # Globs are quoted to prevent filename expansion.
+    $ lightning bolt create code '~/code/fork/\*' '~/code/gems/\*'
+    Created bolt 'code'
+
+* Create function(s) for that bolt by applying to shell commands.
+    $ lightning function create cd code
+    Created function 'cd-code'
+    $ lightning function create grep code
+    Created function 'grep-code'
+* Generate and load functions into shell
+    $ lightning-reload
+    Created ~/.lightning/function.sh
+    Loaded ~/.lightning/function.sh
+
+The second, more brute-force way of creating functions is to make global functions. Global functions are made from combining each global bolt with each global shell command. For example, 4 global bolts combined with 7 global commands will make 28 global functions.
+
+  # First make bolts global since bolts aren't global by default
+  $ lg bolt global on python clojure ruby
+  Global on for bolts python, clojure, ruby
+
+  # Then add the global commands
+  $ lg shell_command create vim
+  Created shell command 'vim'
+  $ lg shell_command create grep
+  Created shell command 'grep'
+  $ lightning-reload
+
+  # Verify global functions
+  $ lightning function list
+  grep-clojure
+  grep-python
+  grep-ruby
+  vim-clojure
+  vim-python
+  vim-ruby
+
+## LIGHTNINGRC
+
+`lightning`'s configuration is stored in ~/.lightningrc as YAML. Since it's human readable it's easy to modify. However, `lightning` depends on this file to function and will fail if the file has a syntax error. Modifying this file is only recommended if you need to modify existing functions, bolts or global commands in a way that the lightning commands can't. To read up on the config file format see _http://tagaholic.me/lightning/doc/Lightning/Config.html_.
+
+## INSTALLATION
+
+Install with either rip or rubygems:
+  $ rip install git://github.com/cldwalker/lightning.git
+  # OR
+  $ sudo gem install yard # to install documentation correctly
+  $ sudo gem install lightning
+
+If you've installed with rubygems and the command `time lightning` takes longer than 0.05 seconds, I *strongly recommend* installing with rip, http://hellorip.com. 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
+  $ 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
+
+## EXAMPLES
+
+Get help on any command:
+
+  $ lightning function -h
+  $ lightning bolt -h
+
+List functions:
+
+  # All functions
+  $ lightning function list
+  # All functions from ruby bolt
+  $ lightning function list --bolt=ruby
+  # All functions from global command echo
+  $ lightning function list --command=echo
+
+Regenerate functions and source them into the shell:
+
+  # Call every time for changes to bolts and functions to take effect
+  $ lightning-reload
+
+Manage global shell commands:
+
+  $ lightning shell_command list
+  $ lightning shell_command create cd
+  $ lightning shell_command delete cd
+
+Manage/edit bolts:
+
+  $ lightning bolt list
+  $ lightning bolt delete ruby
+  $ lightning bolt alias ruby r
+  $ lightning bolt global off ruby gem local_ruby
+
+Generate a bolt using a generator:
+
+  # Generates ruby bolt with ruby generator
+  $ lightning bolt generate ruby
+  # Generates ruby19 bolt with ruby generator
+  $ lightning bolt generate ruby19 ruby
+  # Test what ruby bolt generates
+  $ lightning bolt generate ruby --test
+
+Test what a function will execute:
+
+  # Normal execution
+  $ cp-gem -r rubygems-update-1.3.6 .
+  # Prints cp-gem's translated arguments, one per line
+  $ lightning translate cp-gem -r rubygems-update-1.3.6 .
+  -r
+  /Library/Ruby/Gems/1.8/gems/rubygems-update-1.3.6
+  .
+
+## BUGS
+
+Please report bugs at _http://github.com/cldwalker/lightning/issues_.
+
+## COPYRIGHT
+
+`lightning` is Copyright (C) 2010 Gabriel Horner
+
+## SEE ALSO
+
+<http://tagaholic.me/lightning>, <http://tagaholic.me/lightning/doc/>, <http://github.com/cldwalker/lightning>

data/test/bolt_commands_test.rb

@@ -0,0 +1,119 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+context "bolt command" do
+  def bolt(*args)
+    run_command :bolt, args
+  end
+
+  def command_wont_find(bolt)
+    mock(Commands).puts "Can't find bolt '#{bolt}'"
+  end
+
+  def create_bolt(bolt='abcd')
+    config.bolts[bolt] = Lightning::Config.bolt(['/a/b/c/d'])
+  end
+
+  test 'list lists bolts' do
+    mock(Commands).puts config.bolts.keys.sort
+    bolt 'list'
+  end
+
+  test 'list lists bolts and aliases with --alias' do
+    mock(Commands).print_sorted_hash({"app"=>nil, "wild_dir"=>"w"})
+    bolt 'list', '--alias'
+  end
+
+  test 'alias aliases a bolt' do
+    create_bolt
+    mock(Commands).save_and_say /Aliased.*'abcd'.*'ab'/
+    bolt 'alias', 'abcd', 'ab'
+    config.bolts['abcd']['alias'].should == 'ab'
+  end
+
+  test "alias prints error for nonexistent bolt" do
+    command_wont_find 'zzz'
+    bolt 'alias', 'zzz', 'z'
+  end
+
+  test "create creates a bolt" do
+    mock(Commands).save_and_say /Created.*'blah'/
+    paths = '/some/path', '/some/path2'
+    bolt 'create', 'blah', *paths
+    config.bolts['blah'] = Lightning::Config.bolt(paths)
+  end
+
+  test 'delete deletes a bolt' do
+    mock(Commands).save_and_say /Deleted.*'blah'/
+    bolt 'delete', 'blah'
+    config.bolts['blah'].should.be.nil
+  end
+
+  test 'delete prints error for nonexistent bolt' do
+    command_wont_find 'zzz'
+    bolt 'delete', 'zzz'
+  end
+
+  test "generate generates bolt" do
+    mock(Generator).run('ruby19', :once=>'ruby', :test=>nil)
+    bolt 'generate', 'ruby19', 'ruby'
+  end
+
+  test "generate test generates bolt with --test" do
+    mock(Generator).run('ruby19', :once=>'ruby', :test=>true)
+    bolt 'generate', 'ruby19', 'ruby', '--test'
+  end
+
+  test 'show shows bolt' do
+    create_bolt
+    mock(Commands).puts(/globs:.*c\/d/m)
+    bolt 'show', 'abcd'
+  end
+
+  test 'show shows bolt given alias' do
+    create_bolt
+    config.bolts['abcd']['alias'] = 'ab'
+    mock(Commands).puts(/globs:.*c\/d.*alias: ab/m)
+    bolt 'show', 'ab'
+  end
+
+  test 'show prints error for nonexistent bolt' do
+    command_wont_find 'zzz'
+    bolt 'show', 'zzz'
+  end
+
+  test 'global prints error if first argument invalid' do
+    mock(Commands).puts(/First argument must be/)
+    bolt 'global', 'zero', 'ok'
+  end
+
+  context 'global' do
+    before_all {create_bolt('foo'); create_bolt('bar') }
+
+    test 'sets bolts on' do
+      mock(Commands).save_and_say /Global on.* foo, bar/
+      bolt 'global', 'on', 'foo', 'bar'
+      config.bolts['foo']['global'].should == true
+      config.bolts['bar']['global'].should == true
+    end
+
+    test 'on prints error for nonexistent bolt' do
+      command_wont_find 'far'
+      mock(Commands).save_and_say /Global on.* foo/
+      bolt 'global', 'on', 'foo', 'far'
+    end
+
+    test 'sets bolts off' do
+      mock(Commands).save_and_say /Global off.* foo, bar/
+      bolt 'global', 'off', 'foo', 'bar'
+      config.bolts['foo']['global'].should == nil
+      config.bolts['bar']['global'].should == nil
+    end
+
+    test 'off prints error for nonexistent bolt' do
+      command_wont_find 'far'
+      mock(Commands).save_and_say /Global off.* foo/
+      bolt 'global', 'off', 'foo', 'far'
+    end
+    after_all { config.bolts.delete('bar'); config.bolts.delete('foo') }
+  end
+end

data/test/bolt_test.rb

@@ -1,7 +1,14 @@
 require File.join(File.dirname(__FILE__), 'test_helper')
 
 # depends on test/lightning.yml
-context "Bolt generates correct command from" do
+context "Bolt generates functions from" do
+  test "non-global bolt" do
+    config.bolts['wild_dir']['functions'] = ['mv']
+    Lightning.functions['mv-w'].is_a?(Function).should == true
+    Lightning.functions.delete('mv-w')
+    config.bolts['wild_dir'].delete('functions')
+  end
+
   assert "shell command" do
     Lightning.functions['less-app'].is_a?(Function)
   end

data/test/builder_test.rb

@@ -2,7 +2,7 @@ require File.join(File.dirname(__FILE__), 'test_helper')
 
 context "Builder" do
   def build
-    Lightning.config.source_file = source_file
+    config.source_file = source_file
     Builder.run
   end
 
@@ -11,16 +11,16 @@ context "Builder" do
   end
 
   test "prints error when unable to build" do
-    Lightning.config[:shell] = 'blah'
+    config[:shell] = 'blah'
     capture_stdout { build }.should =~ /No.*exists.*blah shell/
-    Lightning.config[:shell] = nil
+    config[:shell] = nil
   end
 
   test "with non-default shell builds" do
-    Lightning.config[:shell] = 'zsh'
+    config[:shell] = 'zsh'
     mock(Builder).zsh_builder(anything) { '' }
     build
-    Lightning.config[:shell] = nil
+    config[:shell] = nil
   end
 
   test "warns about existing commands being overridden" do

data/test/commands_test.rb

@@ -1,71 +1,43 @@
 require File.join(File.dirname(__FILE__), 'test_helper')
 
 context "Commands:" do
-  # this test seems to run much longer than expected i.e. 0.02
-  # rr and raising?
   test "run_command handles unexpected error" do
     mock($stderr).puts(/^Error: Unexpected/)
     mock(Commands).complete(anything) { raise "Unexpected" }
     run_command :complete
   end
 
-  test "complete defaults to ARGV if no ENV['COMP_LINE']" do
-    mock(Completion).complete('o-a Col', anything)
-    capture_stdout { run_command(:complete, ['o-a', 'Col']) }
+  test "generic command prints usage with -h" do
+    capture_stdout { run_command :install, ['-h'] }.should =~ /^Usage/
   end
 
-  test "complete prints usage for no arguments" do
-    capture_stdout { run_command(:complete, []) }.should =~ /^Usage/
+  test "generic command prints error if invalid subcommand" do
+    mock(Commands).puts /Invalid.*'blah'/, anything
+    run_command 'function', ['blah']
   end
 
-  test "complete prints error for invalid command" do
-    capture_stdout { run_command(:complete, ['invalid','invalid']) }.should =~ /^#Error.*Please/m
+  test "generic command can take abbreviated subcommand" do
+    mock(Commands).list_function(anything)
+    run_command 'function', ['l']
   end
 
-  test "translate prints usage for no arguments" do
-    capture_stdout { run_command(:translate, []) }.should =~ /^Usage/
+  def bolt_expects_subcommand_args(bolt, expected)
+    Commands.instance_variable_set "@command", bolt
+    actual = Commands.send(:subcommand_required_args)
+    expected.all? {|k,v| actual[k] == v }.should == true
   end
 
-  test "translate prints error for invalid command" do
-    capture_stdout { run_command(:translate, %w{invalid blah}) }.should =~ /#Error/
+  test "has correct number of subcommands for bolt" do
+    bolt_expects_subcommand_args 'function', {"delete"=>1, "create"=>2}
   end
 
-  test "command prints usage with -h" do
-    capture_stdout { run_command :install, ['-h'] }.should =~ /^Usage/
+  test "has correct number of subcommands for shell_command" do
+    bolt_expects_subcommand_args 'shell_command', {"delete"=>1, "create"=>1}
   end
 
-  context "first install" do
-    before_all {
-      @old_config = Lightning.config
-      Lightning.config = Lightning::Config.new({})
-      @old_functions = Lightning.functions
-      Lightning.functions = nil
-
-      mock(Lightning.config).save.times(2)
-      mock(Commands).first_install? { true }.times(2)
-      stub.instance_of(Generator).call_generator { [] }
-      mock(File).open(anything, 'w')
-      @stdout = capture_stdout { run_command :install }
-    }
-
-    assert "generates default bolts" do
-      Generator::DEFAULT_GENERATORS.all? {|e| Lightning.config[:bolts].key?(e) }
-    end
-
-    assert "default bolts are global" do
-      Generator::DEFAULT_GENERATORS.all? {|e| Lightning.config[:bolts][e]['global'] }
-    end
-
-    test "builds 8 default functions" do
-      expected = %w{cd-gem cd-local_ruby cd-ruby cd-wild echo-gem echo-local_ruby echo-ruby echo-wild}
-      Lightning.functions.keys.sort.should == expected
-    end
-
-    test "prints correct install message" do
-      @stdout.should =~ /^Created.*lightningrc\nCreated.*functions\.sh for bash/m
-    end
-
-    after_all { Lightning.config = @old_config; Lightning.functions = @old_functions }
+  test "has correct number of subcommands for bolt" do
+    bolt_expects_subcommand_args 'bolt', {"alias"=>2, 'create'=>2, 'delete'=>1,
+      'generate'=>1, 'global'=>2, 'show'=>1}
   end
 
   context "run" do

data/test/completion_test.rb

@@ -9,7 +9,7 @@ context "Completion" do
   }
 
   def tab(input, expected, complete_regex=false)
-    Lightning.config[:complete_regex] = complete_regex
+    config[:complete_regex] = complete_regex
     mock(Commands).puts(expected)
     run_command :complete, [@command, 'cd-test '+ input]
   end
@@ -100,6 +100,8 @@ context "Completion" do
       tab '[]', Completion.error_array('Invalid regular expression.'), true
     end
   end
+
+  after_all { Lightning.functions.delete('blah') }
 end
 
 context "Completion misc" do

data/test/core_commands_test.rb

@@ -0,0 +1,59 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+context "Core commands" do
+  test "complete defaults to ARGV if no ENV['COMP_LINE']" do
+    mock(Completion).complete('o-a Col', anything)
+    capture_stdout { run_command(:complete, ['o-a', 'Col']) }
+  end
+
+  test "complete prints usage for no arguments" do
+    capture_stdout { run_command(:complete, []) }.should =~ /^Usage/
+  end
+
+  test "complete prints error for invalid command" do
+    capture_stdout { run_command(:complete, ['invalid','invalid']) }.should =~ /^#Error.*Please/m
+  end
+
+  test "translate prints usage for no arguments" do
+    capture_stdout { run_command(:translate, [])
+      }.should =~ /'lightning translate'.*incorrectly.*Usage:/m
+  end
+
+  test "translate prints error for invalid command" do
+    capture_stdout { run_command(:translate, %w{invalid blah}) }.should =~ /#Error/
+  end
+
+  context "first install" do
+    before_all {
+      @old_config = config
+      Lightning.config = Lightning::Config.new({})
+      @old_functions = Lightning.functions
+      Lightning.functions = nil
+
+      mock(config).save.times(2)
+      mock(Commands).first_install? { true }.times(2)
+      stub.instance_of(Generator).call_generator { [] }
+      mock(File).open(anything, 'w')
+      @stdout = capture_stdout { run_command :install }
+    }
+
+    assert "generates default bolts" do
+      Generator::DEFAULT_GENERATORS.all? {|e| config[:bolts].key?(e) }
+    end
+
+    assert "default bolts are global" do
+      Generator::DEFAULT_GENERATORS.all? {|e| config[:bolts][e]['global'] }
+    end
+
+    test "builds 8 default functions" do
+      expected = %w{cd-gem cd-local_ruby cd-ruby cd-wild echo-gem echo-local_ruby echo-ruby echo-wild}
+      Lightning.functions.keys.sort.should == expected
+    end
+
+    test "prints correct install message" do
+      @stdout.should =~ /^Created.*lightningrc\nCreated.*functions\.sh for bash/m
+    end
+
+    after_all { Lightning.config = @old_config; Lightning.functions = @old_functions }
+  end
+end