lightning 0.3.1 → 0.3.2

data/CHANGELOG.rdoc

@@ -1,3 +1,8 @@
+== 0.3.2
+* Better tests
+* Added a manpage
+* All command options can be abbreviated
+
 == 0.3.1
 * Fixed lightning function create bug
 

data/README.rdoc

@@ -1,5 +1,5 @@
 == 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.
+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
@@ -59,6 +59,18 @@ Once lightning is installed, we need to do a one-time setup:
   # 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}[http://github.com/cldwalker/lightning/issues].
 
@@ -68,12 +80,13 @@ Please report them {on github}[http://github.com/cldwalker/lightning/issues].
 
 == 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
+* 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
-* 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

@@ -20,11 +20,11 @@ begin
     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.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."
     s.email = "gabriel.horner@gmail.com"
     s.homepage = "http://tagaholic.me/lightning"
     s.authors = ["Gabriel Horner"]
-    s.files =  FileList["CHANGELOG.rdoc", "Rakefile","README.rdoc", "LICENSE.txt", "{bin,lib,test}/**/*"]
+    s.files =  FileList["CHANGELOG.rdoc", "Rakefile","README.rdoc", "LICENSE.txt", "{bin,lib,test,man}/**/*"]
     s.has_rdoc = 'yard'
     s.rdoc_options = ['--title', "Lightning #{Lightning::VERSION} Documentation"]
     s.rubyforge_project = 'tagaholic'

data/lib/lightning/commands/bolt.rb

@@ -4,27 +4,28 @@ module Lightning::Commands
     "generate BOLT [generator] [-t|--test] | global ON_OR_OFF BOLTS | show BOLT)",
     "Commands for managing bolts. Defaults to listing them."
   def bolt(argv)
-    subcommand = argv.shift || 'list'
-    subcommand = %w{alias create delete generate global list show}.find {|e| e[/^#{subcommand}/]} || subcommand
-    bolt_subcommand(subcommand, argv) if subcommand_has_required_args(subcommand, argv)
+    call_subcommand(argv, %w{alias create delete generate global list show}) do |scmd, argv|
+      case scmd
+      when 'list'     then  list_bolts(argv)
+      when 'create'   then  create_bolt(argv.shift, argv)
+      when 'alias'    then  alias_bolt(argv[0], argv[1])
+      when 'delete'   then  delete_bolt(argv[0])
+      when 'show'     then  show_bolt(argv[0])
+      when 'global'   then  globalize_bolts(argv.shift, argv)
+      when 'generate' then  generate_bolt(argv)
+      end
+    end
   end
 
-  def bolt_subcommand(subcommand, argv)
-    case subcommand
-    when 'list'     then  list_subcommand(:bolts, argv)
-    when 'create'   then  create_bolt(argv.shift, argv)
-    when 'alias'    then  alias_bolt(argv[0], argv[1])
-    when 'delete'   then  delete_bolt(argv[0])
-    when 'show'     then  show_bolt(argv[0])
-    when 'global'   then  globalize_bolts(argv.shift, argv)
-    when 'generate' then  generate_bolt(argv)
-    else puts "Invalid subcommand '#{subcommand}'", command_usage
-    end
+  def list_bolts(argv)
+    args, options = parse_args argv, %w{alias}
+    options[:alias] ? print_sorted_hash(config.bolts.inject({}) {|a,(k,v)| a[k] = v['alias']; a }) :
+      puts(config.bolts.keys.sort)
   end
 
   def generate_bolt(argv)
-    args, options = parse_args argv
-    Lightning::Generator.run(args[0], :once=>args[1], :test=>options[:test] || options[:t])
+    args, options = parse_args argv, %w{test}
+    Lightning::Generator.run(args[0], :once=>args[1], :test=>options[:test])
   end
 
   def create_bolt(bolt, globs)

data/lib/lightning/commands/core.rb

@@ -32,7 +32,7 @@ module Lightning
     desc "[--file=FILE] [--shell=SHELL]",
       "Builds shell functions and installs them into FILE to be sourced by shell."
     def install(argv)
-      args, options = parse_args(argv)
+      args, options = parse_args(argv, %w{file shell})
       config[:shell] = options[:shell] if options[:shell]
       config.source_file = options[:file] if options[:file]
 

data/lib/lightning/commands/function.rb

@@ -3,24 +3,20 @@ module Lightning::Commands
   desc '(list [--command=SHELL_COMMAND] [--bolt=BOLT] | create SHELL_COMMAND BOLT [function] | delete FUNCTION)',
     'Commands for managing functions. Defaults to listing them.'
   def function(argv)
-    subcommand = argv.shift || 'list'
-    subcommand = %w{create delete list}.find {|e| e[/^#{subcommand}/]} || subcommand
-    function_subcommand(subcommand, argv) if subcommand_has_required_args(subcommand, argv)
-  end
-
-  def function_subcommand(subcommand, argv)
-    case subcommand
-    when 'list'    then list_function(argv)
-    when 'create'  then create_function_and_bolt(argv)
-    when 'delete'  then delete_function argv.shift
-    else puts "Invalid subcommand '#{subcommand}'", command_usage
+    call_subcommand(argv, %w{create delete list}) do |subcommand, argv|
+      case subcommand
+      when 'list'    then list_function(argv)
+      when 'create'  then create_function_and_bolt(argv)
+      when 'delete'  then delete_function argv.shift
+      end
     end
   end
 
   def list_function(argv)
-    args, options = parse_args argv
+    args, options = parse_args argv, %w{bolt command}
     functions = if options[:bolt]
-      Lightning.functions.values.select {|e| e.bolt.name == options[:bolt] }.map {|e| e.name}
+      bolt = config.unalias_bolt(options[:bolt])
+      Lightning.functions.values.select {|e| e.bolt.name == bolt }.map {|e| e.name}
     elsif options[:command]
       Lightning.functions.values.select {|e| e.shell_command == options[:command] }.map {|e| e.name}
     else

data/lib/lightning/commands/shell_command.rb

@@ -3,18 +3,18 @@ module Lightning::Commands
   desc '(list [-a|--alias] | create SHELL_COMMAND [alias]| delete SHELL_COMMAND)',
     'Commands for managing shell commands. Defaults to listing them.'
   def shell_command(argv)
-    subcommand = argv.shift || 'list'
-    subcommand = %w{create delete list}.find {|e| e[/^#{subcommand}/]} || subcommand
-    shell_command_subcommand(subcommand, argv) if subcommand_has_required_args(subcommand, argv)
+    call_subcommand(argv, %w{create delete list}) do |scmd, argv|
+      case scmd
+      when 'list'   then   list_shell_commands(argv)
+      when 'create' then   create_shell_command(argv[0], argv[1])
+      when 'delete' then   delete_shell_command(argv[0])
+      end
+    end
   end
 
-  def shell_command_subcommand(subcommand, argv)
-    case subcommand
-    when 'list'   then   list_subcommand(:shell_commands, argv)
-    when 'create' then   create_shell_command(argv[0], argv[1])
-    when 'delete' then   delete_shell_command(argv[0])
-    else  puts "Invalid subcommand '#{subcommand}'", command_usage
-    end
+  def list_shell_commands(argv)
+    args, options = parse_args argv, %w{alias}
+    options[:alias] ? print_sorted_hash(config.shell_commands) : puts(config.shell_commands.keys.sort)
   end
 
   def create_shell_command(scmd, scmd_alias=nil)
@@ -23,7 +23,7 @@ module Lightning::Commands
       puts "Alias '#{scmd_alias}' already exists for shell command '#{config.unaliased_command(scmd_alias)}'"
     else
       config.shell_commands[scmd] = scmd_alias
-      save_and_say "Added shell command '#{scmd}'"
+      save_and_say "Created shell command '#{scmd}'"
     end
   end
 

data/lib/lightning/commands_util.rb

@@ -23,27 +23,33 @@ module Lightning
       puts message
     end
 
+    # Handles abbreviated subcommands and printing errors for invalid subcommands.
+    # Defaults to 'list' subcommand if none given.
+    def call_subcommand(argv, cmds)
+      subcommand = argv.shift || 'list'
+      (subcmd = cmds.find {|e| e[/^#{subcommand}/]}) ?
+        subcommand_has_required_args(subcmd, argv) && yield(subcmd, argv) :
+        puts("Invalid subcommand '#{subcommand}'", command_usage)
+    end
+
     # @return [nil, true] Determines if command has required arguments
     def command_has_required_args(argv, required)
       return true if argv.size >= required
       puts "'lightning #{@command}' was called incorrectly.", command_usage
     end
 
-    # @return [nil, true] Determines if subcommand has required arguments
-    def subcommand_has_required_args(subcommand, argv)
-      return true if argv.size >= (subcommand_required_args[subcommand] || 0)
-      puts "'lightning #{@command} #{subcommand}' was called incorrectly.", command_usage
-    end
-
     # Parses arguments into non-option arguments and hash of options. Options can have
-    # values with an equal sign i.e. '--option=value'. Options without a value are set to true.
+    # values with an equal sign i.e. '--option=value'. Options can be abbreviated with
+    # their first letter. Options without a value are set to true.
     # @param [Array]
     # @return [Array<Array, Hash>] Hash of options has symbolic keys
-    def parse_args(args)
+    def parse_args(args, names=[])
       options, args = args.partition {|e| e =~ /^-/ }
       options = options.inject({}) do |hash, flag|
         key, value = flag.split('=')
-        hash[key.sub(/^--?/,'').intern] = value.nil? ? true : value
+        name = key.sub(/^--?/,'')
+        name = names.sort.find {|e| e[/^#{name}/] } || name
+        hash[name.intern] = value.nil? ? true : value
         hash
       end
       [args, options]
@@ -52,18 +58,12 @@ module Lightning
     # Shortcut to Lightning.config
     def config; Lightning.config; end
 
-    # Lists a bolt or shell_command with optional --alias
-    def list_subcommand(list_type, argv)
-      if %w{-a --alias}.include?(argv[0])
-        hash = config.send(list_type)
-        hash = hash.inject({}) {|a,(k,v)| a[k] = v['alias']; a } if list_type == :bolts
-        print_sorted_hash hash
-      else
-        puts config.send(list_type).keys.sort
-      end
+    private
+    def subcommand_has_required_args(subcommand, argv)
+      return true if argv.size >= (subcommand_required_args[subcommand] || 0)
+      puts "'lightning #{@command} #{subcommand}' was called incorrectly.", command_usage
     end
 
-    private
     def subcommand_required_args
       desc_array[0].split('|').inject({}) {|a,e|
         cmd, *args = e.strip.split(/\s+/)

data/lib/lightning/generator.rb

@@ -54,11 +54,11 @@ module Lightning
     def run_once(bolt, options)
       generator = options[:once] || bolt
       if options[:test]
-        puts Config.bolt(Array(call_generator(generator)))['globs']
+        $stdout.puts Config.bolt(Array(call_generator(generator)))['globs']
       else
         if generate_bolts(bolt=>generator)
-          puts "Generated following globs for bolt '#{bolt}':"
-          puts Lightning.config.bolts[bolt]['globs'].map {|e| "  "+e }
+          $stdout.puts "Generated following globs for bolt '#{bolt}':",
+            Lightning.config.bolts[bolt]['globs'].map {|e| "  "+e }
           true
         end
       end

data/lib/lightning/version.rb

@@ -1,3 +1,3 @@
 module Lightning
-  VERSION = '0.3.1'
+  VERSION = '0.3.2'
 end

data/man/lightning.1

@@ -0,0 +1,207 @@
+.\" generated with Ronn/v0.4.1
+.\" http://github.com/rtomayko/ronn/
+.
+.TH "LIGHTNING" "1" "April 2010" "CLDWALKER" "Lightning Manual"
+.
+.SH "NAME"
+\fBlightning\fR \-\- Speed for your shell
+.
+.SH "SYNOPSIS"
+.
+.nf
+lightning [\-h|\-\-help] [\-v|\-\-version] COMMAND [ARGS]
+.
+.fi
+.
+.SH "DESCRIPTION"
+\fBlightning\fR 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 \fIbolt\fR, are then applied to commands to produce functions. In addition to translating basenames to full paths, lightning \fIfunctions\fR 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.
+.
+.P
+To make bolts shareable between users and functions easier to create, \fBlightning\fR has \fIgenerators\fR. A \fIgenerator\fR generates filesystem\-specific globs for a bolt. \fBlightning\fR comes with some default generators. Users can make their own generators with generator plugins placed under ~/.lightning/generators/.
+.
+.SH "COMMANDS"
+\fBlightning\fR 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/.
+.
+.TP
+\fBbolt\fR
+Commands for managing bolts. Defaults to listing them.
+.
+.TP
+\fBcomplete\fR
+Prints a function's completions based on the last argument.
+.
+.TP
+\fBfunction\fR
+Commands for managing functions. Defaults to listing them.
+.
+.TP
+\fBgenerator\fR
+Lists available generators.
+.
+.TP
+\fBinstall\fR
+Builds shell functions and installs them into FILE to be sourced by shell.
+.
+.TP
+\fBshell_command\fR
+Commands for managing shell commands. Defaults to listing them.
+.
+.TP
+\fBtranslate\fR
+Translates each argument and prints it on a separate line.
+.
+.SH "CREATE FUNCTIONS"
+There are two nonexclusive ways of creating functions. The first involves combining bolts with individual shell commands. Here are the steps involved:
+.
+.IP "\(bu" 4
+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'
+.
+.IP "\(bu" 4
+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'
+.
+.IP "\(bu" 4
+Generate and load functions into shell
+  $ lightning\-reload
+  Created ~/.lightning/function.sh
+  Loaded ~/.lightning/function.sh
+.
+.IP "" 0
+.
+.P
+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.
+.
+.P
+  # 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
+.
+.P
+  # 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
+.
+.P
+  # Verify global functions
+  $ lightning function list
+  grep\-clojure
+  grep\-python
+  grep\-ruby
+  vim\-clojure
+  vim\-python
+  vim\-ruby
+.
+.SH "LIGHTNINGRC"
+\fBlightning\fR's configuration is stored in ~/.lightningrc as YAML. Since it's human readable it's easy to modify. However, \fBlightning\fR 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 \fIhttp://tagaholic.me/lightning/doc/Lightning/Config.html\fR.
+.
+.SH "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
+.
+.P
+If you've installed with rubygems and the command \fBtime lightning\fR takes longer than 0.05 seconds, I \fIstrongly recommend\fR installing with rip, http://hellorip.com. Your startup time directly effects your autocompletion speed with lightning.
+.
+.P
+Once lightning is installed, we need to do a one\-time setup:
+.
+.P
+  # To see available install options
+  $ lightning install \-h
+.
+.P
+  # Installs lightning's core files
+  $ lightning install && source ~/.lightning/functions.sh
+  Created ~/.lightning_yml
+  Created ~/.lightning/functions.sh
+.
+.P
+  # 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
+.
+.SH "EXAMPLES"
+Get help on any command:
+.
+.P
+  $ lightning function \-h
+  $ lightning bolt \-h
+.
+.P
+List functions:
+.
+.P
+  # 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
+.
+.P
+Regenerate functions and source them into the shell:
+.
+.P
+  # Call every time for changes to bolts and functions to take effect
+  $ lightning\-reload
+.
+.P
+Manage global shell commands:
+.
+.P
+  $ lightning shell_command list
+  $ lightning shell_command create cd
+  $ lightning shell_command delete cd
+.
+.P
+Manage/edit bolts:
+.
+.P
+  $ lightning bolt list
+  $ lightning bolt delete ruby
+  $ lightning bolt alias ruby r
+  $ lightning bolt global off ruby gem local_ruby
+.
+.P
+Generate a bolt using a generator:
+.
+.P
+  # 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
+.
+.P
+Test what a function will execute:
+.
+.P
+  # 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
+  .
+.
+.SH "BUGS"
+Please report bugs at \fIhttp://github.com/cldwalker/lightning/issues\fR.
+.
+.SH "COPYRIGHT"
+\fBlightning\fR is Copyright (C) 2010 Gabriel Horner
+.
+.SH "SEE ALSO"
+\fIhttp://tagaholic.me/lightning\fR, \fIhttp://tagaholic.me/lightning/doc/\fR, \fIhttp://github.com/cldwalker/lightning\fR