tabtab 0.9.0

data/lib/tabtab/completions.rb

@@ -0,0 +1,6 @@
+module TabTab::Completions
+end
+
+Dir[File.dirname(__FILE__) + "/completions/*.rb"].each do |path|
+  require path.gsub(/.rb$/, '')
+end

data/lib/tabtab/completions/external.rb

@@ -0,0 +1,39 @@
+class TabTab::Completions::External
+  attr_reader :global_config
+
+  def initialize(app_name, options_flag = '-h', global_config = {})
+    @app_name     = app_name
+    @options_flag = options_flag
+    @global_config  = global_config
+  end
+  
+  def options_str
+    @options_str ||= `#{@app_name} #{@options_flag}`
+  end
+  
+  # Returns list of long and short options for an application's --help display
+  # which was passed into initializer
+  def extract(_options_str = nil)
+    @options_str = _options_str if _options_str # hook for testing
+    @extract ||= begin
+      lines_containing_options = options_str.split(/\n/).grep(/^[\s\t]+-/)
+      all_options = lines_containing_options.inject([]) do |list, line|
+        list + line.scan(/(?:^\s+|,\s)(-[\w-]+)/).flatten
+      end
+      long_options  = all_options.grep(/^--/).sort
+      short_options = hide_short_flags? ? [] : (all_options - long_options).sort
+      long_options + short_options
+    end
+  end
+  
+  # Returns the sub-list of all options filtered by a common prefix
+  # e.g. if current +extract+ list is +['--help', '--extra', '-h', '-x']+
+  # then +starts_with('--')+ returns +['--help', '--extra']+
+  def starts_with(prefix)
+    extract.grep(/^#{prefix}/)
+  end
+
+  def hide_short_flags?
+    global_config[:shortflags] == 'disable'
+  end
+end

data/lib/tabtab/completions/file.rb

@@ -0,0 +1,23 @@
+class TabTab::Completions::File
+  attr_reader :file_path, :app_name, :current_token, :previous_token, :global_config
+  
+  def initialize(file_path, app_name, current_token, previous_token, global_config = {})
+    @file_path      = file_path
+    @app_name       = app_name
+    @current_token  = current_token
+    @previous_token = previous_token
+    @global_config  = global_config
+  end
+
+  # Returns the sub-list of all options filtered by a common prefix
+  # e.g. if current +extract+ list is +['--help', '--extra', '-h', '-x']+
+  # then +starts_with('--')+ returns +['--help', '--extra']+
+  def extract
+    if File.exists?(file_path)
+      load file_path
+      TabTab::Definition[app_name].extract_completions(previous_token, current_token, global_config)
+    else
+      []
+    end
+  end
+end

data/lib/tabtab/completions/gems.rb

@@ -0,0 +1,44 @@
+class TabTab::Completions::Gem
+  attr_reader :gem_name, :app_name, :current_token, :previous_token, :global_config, :definitions_file
+  
+  def initialize(gem_name, app_name, current_token, previous_token, global_config = {})
+    parse_gem_name_and_optional_explicit_file(gem_name)
+    @app_name       = app_name
+    @current_token  = current_token
+    @previous_token = previous_token
+    @global_config  = global_config
+  end
+
+  # Returns the sub-list of all options filtered by a common prefix
+  # e.g. if current +extract+ list is +['--help', '--extra', '-h', '-x']+
+  # then +starts_with('--')+ returns +['--help', '--extra']+
+  def extract
+    require "tabtab/definitions"
+    load definitions_file
+    if TabTab::Definition[app_name]
+      TabTab::Definition[app_name].extract_completions(previous_token, current_token, global_config)
+    else
+      []
+    end
+  end
+  
+  def load_gem_and_return_definitions_file
+    Dir[File.join(gem_root_path, '**', "tabtab_definitions.rb")].first
+  end
+  
+  def parse_gem_name_and_optional_explicit_file(gem_name)
+    if gem_name =~ %r{^([\w\-_]*)/(.*)}
+      @gem_name, file_path = $1, $2
+      @definitions_file = File.join(gem_root_path, file_path)
+    else
+      @gem_name = gem_name
+      @definitions_file = load_gem_and_return_definitions_file
+    end
+  end
+
+  def gem_root_path
+    require "rubygems"
+    gem gem_name
+    $LOAD_PATH.grep(/#{gem_name}.*\/lib$/).first.gsub(/\/lib$/, '')
+  end
+end

data/lib/tabtab/definitions.rb

@@ -0,0 +1,28 @@
+module TabTab::Definition
+  class InvalidDefinitionBlockArguments < Exception; end
+
+  class << self
+    attr_reader :registrations
+    
+    def register(app_name, options={}, &block)
+      @registrations ||= {}
+      registrations[app_name] = Root.named(app_name, options, &block)
+    end
+    
+    def [](app_name)
+      registrations[app_name]
+    end
+    
+    def clear
+      @registrations = {}
+    end
+    
+    def app_names
+      registrations.keys
+    end
+  end
+end
+
+Dir[File.dirname(__FILE__) + "/definitions/*.rb"].sort.each do |definition|
+  require definition.gsub(/.rb$/,'')
+end

data/lib/tabtab/definitions/base.rb

@@ -0,0 +1,146 @@
+class TabTab::Definition::Base
+  attr_reader :parent, :contents, :definition_block
+  
+  def initialize(parent, &block)
+    @parent           = parent
+    @contents         = []
+    @definition_block = block
+    yield_definition_block
+  end
+  
+  # Example usage:
+  #   c.flags :some_flag
+  #   c.flags :some_flag, :s, "a description"
+  #   c.flags :another_flag, "a description" do
+  #       %w[possible values for the flag]
+  #   end
+  # which map to example command-line expressions:
+  #   myapp --some_flag
+  #   myapp -s
+  #   myapp --another_flag possible
+  #   myapp --another_flag values
+  def flags(*flags_and_description, &block)
+    description = flags_and_description.pop if flags_and_description.last.is_a?(String)
+    flag_names  = flags_and_description
+    contents << TabTab::Definition::Flag.new(self, flag_names, description, &block)
+  end
+  alias_method :flag, :flags
+
+  # Example usage:
+  #   c.command :run
+  #   c.command :run, "Runs the good stuff"
+  #   c.command :choose, "Runs the good stuff", do
+  #      %w[possible values for the commands argument]
+  #   end
+  #   c.command :set_speed, "Runs the good stuff", do |run|
+  #      run.flags :a_flag
+  #      run.command :slowly
+  #      run.command :fast
+  #   end
+  # which map to example command-line expressions:
+  #   myapp run
+  #   myapp choose possible
+  #   myapp set_speed --a_flag fast
+  def command(name, description="", &block)
+    contents << TabTab::Definition::Command.new(self, name, description, &block)
+  end
+  
+  # Find a direct child/contents definition that supports a given token
+  def [](token)
+    contents.find { |definition| definition.definition_type != :default && definition.matches_token?(token) }
+  end
+  
+  # Find any child definition that supports a given token
+  def find_active_definition_for_last_token(last_token)
+    self[last_token] || contents.inject([]) do |mem, definition|
+      child = definition[last_token]
+      mem << child if child
+      mem
+    end.first
+  end
+  
+  
+  # How many tokens/parts of a command-line expression does this Flag consume
+  # By default, it is 1 token unless overridden by subclass
+  def tokens_consumed
+    1
+  end
+  
+  def filtered_completions(prefix)
+    completions_of_contents.grep(/^#{prefix}/)
+  end
+
+  def completions_of_contents
+    results = yield_result_block if contents.empty?
+    return results if results
+    contents.inject([]) do |mem, definition|
+      mem << definition.own_completions
+      mem
+    end.flatten
+  end
+
+  def own_completions
+    []
+  end
+  
+  def definition_type?(def_type)
+    self.definition_type == def_type
+  end
+  #
+  # Test support
+  #
+  
+  # Helper for test frameworks
+  def autocompletable?(cmd_line_or_tokens)
+    return false if cmd_line_or_tokens.nil?
+    tokens = cmd_line_or_tokens.is_a?(String) ? cmd_line_or_tokens.split(/\s/) : cmd_line_or_tokens
+    current, *remainder = tokens
+    return false unless matches_token?(current) # current cmd-line doesn't match this Definition
+    return true if remainder.empty?
+    if definition = find_child_definition_by_token(current, remainder)
+      return definition.autocompletable?(remainder)
+    end
+    yield_result_block
+  end
+  
+  def yield_definition_block
+    if definition_block.nil?
+      return
+    elsif definition_block.arity == -1
+      # these blocks return a result/do lots of work - don't run them now
+    elsif definition_block.arity == 1
+      definition_block.call self
+    else
+      raise TabTab::Definition::InvalidDefinitionBlockArguments
+    end
+  end
+
+  def yield_result_block
+    if definition_block.nil? || definition_block.arity == 1
+      nil
+    elsif definition_block.arity == -1
+      definition_block.call
+    else
+      raise TabTab::Definition::InvalidDefinitionBlockArguments
+    end
+  end
+
+  # recursively ask parents, until finding root, for current_token being completed
+  def current_token
+    parent.current_token
+  end
+
+  protected
+  
+  # To be implemented by subclasses.
+  # Determines if this definition matches the current token
+  def matches_token?(cmd_line_token)
+    false
+  end
+
+  def find_child_definition_by_token(cmd_line_token, remainder=nil)
+    contents.find do |definition|
+      definition.autocompletable?(remainder)
+    end
+  end
+end

data/lib/tabtab/definitions/command.rb

@@ -0,0 +1,47 @@
+module TabTab::Definition
+  class Command < Base
+    attr_reader :name, :description
+    def initialize(parent, name, description, &block)
+      @name        = name.to_s
+      @description = description
+      super parent, &block
+    end
+    
+    def definition_type
+      :command
+    end
+    
+    # How many tokens/parts of a command-line expression does this Flag consume
+    # For example, the following consume 1 token:
+    #   --simple
+    #   -s
+    # The following consumes 2 tokens:
+    #   --port 1234
+    def tokens_consumed
+      return 2 if definition_block
+      1
+    end
+
+    def own_completions
+      [name]
+    end
+
+    # Example usage:
+    #   c.default do
+    #     %w[possible values following command name]
+    #   end
+    # which map to example command-line expressions:
+    #   myapp this_command possible
+    #   myapp this_command value
+    #   myapp this_command following
+    def default(description=nil, &block)
+      contents << TabTab::Definition::Default.new(self, description, &block)
+    end
+
+    # Determines if current token matches this command's name
+    def matches_token?(cmd_line_token)
+      cmd_line_token == name
+    end
+
+  end
+end

data/lib/tabtab/definitions/default.rb

@@ -0,0 +1,41 @@
+module TabTab::Definition
+  class Default < Base
+    attr_reader :description
+    def initialize(parent, description=nil, &definition_block)
+      @description = description
+      super parent, &definition_block
+    end
+    
+    def definition_type
+      :default
+    end
+
+    def own_completions
+      yield_result_block
+    end
+    
+    def yield_result_block
+      if definition_block.arity == -1
+        definition_block.call
+      elsif definition_block.arity == 1
+        definition_block.call(parent.current_token)
+      else
+        raise TabTab::Definition::InvalidDefinitionBlockArguments
+      end
+    end
+
+    # Determines if current token matches this command's name
+    def matches_token?(cmd_line_token)
+      results = yield_result_block
+      case results
+      when String
+        results == cmd_line_token.to_s
+      when Array
+        results.include?(cmd_line_token.to_s)
+      else
+        false
+      end
+    end
+
+  end
+end

data/lib/tabtab/definitions/flag.rb

@@ -0,0 +1,38 @@
+module TabTab::Definition
+  class Flag < Base
+    attr_reader :definition, :flags, :description
+    def initialize(definition, flags, description, &block)
+      @flags       = flags.map { |flag| flag.to_s }
+      @description = description
+      super definition, &block
+    end
+    
+    def definition_type
+      :flag
+    end
+
+    # How many tokens/parts of a command-line expression does this Flag consume
+    # For example, the following consume 1 token:
+    #   --simple
+    #   -s
+    # The following consumes 2 tokens:
+    #   --port 1234
+    def tokens_consumed
+      definition_block.nil? ? 1 : 2
+    end
+
+    # convert flags into --flag or -f based on length of value
+    def own_completions
+      flags.map do |flag|
+        flag.size > 1 ? "--#{flag}" : "-#{flag}"
+      end
+    end
+    
+    # Determines if current token matches this command's flags
+    def matches_token?(cmd_line_token)
+      return false unless cmd_line_token
+      flags.include? cmd_line_token.gsub(/^-*/,'')
+    end
+    
+  end
+end

data/lib/tabtab/definitions/root.rb

@@ -0,0 +1,70 @@
+module TabTab::Definition
+  class Root < Base
+    attr_reader :app_name, :current_token
+
+    def self.named(app_name, options = {}, &block)
+      self.new(app_name, options, &block)
+    end
+
+    def initialize(app_name, options = {}, &block)
+      @app_name = app_name
+      super(nil, &block)
+      import_help_flags(options[:import]) if options[:import]
+    end
+    
+    def extract_completions(previous_token, current_token, global_config = {})
+      @current_token = current_token
+      @global_config = global_config
+      current = find_active_definition_for_last_token(previous_token) || self
+      current = (current.parent || self) if current.tokens_consumed == 1
+      completions = current.filtered_completions(current_token)
+      grouped = {:long => [], :short => [], :command => []}
+      grouped = completions.inject(grouped) do |mem, token|
+        if token =~ /^--/
+          mem[:long] << token
+        elsif token =~ /^-/
+          mem[:short] << token unless hide_short_flags?
+        else
+          mem[:command] << token
+        end
+        mem
+      end
+      grouped[:command].sort + grouped[:long].sort + grouped[:short].sort
+    end
+
+    def definition_type
+      :root
+    end
+    
+    # Example usage:
+    #   c.default do
+    #     %w[possible values following command name]
+    #   end
+    # which map to example command-line expressions:
+    #   myapp this_command possible
+    #   myapp this_command value
+    #   myapp this_command following
+    def default(description=nil, &block)
+      contents << TabTab::Definition::Default.new(self, description, &block)
+    end
+
+    # Determines if current token matches the app name
+    def matches_token?(cmd_line_token)
+      cmd_line_token == app_name
+    end
+    
+    def import_help_flags(help_flag)
+      help_flag = "--help" unless help_flag.is_a?(String)
+      imported_flags = TabTab::Completions::External.new(app_name, help_flag).extract
+      imported_flags.each do |flag|
+        flag.gsub!(/^-*/, '')
+        next unless flag.size > 0
+        self.flag(flag.to_sym)
+      end
+    end
+    
+    def hide_short_flags?
+      @global_config[:shortflags] == 'disable'
+    end
+  end
+end