clin 0.3.0 → 0.4.0

data/lib/clin/errors.rb

@@ -4,16 +4,32 @@ module Clin
   Error = Class.new(RuntimeError)
 
   # Error cause by the user input(when parsing command)
-  CommandLineError = Class.new(Error)
+  class CommandLineError < Error
+    def self.severity(value = @severity)
+      @severity = value
+      @severity ||= 1
+    end
+  end
 
   # Error when the help needs to be shown
-  HelpError = Class.new(CommandLineError)
+  class HelpError < CommandLineError
+    def initialize(command)
+      if command.class == Class && command < Clin::Command
+        super(command.help)
+        @command = command
+      else
+        super(command)
+      end
+    end
+  end
 
   # Error when an positional argument is wrong
   ArgumentError = Class.new(CommandLineError)
 
   # Error when a fixed argument is not matched
-  class FixedArgumentError < ArgumentError
+  class RequiredArgumentError < ArgumentError
+    severity 100
+
     # Create a new FixedArgumentError
     # @param argument [String] Name of the fixed argument
     # @param got [String] What argument was in place of the fixed argument
@@ -32,5 +48,35 @@ module Clin
   end
 
   # Error when a option is wrong
-  OptionError = Class.new(CommandLineError)
+  class OptionError < CommandLineError
+    def initialize(message, option)
+      super(message)
+      @option = option
+    end
+  end
+
+  # Error when undefined options are found in argv
+  class UnknownOptionError < OptionError
+    def initialize(option)
+      message = "Unknown option #{option}"
+      super(message, option)
+    end
+  end
+
+  # Error when a flag option has an unexpected argument
+  class OptionUnexpectedArgumentError < OptionError
+    def initialize(option, value)
+      @value = value
+      message = "Unexpected argument '#{value}' for option #{option}"
+      super message, option
+    end
+  end
+
+  # When a option is missing it's required argument
+  class MissingOptionArgumentError < OptionError
+    def initialize(option)
+      message = "Missing argument for option #{option}"
+      super(message, option)
+    end
+  end
 end

data/lib/clin/line_reader/basic.rb

@@ -0,0 +1,38 @@
+require 'clin'
+require 'clin/line_reader'
+require 'io/console'
+
+# Basic line scanner.
+# Use stdin#gets
+class Clin::LineReader::Basic
+  attr_reader :statement
+  attr_reader :options
+
+  def self.available?
+    true
+  end
+
+  def initialize(shell, statement, options = {})
+    @shell = shell
+    @statement = statement
+    @options = options
+  end
+
+  def readline
+    @shell.out.print(@statement)
+    scan
+  end
+
+  protected def scan
+    return @shell.in.gets if echo?
+    begin
+      @shell.in.noecho(&:gets)
+    rescue Errno::EBADF # If console doesn't support noecho
+      @shell.in.gets
+    end
+  end
+
+  protected def echo?
+    @options.fetch(:echo, true)
+  end
+end

data/lib/clin/line_reader/readline.rb

