lightning 0.2.1 → 0.3.0

data/lib/lightning/commands/shell_command.rb

@@ -0,0 +1,38 @@
+module Lightning::Commands
+  protected
+  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)
+  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
+  end
+
+  def create_shell_command(scmd, scmd_alias=nil)
+    scmd_alias ||= scmd
+    if config.shell_commands.values.include?(scmd_alias)
+      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}'"
+    end
+  end
+
+  def delete_shell_command(scmd)
+    if config.shell_commands[scmd]
+      config.shell_commands.delete scmd
+      save_and_say "Deleted shell command '#{scmd}' and its functions"
+    else
+      puts "Can't find shell command '#{scmd}'"
+    end
+  end
+end

data/lib/lightning/commands_util.rb

@@ -0,0 +1,75 @@
+module Lightning
+  # Utility methods to be used inside lightning commands.
+  module CommandsUtil
+    # Yields a block for an existing bolt or prints an error message
+    def if_bolt_found(bolt)
+      bolt = config.unalias_bolt(bolt)
+      config.bolts[bolt] ? yield(bolt) : puts("Can't find bolt '#{bolt}'")
+    end
+
+    # Prints a hash as a 2 column table sorted by keys
+    def print_sorted_hash(hash, indent=false)
+      offset = hash.keys.map {|e| e.size }.max + 2
+      offset += 1 unless offset % 2 == 0
+      indent_char = indent ? '  ' : ''
+      hash.sort.each do |k,v|
+        puts "#{indent_char}#{k}" << ' ' * (offset - k.size) << (v || '')
+      end
+    end
+
+    # Saves config and prints message
+    def save_and_say(message)
+      config.save
+      puts message
+    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.
+    # @param [Array]
+    # @return [Array<Array, Hash>] Hash of options has symbolic keys
+    def parse_args(args)
+      options, args = args.partition {|e| e =~ /^-/ }
+      options = options.inject({}) do |hash, flag|
+        key, value = flag.split('=')
+        hash[key.sub(/^--?/,'').intern] = value.nil? ? true : value
+        hash
+      end
+      [args, options]
+    end
+
+    # 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
+    end
+
+    private
+    def subcommand_required_args
+      desc_array[0].split('|').inject({}) {|a,e|
+        cmd, *args = e.strip.split(/\s+/)
+        a[cmd] = args.select {|e| e[/^[A-Z]/]}.size
+        a
+      }
+    end
+  end
+end

data/lib/lightning/completion.rb

@@ -1,43 +1,87 @@
-# derived from http://github.com/ryanb/dotfiles/tree/master/bash/completion_scripts/project_completion
-#This class handles completions given a path key and the text already typed.
-class Lightning
+require 'shellwords'
+
+module Lightning
+  # This class returns completions for the last word typed for a given lightning function and its {Function} object.
+  # Inspired loosely by ryanb[http://github.com/ryanb/dotfiles/tree/master/bash/completion_scripts/project_completion].
+  #
+  # == Regex Completion
+  # By default, regular expressions can be used while completing to filter/match possible completions. For duplicate
+  # paths that offer their full paths in completion, this means their full paths can also match. One non-regexp
+  # shorthand is that a '*' is converted to '.*' for glob-like behavior.To revert to standard completion, toggle
+  # Lightning.config[:complete_regex].
   class Completion
-    def self.complete(text_to_complete, bolt_key)
-      new(text_to_complete, bolt_key).matches
+    # @return [Array] Returns completions that match last word typed
+    def self.complete(text_to_complete, function, shellescape=true)
+      return error_array("No function found to complete.") unless function
+      new(text_to_complete, function, shellescape).matches
     end
-      
-    def initialize(text_typed, bolt_key)
+
+    # @return [Array] Constructs completion error message. More than one element long to ensure error message
+    # gets displayed and not completed
+    def self.error_array(message)
+      ["#Error: #{message}", "Please open an issue."]
+    end
+
+    def initialize(text_typed, function, shellescape=true)
       @text_typed = text_typed
-      @bolt_key = bolt_key
+      @function = function
+      @shellescape = shellescape
     end
   
+    # @return [Array] Main method to determine and return completions that match
     def matches
-      if Lightning.config[:complete_regex]
-        begin 
-          possible_completions.grep(/#{blob_to_regex(typed)}/)
-        rescue RegexpError
-          ['#Error: Invalid regular expression']
-        end
-      else
-        possible_completions.select do |e|
-          e[0, typed.length] == typed
+      matched = get_matches(possible_completions)
+      matched = match_when_completing_subdirectories(matched)
+      @shellescape ? matched.map {|e| Util.shellescape(e) } : matched
+    rescue SystemCallError
+      self.class.error_array("Nonexistent directory.")
+    rescue RegexpError
+      self.class.error_array("Invalid regular expression.")
+    end
+
+    # @param [Array]
+    # @return [Array] Selects possible completions that match using {Completion#typed typed}
+    def get_matches(possible)
+      Lightning.config[:complete_regex] ? possible.grep(/^#{blob_to_regex(typed)}/) :
+        possible.select {|e| e[0, typed.length] == typed }
+    end
+
+    # @param [Array]
+    # @return [Array] Generates completions when completing a directory above or below a basename
+    def match_when_completing_subdirectories(matched)
+      if matched.empty? && (top_dir = typed[/^([^\/]+)\//,1]) && !typed.include?('//')
+        matched = possible_completions.grep(/^#{top_dir}/)
+
+        # for typed = some/dir/file, top_dir = path and translated_dir = /full/bolt/path
+        if matched.size == 1 && (translated_dir = @function.translate([top_dir])[0])
+          short_dir = typed.sub(/\/([^\/]+)?$/, '')  # some/dir
+          completed_dir = short_dir.sub(top_dir, translated_dir) #/full/bolt/path/some/dir
+          completed_dir = File.expand_path(completed_dir) if completed_dir[/\/\.\.($|\/)/]
+          matched = Dir.entries(completed_dir).delete_if {|e| %w{. ..}.include?(e) }.map {|f|
+            File.directory?(completed_dir+'/'+f) ? File.join(short_dir,f) +'/' : File.join(short_dir,f)
+          }
+          matched = get_matches(matched)
         end
       end
+      matched
+    end
+
+    # @return [String] Last word typed by user
+    def typed
+      @typed ||= begin
+        args = Shellwords.shellwords(@text_typed)
+        !args[-1][/\s+/] && @text_typed[/\s+$/] ? '' : args[-1]
+      end
     end
-    
-    #just converts * to .*  to make a glob-like regex
+
+    # @private Converts * to .*  to make a glob-like regex when in regex completion mode
     def blob_to_regex(string)
       string.gsub(/^\*|([^\.])\*/) {|e| $1 ? $1 + ".*" : ".*" }
     end
-  
-    def typed
-      # @text_typed[/\s(.+?)$/, 1] || ''
-      text = @text_typed[/^(\S+)\s+(#{Lightning::TEST_FLAG})?\s*(.+?)$/, 3] || ''
-      text.strip
-    end
-  
+
+    protected
     def possible_completions
-      Lightning.bolts[@bolt_key].completions
-    end    
+      @function.completions
+    end
   end
 end

data/lib/lightning/completion_map.rb

@@ -1,59 +1,62 @@
-#This class maps completions to their full paths for the given blobs
-class Lightning
+module Lightning
+  # Maps completions (file basenames) and aliases to their full paths given a {Bolt} object's globs.
   class CompletionMap
+    DUPLICATE_DELIMITER = '//'
+    # @return [Array] Regular expression paths to ignore. By default paths ending in . or .. are ignored.
+    def self.ignore_paths
+      @ignore_paths ||= (Lightning.config[:ignore_paths] || []) + %w{\.\.?$}
+    end
+
+    # Sets ignore_paths
+    def self.ignore_paths=(val)
+      @ignore_paths = val
+    end
+
+    # @return [Hash] Maps file basenames to full paths
     attr_accessor :map
+    # @return [Hash] Maps aliases to full paths
     attr_reader :alias_map
     
     def initialize(*globs)
       options = globs[-1].is_a?(Hash) ? globs.pop : {}
       globs.flatten!
-      @map = create_map_for_globs(globs)
-      @alias_map = (options[:global_aliases] || {}).merge(options[:aliases] || {})
+      @map = create_globbed_map(globs)
+      @alias_map = options[:aliases] || {}
     end
-    
+
+    # @return [String] Fetches full path of file or alias
      def [](completion)
        @map[completion] || @alias_map[completion]
      end
-     
+
+     # @return [Array] List of unique basenames and aliases
      def keys
        (@map.keys + @alias_map.keys).uniq
      end
-    
-    #should return hash
-    def create_map_for_globs(globs)
-      path_hash = {}
-      ignore_paths = ['.', '..'] + Lightning.ignore_paths
-      globs.each do |d|
-        Dir.glob(d, File::FNM_DOTMATCH).each do |e|
-          basename = File.basename(e)
-          unless ignore_paths.include?(basename)
-            #save paths of duplicate basenames to process later
-            if path_hash.has_key?(basename)
-              if path_hash[basename].is_a?(Array)
-                path_hash[basename] << e
-              else
-                path_hash[basename] = [path_hash[basename], e]
-              end
-            else
-              path_hash[basename] = e
-            end
-          end
+
+    protected
+    def create_globbed_map(globs)
+      duplicates = {}
+      ignore_regexp = /(#{self.class.ignore_paths.join('|')})/
+      globs.map {|e| Dir.glob(e, File::FNM_DOTMATCH)}.flatten.uniq.
+       inject({}) do |acc, file|
+        basename = File.basename file
+        next acc if file =~ ignore_regexp
+        if duplicates[basename]
+          duplicates[basename] << file
+        elsif acc.key?(basename)
+          duplicates[basename] = [acc.delete(basename), file]
+        else
+          acc[basename] = file
         end
-      end
-      map_duplicate_basenames(path_hash)
-      path_hash
+        acc
+       end.merge create_resolved_duplicates(duplicates)
     end
-    
-    #map saved duplicates
-    def map_duplicate_basenames(path_hash)
-      path_hash.select {|k,v| v.is_a?(Array)}.each do |key,paths|
-        paths.each do |e|
-          new_key = "#{key}/#{File.dirname(e)}"
-          path_hash[new_key] = e
-        end
-        path_hash.delete(key)
+
+    def create_resolved_duplicates(duplicates)
+      duplicates.inject({}) do |hash, (basename, paths)|
+        paths.each {|e| hash["#{basename}#{DUPLICATE_DELIMITER}#{File.dirname(e)}"] = e }; hash
       end
     end
-    
   end
 end

data/lib/lightning/config.rb

@@ -1,72 +1,107 @@
-class Lightning  
+require 'yaml'
+module Lightning
+  # Handles config file used to generate bolts and functions.
+  # The config file is in YAML so it's easy to manually edit. Nevertheless, it's recommended to modify
+  # the config through lightning commands since their API is more stable than the config file's API.
+  #
+  # == Config File Format
+  # 
+  # Top level keys:
+  #
+  # * *:source_file*: Location of shell file generated by {Builder}. Defaults to ~/.lightning/functions.sh
+  # * *:ignore_paths*: Array of paths to globally ignore when generating possible completions
+  # * *:complete_regex*: true or false (default is true). When true, regular expressions can be used while
+  #   completing. See {Completion} for more details.
+  # * *:shell*: Specifies shell Builder uses to generate completions. Defaults to bash.
+  # * *:bolts*: Array of bolts with each bolt being a hash with the following keys:
+  #   * *name*(required): Unique name
+  #   * *alias*: Abbreviated name which can be used to reference bolt in most lightning commands. This is used
+  #     over name when generating function names.
+  #   * *global*: true or false (default is false). When set, uses bolt to generate functions with each command
+  #     in :shell_commands.
+  #   * *globs*(required): Array of globs which defines group of paths bolt handles
+  #   * *functions*: Array of lightning functions. A function can either be a string (shell command with default
+  #     options) or a hash with the following keys:
+  #     * *name*: Name of the lightning function
+  #     * *shell_command*(required): Shell command with default options which this function wraps
+  #     * *aliases*: A hash of custom aliases and full paths only for this function
+  #     * *post_path*: String to add immediately after a resolved path
+  # * *:shell_commands*: Hash of global shell commands which are combined with all global bolts to generate functions
   class Config < ::Hash
     class <<self
       attr_accessor :config_file
+      # @return [String] ~/.lightningrc
       def config_file
-        @config_file ||= (File.exists?('lightning.yml') ? 'lightning.yml' : File.expand_path(File.join("~",".lightning.yml")))
+        @config_file ||= File.join(Lightning.home,".lightningrc")
       end
 
-      def create(options={})
-        hash = read_config_file
-        obj = new(hash)
-        configure_commands_and_paths(obj) if options[:read_only]
-        obj
-      end
-    
-      def read_config_file(file=nil)
-        default_config = {'shell'=>'bash', 'generated_file'=>File.expand_path(File.join('~', '.lightning_completions')), 
-          'complete_regex'=>true}
-        @config_file = file if file
-        hash = YAML::load_file(config_file)
-        default_config.merge(hash)
-      end
-      
-      def commands_to_bolt_key(map_to_command, new_command)
-        "#{map_to_command}-#{new_command}"
-      end
-
-      def configure_commands_and_paths(hash)
-        hash[:paths] ||= {}
-        hash[:commands].each do |e|
-          #mapping a referenced path
-          if e['paths'].is_a?(String)
-            e['bolt_key'] = e['paths'].dup
-          end
-          #create a path entry + key if none exists
-          if e['bolt_key'].nil?
-            #extract command in case it has options after it
-            e['map_to'] =~ /\s*(\w+)/
-            bolt_key = commands_to_bolt_key($1, e['name'])
-            e['bolt_key'] = bolt_key
-            hash[:paths][bolt_key] = e['paths'] || []
-          end
-        end
-        hash
+      # @return [Hash] Creates a bolt hash given globs
+      def bolt(globs)
+        {'globs'=>globs.map {|e| e.sub(/^~/, Lightning.home) }}
       end
     end
-    
-    def save
-      File.open(self.class.config_file, "w") { |f| f.puts self.to_hash.to_yaml }
-    end
 
-    def initialize(hash)
+    DEFAULT = {:complete_regex=>true, :bolts=>{}, :shell_commands=>{'cd'=>'cd', 'echo'=>'echo'} }
+    attr_accessor :source_file
+    def initialize(hash=read_config_file)
+      hash = DEFAULT.merge hash
       super
       replace(hash)
-      self.replace(self.symbolize_keys)
     end
-    
-    def to_hash
-      hash = Hash.new
-      hash.replace(self)
+
+    # @return [String] Shell file generated by Builder. Defaults to ~/.lightning/functions.sh
+    def source_file
+      @source_file ||= self[:source_file] || File.join(Lightning.dir, 'functions.sh')
     end
-    
-    #from Rails' ActiveSupport
-    def symbolize_keys
-      inject({}) do |options, (key, value)|
-        options[(key.to_sym rescue key) || key] = value
-        options
-      end
+
+    # @return [Array] Global shell commands used to generate Functions for all Bolts.
+    def global_commands
+      shell_commands.keys
+    end
+
+    # @return [Hash] Maps shell command names to their aliases
+    def shell_commands
+      self[:shell_commands]
+    end
+
+    # @return [Hash] Maps bolt names to their config hashes
+    def bolts
+      self[:bolts]
+    end
+
+    # @return [String] Converts shell command alias to shell command
+    def unaliased_command(cmd)
+      shell_commands.invert[cmd] || cmd
+    end
+
+    # @return [String] Converts bolt alias to bolt's name
+    def unalias_bolt(bolt)
+      bolts[bolt] ? bolt : (Array(bolts.find {|k,v| v['alias'] == bolt })[0] || bolt)
+    end
+
+    # @return [String] Extracts shell command from a shell_command string
+    def only_command(shell_command)
+      shell_command[/\w+/]
+    end
+
+    # @return [String] Creates a command name from its shell command and bolt in the form "#{command}-#{bolt}".
+    # Uses aliases for either if they exist.
+    def function_name(shell_command, bolt)
+      cmd = only_command shell_command
+      "#{shell_commands[cmd] || cmd}-#{bolt}"
+    end
+
+    # Saves config to Config.config_file
+    def save
+      File.open(self.class.config_file, "w") {|f| f.puts Hash.new.replace(self).to_yaml }
+    end
+
+    protected
+    def read_config_file
+      File.exists?(self.class.config_file) ?
+        Util.symbolize_keys(YAML::load_file(self.class.config_file)) : {}
+    rescue
+      raise $!.message.sub('syntax error', "Syntax error in '#{Config.config_file}'")
     end
-    
   end
-end
+end