@@ -0,0 +1,53 @@
+require 'readline'
+
+# Readline line scanner.
+# Allow autocomplete and history.
+# Use Readline.readline
+# Valid options:
+# echo: [Boolean] Set to false not to show on screen what you type(e.g. password)
+# autocomplete: List of values to autocomplete or proc that return the values
+# add_to_history: [Boolean] Add the reply to the history, default: true
+class Clin::LineReader::Readline < Clin::LineReader::Basic
+  def self.available?
+    Clin.use_readline?
+  end
+
+  def readline
+    if echo?
+      Readline.completion_append_character = nil
+      set_completion_proc
+      Readline.readline(statement, add_to_history?)
+    else # Use basic method to fetch
+      super
+    end
+  end
+
+  # Set the auto-completion process if applicable
+  protected def set_completion_proc
+    proc = completion_proc
+    Readline.completion_proc = proc unless proc.nil?
+  end
+
+  # Return nil if no completion given as option
+  # @return [Proc] Auto-completion process
+  protected def completion_proc
+    return nil unless autocomplete?
+    if autocomplete.is_a? Proc
+      autocomplete
+    else
+      proc { |s| autocomplete.grep(/^#{Regexp.escape(s)}/) }
+    end
+  end
+
+  protected def autocomplete
+    options[:autocomplete]
+  end
+
+  protected def autocomplete?
+    options.fetch(:autocomplete, false)
+  end
+
+  protected def add_to_history?
+    options.fetch(:add_to_history, true)
+  end
+end

data/lib/clin/line_reader.rb

@@ -0,0 +1,16 @@
+require 'clin'
+
+# Handle to delegate the scan method to the right module.
+# It will use Readline unless the disabled using Clin.use_readline = false
+module Clin::LineReader
+  def self.scan(shell, statement, options = {})
+    readers.detect(&:available?).new(shell, statement, options).readline
+  end
+
+  def self.readers
+    @readers ||= [Clin::LineReader::Readline, Clin::LineReader::Basic]
+  end
+end
+
+require 'clin/line_reader/basic'
+require 'clin/line_reader/readline'

data/lib/clin/option.rb

@@ -53,19 +53,12 @@ class Clin::Option
     @default = default
   end
 
-  # Register the option to the Option Parser
-  # @param opts [OptionParser]
-  # @param out [Hash] Out options mapping
-  def register(opts, out)
-    load_default(out)
+  def trigger(opts, out, value)
+    value = cast(value)
     if @block.nil?
-      opts.on(*option_parser_arguments) do |value|
-        on(value, out)
-      end
+      on(value, out)
     else
-      opts.on(*option_parser_arguments) do |value|
-        block.call(opts, out, value)
-      end
+      block.call(opts, out, value)
     end
   end
 
@@ -153,6 +146,10 @@ class Clin::Option
     @argument.eql? false
   end
 
+  def argument_optional?
+    @optional_argument
+  end
+
   # Init the output Hash with the default values. Must be called before parsing.
   # @param out [Hash]
   def load_default(out)
@@ -187,4 +184,20 @@ class Clin::Option
     end
     out
   end
+
+  def banner
+    args = [short, long_argument, description]
+    args.compact.join(' ')
+  end
+
+  def cast(str)
+    return str if type.nil?
+    if type == Integer
+      Integer(str)
+    elsif type == Float
+      Float(str)
+    else
+      str
+    end
+  end
 end

data/lib/clin/option_parser.rb

@@ -0,0 +1,159 @@
+require 'clin'
+
+# Class that handler the option parsing part of command parsing.
+# It separate the options from the arguments
+class Clin::OptionParser
+  LONG_OPTION_REGEX = /\A(?<name>--[^=]*)(?:=(?<value>.*))?/m
+  SHORT_OPTION_REGEX = /\A(?<name>-.)(?<value>(=).*|.+)?/m
+
+  # List of arguments(i.e. Argv segments that are not options)
+  attr_reader :arguments
+
+  # List of errors encountered
+  attr_reader :errors
+
+  # Parsed options are store here
+  attr_reader :options
+
+  # Any option skipped(if the command allow it) will be listed in here
+  attr_reader :skipped_options
+
+  def initialize(command, argv)
+    @errors = []
+    @command = command
+    @options = {}
+    @original_argv = argv
+    @argv = argv.clone
+    @arguments = []
+    @skipped_options = []
+  end
+
+  # Parse the argument for the command.
+  # @return [Hash] return the options parsed
+  # Options can also be accessed with #options
+  # ```
+  # # Suppose verbose and opt are defined option for the command.
+  # parser = OptionParser.new(command, %w(arg1 arg2 -v --opt val))
+  # parser.parse #=> {verbose: true, opt: 'val'}
+  # Get the arguments
+  # parser.argv # => ['arg1', 'arg2']
+  # ```
+  def parse
+    while parse_next
+    end
+    @options
+  end
+
+  # Fetch the next next argument and parse the option or store it as an argument
+  # @return [Boolean] true if it parsed anything, false if there are no more argument to parse
+  def parse_next
+    return false if @argv.empty?
+    case (arg = @argv.shift)
+    when LONG_OPTION_REGEX
+      name = Regexp.last_match[:name]
+      value = Regexp.last_match[:value]
+      parse_long(name, value)
+    when SHORT_OPTION_REGEX
+      name = Regexp.last_match[:name]
+      value = Regexp.last_match[:value]
+      parse_short(name, value)
+    else
+      @arguments << arg
+    end
+    true
+  end
+
+  # Parse a long option
+  # @param name [String] name of the option(--verbose)
+  # @param value [String] value of the option
+  # If the value is nil and the option allow argument it will try to use the next argument
+  def parse_long(name, value)
+    option = @command.find_option_by(long: name)
+    parse_option(option, name, value, false)
+  end
+
+  # Parse a long option
+  # @param name [String] name of the option(-v)
+  # @param value [String] value of the option
+  # If the value is nil and the option allow argument it will try to use the next argument
+  def parse_short(name, value)
+    option = @command.find_option_by(short: name)
+    parse_option(option, name, value, true)
+  end
+
+  # Parse the given option.
+  # @param option [Clin::Option]
+  # @param name [String] name it was given in the command
+  # @param value [String] value of the option
+  # If the value is nil and the option allow argument it will try to use the next argument
+  def parse_option(option, name, value, short)
+    return handle_unknown_option(name, value) if option.nil?
+    return parse_flag_option(option, value, short) if option.flag?
+
+    value = complete(value)
+    if value.nil? && !option.argument_optional?
+      return add_error Clin::MissingOptionArgumentError.new(option)
+    end
+    value ||= true
+    option.trigger(self, @options, value)
+  end
+
+  # Get the next possible argument in the list if the value is nil.
+  # @param value [String] current option value.
+  # Only get the next argument in the list if:
+  # - value is nil
+  # - the next argument is not an option(start with '-')
+  def complete(value)
+    if value.nil? && @argv.any? && !@argv.first.start_with?('-')
+      @argv.shift
+    else
+      value
+    end
+  end
+
+  # Parse a flag option(No argument)
+  # Add [OptionUnexpectedArgumentError] If value is defined and the long version was used.
+  # Short flag option can be merged together(i.e these are equivalent: -abc, -a -b -c)
+  # In that case the value will be 'bc'. It will then try to parse b and c as flag options.
+  def parse_flag_option(option, value, short)
+    return option.trigger(self, @options, true) if value.nil?
+    unless short # Short can also have the format -abc
+      return add_error Clin::OptionUnexpectedArgumentError.new(option, value)
+    end
+
+    option.trigger(self, @options, true)
+    # The value is expected to be other flag options
+    parse_compact_flag_options(value)
+  end
+
+  # Parse compact flag_options(e.g. For -abc it will be called with 'bc')
+  # @param options [String] List of options where each char should correspond to a short option
+  def parse_compact_flag_options(options)
+    options.each_char do |s|
+      option = @command.find_option_by(short: "-#{s}")
+      if option && !option.flag?
+        message = "Cannot combine short options that expect argument: #{option}"
+        add_error Clin::OptionError.new(message, option)
+        break
+      end
+      parse_flag_option(option, nil, true)
+    end
+  end
+
+  # Handle the case where the option was not defined in the command.
+  # @param name [String] name used in the command.
+  # @param value [String] Value of the option if applicable.
+  # Add [UnknownOptionError] if the command doesn't allow unknown options.
+  def handle_unknown_option(name, value)
+    unless @command.skip_options?
+      add_error Clin::UnknownOptionError.new(name)
+      return
+    end
+    value = complete(value)
+    @skipped_options += [name, value]
+  end
+
+  def add_error(err)
+    @errors << err
+  end
+end

data/lib/clin/shell.rb

@@ -1,4 +1,5 @@
 require 'clin'
+require 'clin/line_reader'
 
 # Class the offer helper method to interact with the user using the command line
 class Clin::Shell
@@ -8,19 +9,34 @@ class Clin::Shell
   # Output stream, default: STDOUT
   attr_accessor :out
 
+  # Text builder instance that is used to stream
+  attr_accessor :text
+
   def initialize(input: STDIN, output: STDOUT)
     @in = input
     @out = output
     @yes_or_no_persist = false
     @override_persist = false
+    @text = Clin::Text.new
+  end
+
+  def say(line, indent: '')
+    @out.puts text.line(line, indent: indent)
+  end
+
+  # Indent the current output
+  def indent(indent, &block)
+    text.indent(indent, &block)
   end
 
   # Ask a question
   # @param statement [String]
   # @param default [String]
-  # @param autocomplete [Array|Proc] Filter for autocomplete
-  def ask(statement, default: nil, autocomplete: nil)
-    answer = scan(statement, autocomplete: autocomplete)
+  # @param autocomplete [Array|Proc] Filter for autocomplete (Need Readline)
+  # @param echo [Boolean] If false no character will be displayed during input
+  # @param add_to_history [Boolean] If the answer should be added to history. (Need Readline)
+  def ask(statement, default: nil, autocomplete: nil, echo: true, add_to_history: true)
+    answer = scan(statement, autocomplete: autocomplete, echo: echo, add_to_history: add_to_history)
     if answer.blank?
       default
     else
@@ -28,6 +44,10 @@ class Clin::Shell
     end
   end
 
+  def password(statement, default: nil)
+    ask(statement, default: default, echo: false, add_to_history: false)
+  end
+
   # Ask a question and expect the result to be in the list of choices
   # Will continue asking until the input is correct
   # or if a default value is supplied then empty will return.
@@ -43,6 +63,17 @@ class Clin::Shell
                                                  default: default, allow_initials: allow_initials)
   end
 
+  # Ask a question with a list of possible answer.
+  # Answer can either be selected using their name or their index
+  # e.g.
+  # Select answer:
+  # 1. Choice A
+  # 2. Choice B
+  # 3. Choice C
+  def select(statement, choices, default: nil)
+    Clin::ShellInteraction::Select.new(self).run(statement, choices, default: default)
+  end
+
   # Expect the user the return yes or no(y/n also works)
   # @param statement [String] Question to ask
   # @param default [String] Default value(yes/no)
@@ -93,18 +124,8 @@ class Clin::Shell
   end
 
   # Prompt the statement to the user and return his reply.
-  # @param statement [String]
-  # @param autocomplete [Array|Block]
-  protected def scan(statement, autocomplete: nil)
-    unless autocomplete.nil?
-      Readline.completion_proc = if autocomplete.is_a? Proc
-                                   autocomplete
-                                 else
-                                   proc { |s| autocomplete.grep(/^#{Regexp.escape(s)}/) }
-                                 end
-    end
-    Readline.completion_append_character = nil
-    Readline.readline(statement + ' ', true)
+  protected def scan(statement, options = {})
+    Clin::LineReader.scan(self, statement + ' ', options)
   end
 end
 

data/lib/clin/shell_interaction/choose.rb

@@ -1,4 +1,5 @@
 require 'clin'
+require 'clin/text'
 
 # Handle a choose question
 class Clin::ShellInteraction::Choose < Clin::ShellInteraction
@@ -41,19 +42,26 @@ class Clin::ShellInteraction::Choose < Clin::ShellInteraction
     end
   end
 
+  # Print help
   protected def print_choices_help(choices, allow_initials: false)
-    puts 'Choose from:'
+    shell.say choice_help(choices, allow_initals: allow_initials)
+  end
+
+  def choice_help(choices, allow_initials: false)
     used_initials = Set.new
-    choices.each do |choice, description|
-      suf = choice.to_s
-      suf += ", #{description}" unless description.blank?
-      line = if allow_initials && !used_initials.include?(choice[0])
-               used_initials << choice[0]
-               "  #{choice[0]} - #{suf}"
-             else
-               "      #{suf}"
-             end
-      puts line
+    Clin::Text.new do |t|
+      t.line 'Choose from:'
+      t.table(indent: 2, border: false, separate_blank: false) do |m|
+        m.column_delimiter(allow_initials ? [' - ', '  '] : ['  '])
+        choices.each do |choice, description|
+          if allow_initials
+            inital = used_initials.add?(choice[0]) ? choice[0] : nil
+            m.row inital, choice.to_s, description
+          else
+            m.row choice.to_s, description
+          end
+        end
+      end
     end
   end
 end

data/lib/clin/shell_interaction/file_conflict.rb

@@ -15,6 +15,9 @@ class Clin::ShellInteraction::FileConflict < Clin::ShellInteraction
     result
   end
 
+  # Handle the use choice
+  # @return [Boolean] true/false if the user made a choice or
+  #   nil if the question needs to be asked again
   protected def handle_choice(choice, filename, &block)
     case choice
     when :yes
@@ -24,7 +27,7 @@ class Clin::ShellInteraction::FileConflict < Clin::ShellInteraction
     when :always
       return persist!
     when :quit
-      puts 'Aborting...'
+      shell.say 'Aborting...'
       fail SystemExit
     when :diff
       show_diff(filename, block.call)

data/lib/clin/shell_interaction/select.rb

@@ -0,0 +1,44 @@
+require 'clin'
+require 'clin/text'
+
+# Handle a choose question. Where you select the choices with a number
+# $ Choose:
+# 1. Choice A
+# 2. Choice B
+# 3. Choice B
+#
+class Clin::ShellInteraction::Select < Clin::ShellInteraction::Choose
+  def run(statement, choices, default: nil, start_index: 1)
+    choices = convert_choices(choices)
+    loop do
+      shell.say statement
+      shell.say choice_help(choices, start_index)
+      answer = @shell.ask('>', default: default, autocomplete: choices.keys)
+      next if answer.nil?
+      choice = get_choice(choices, answer, start_index)
+      return choice unless choice.nil?
+    end
+  end
+
+  def choice_help(choices, start_index)
+    Clin::Text::Table.new(border: false, col_delim: ' ') do |t|
+      i = start_index
+      choices.each do |key, description|
+        key = "#{key}," unless description.blank?
+        row = ["#{i}.", key]
+        row << description unless description.blank?
+        t.row row
+        i += 1
+      end
+    end
+  end
+
+  def get_choice(choices, answer, start_index)
+    i = start_index
+    choices.each do |choice, _|
+      return choice if choice.casecmp(answer) == 0 || i.to_s == answer
+      i += 1
+    end
+    nil
+  end
+end

data/lib/clin/shell_interaction.rb

@@ -32,3 +32,4 @@ end
 require 'clin/shell_interaction/file_conflict'
 require 'clin/shell_interaction/yes_or_no'
 require 'clin/shell_interaction/choose'
+require 'clin/shell_interaction/select'