clin 0.1.0

data/lib/clin/command.rb

@@ -0,0 +1,195 @@
+require 'clin'
+require 'clin/command_options_mixin'
+require 'clin/argument'
+require 'shellwords'
+require 'clin/common/help_options'
+
+# Clin Command
+class Clin::Command < Clin::CommandOptionsMixin
+
+  class_attribute :args
+  class_attribute :description
+
+
+  # Redispatch will be reset to nil when inheriting a dispatcher command
+  class_attribute :_redispatch_args
+  class_attribute :_abstract
+  class_attribute :_exe_name
+
+  self.args = []
+  self.description = ''
+  self._abstract = false
+
+
+  # Trigger when a class inherit this class
+  # Rest class_attributes that should not be shared with subclass
+  # @param subclass [Clin::Command]
+  def self.inherited(subclass)
+    subclass._redispatch_args = nil
+    subclass._abstract = false
+    super
+  end
+
+  # Mark the class as abstract
+  def self.abstract(value)
+    self._abstract = value
+  end
+
+  # Set or get the exe name.
+  # Executable name that will be display in the usage.
+  # If exe_name is not set in a class or it's parent it will use the global setting Clin.exe_name
+  # @param value [String] name of the exe.
+  # ```
+  # class Git < Clin::Command
+  #   exe_name 'git'
+  #   arguments '<command> <args>...'
+  # end
+  # Git.usage # => git <command> <args>...
+  # ```
+  def self.exe_name(value=nil)
+    self._exe_name = value unless value.nil?
+    self._exe_name ||= Clin.exe_name
+  end
+
+  def self.arguments(args)
+    self.args = []
+    [*args].map(&:split).flatten.each do |arg|
+      self.args += [Clin::Argument.new(arg)]
+    end
+  end
+
+  def self.usage
+    a = [exe_name, args.map(&:original).join(' '), '[Options]']
+    a.reject(&:blank?).join(' ')
+  end
+
+  def self.banner
+    "Usage: #{usage}"
+  end
+
+  # Parse the command and initialize the command object with the parsed options
+  # @param argv [Array|String] command line to parse.
+  def self.parse(argv = ARGV, fallback_help: true)
+    argv = Shellwords.split(argv) if argv.is_a? String
+    argv = argv.clone
+    options_map = parse_options(argv)
+    error = nil
+    begin
+      args_map = parse_arguments(argv)
+    rescue Clin::MissingArgumentError => e
+      error = e
+    rescue Clin::FixedArgumentError => e
+      raise e unless fallback_help
+      error = e
+    end
+    args_map ||= {}
+
+    options = options_map.merge(args_map)
+    return handle_dispatch(options) unless self._redispatch_args.nil?
+    obj = new(options)
+    if error
+      fail Clin::HelpError, option_parser if fallback_help
+      fail error
+    end
+    obj
+  end
+
+  # Parse the options in the argv.
+  # @return [Array] the list of argv that are not options(positional arguments)
+  def self.parse_options(argv)
+    out = {}
+    parser = option_parser(out)
+    parser.parse!(argv)
+    out
+  end
+
+  # Build the Option Parser object
+  # Used to parse the option
+  # Useful for regenerating the help as well.
+  def self.option_parser(out = {})
+    OptionParser.new do |opts|
+      opts.banner = banner
+      opts.separator ''
+      opts.separator 'Options:'
+      register_options(opts, out)
+      dispatch_doc(opts)
+      unless description.blank?
+        opts.separator "\nDescription:"
+        opts.separator description
+      end
+      opts.separator ''
+    end
+  end
+
+  def self.execute_general_options(options)
+    general_options.each do |_cls, gopts|
+      gopts.execute(options)
+    end
+  end
+
+  # Parse the argument. The options must have been strip out first.
+  def self.parse_arguments(argv)
+    out = {}
+    self.args.each do |arg|
+      value, argv = arg.parse(argv)
+      out[arg.name.to_sym] = value
+    end
+    out.delete_if { |_, v| v.nil? }
+  end
+
+  # Redispatch the command to a sub command with the given arguments
+  # @param args [Array<String>|String] New argument to parse
+  # @param prefix [String] Prefix to add to the beginning of the command
+  # @param commands [Array<Clin::Command.class>] Commands that will be tried against
+  # If no commands are given it will look for Clin::Command in the class namespace
+  # e.g. If those 2 classes are defined.
+  # `MyDispatcher < Clin::Command` and `MyDispatcher::ChildCommand < Clin::Command`
+  # Will test against ChildCommand
+  def self.dispatch(args, prefix: nil, commands: nil)
+    self._redispatch_args = [[*args], prefix, commands]
+  end
+
+  # Method called after the argument have been parsed and before creating the command
+  # @param params [List<String>] Parsed params from the command line.
+  def self.handle_dispatch(params)
+    args, prefix, commands = self._redispatch_args
+    commands ||= default_commands
+    dispatcher = Clin::CommandDispatcher.new(commands)
+    args = args.map { |x| params[x] }.flatten
+    args = prefix.split + args unless prefix.nil?
+    begin
+      dispatcher.parse(args)
+    rescue Clin::HelpError
+      raise Clin::HelpError, option_parser
+    end
+  end
+
+  def self.dispatch_doc(opts)
+    return if self._redispatch_args.nil?
+    opts.separator 'Examples: '
+    commands = (self._redispatch_args[2] || default_commands)
+    commands.each do |cmd_cls|
+      opts.separator "\t#{cmd_cls.usage}"
+    end
+  end
+
+  def self.default_commands
+    # self.constants.map { |c| self.const_get(c) }.select { |c| c.is_a?(Class) && (c < Clin::Command) }
+    self.subcommands
+  end
+
+  # List the subcommands
+  # The subcommands are all the Classes inheriting this one that are not set to abstract
+  def self.subcommands
+    self.subclasses.reject(&:_abstract)
+  end
+
+  general_option 'Clin::HelpOptions'
+
+  attr_accessor :params
+
+  def initialize(params)
+    @params = params
+    self.class.execute_general_options(params)
+  end
+end

data/lib/clin/command_dispatcher.rb

@@ -0,0 +1,48 @@
+require 'clin'
+require 'clin/command'
+
+# Class charge dispatching the CL to the right command
+class Clin::CommandDispatcher
+  attr_accessor :commands
+
+  # Create a new command dispatcher.
+  # @param commands [Array<Clin::Command.class>] List of commands that can be dispatched.
+  #   If commands is nil it will get all the subclass of Clin::Command loaded.
+  def initialize(*commands)
+    @commands = commands.empty? ? Clin::Command.subcommands : commands.flatten
+  end
+
+  # Parse the command line using the given arguments
+  # It will return the newly initialized command with the arguments if there is a match
+  # Otherwise will fail and display the help message
+  # @param argv [Array<String>] Arguments
+  # @return [Clin::Command]
+  def parse(argv = ARGV)
+    errors = 0
+    argv = Shellwords.split(argv) if argv.is_a? String
+    @commands.each do |cmd|
+      begin
+        return cmd.parse(argv, fallback_help: false)
+      rescue Clin::ArgumentError
+        errors += 1
+      end
+    end
+    fail Clin::HelpError, help_message
+  end
+
+  # Helper method to parse against all the commands
+  # @see #parse
+  def self.parse(argv=ARGV)
+    Clin::CommandDispatcher.new.parse(argv)
+  end
+
+  # Generate the help message for this dispatcher
+  # @return [String]
+  def help_message
+    message = "Usage:\n"
+    commands.each do |command|
+      message << "\t#{command.usage}\n"
+    end
+    message
+  end
+end

data/lib/clin/command_options_mixin.rb

@@ -0,0 +1,88 @@
+require 'clin'
+require 'clin/option'
+
+# Template class for reusable options and commands
+# It provide the method to add options to a command
+class Clin::CommandOptionsMixin
+  class_attribute :options
+  class_attribute :general_options
+  self.options = []
+  self.general_options = {}
+
+
+  # Add an option
+  # @param args list of arguments.
+  #   * First argument must be the name if no block is given.
+  #     It will set automatically read the value into the hash with  +name+ as key
+  #   * The remaining arguments are OptionsParser#on arguments
+  # ```
+  #   option :require, '-r', '--require [LIBRARY]', 'Require the library'
+  #   option '-h', '--helper', 'Show the help' do
+  #     puts opts
+  #     exit
+  #   end
+  # ```
+  def self.opt_option(*args, &block)
+    add_option Clin::Option.new(*args, &block)
+  end
+
+  # Add an option.
+  # Helper method that just create a new Clin::Option with the argument then call add_option
+  # ```
+  #   option :show, 'Show some message'
+  #   # => -s --show              SHOW Show some message
+  #   option :require, 'Require a library', short: false, optional: true, argument: 'LIBRARY'
+  #   # => --require [LIBRARY]    Require a library
+  #   option :help, 'Show the help', argument: false do
+  #     puts opts
+  #     exit
+  #   end
+  #   # => -h --help              Show the help
+  # ```
+  def self.option(name, description, **config, &block)
+    add_option Clin::Option.new(name, description, **config, &block)
+  end
+
+  # For an option that does not have an argument
+  # Same as .option except it will default argument to false
+  # ```
+  #   option :verbose, 'Use verbose' #=> -v --verbose will be added to the option of this command
+  # ```
+  def self.flag_option(name, description, **config, &block)
+    add_option Clin::Option.new(name, description, **config.merge(argument: false), &block)
+  end
+
+  def self.add_option(option)
+    # Need to use += instead of << otherwise the parent class will also be changed
+    self.options += [option]
+  end
+
+  # Add a general option
+  # @param option_cls [Class<GeneralOption>] Class inherited from GeneralOption
+  # @param config [Hash] General option config. Check the general option config.
+  def self.general_option(option_cls, config = {})
+    option_cls = option_cls.constantize if option_cls.is_a? String
+    self.general_options = self.general_options.merge(option_cls => option_cls.new(config))
+  end
+
+  # Remove a general option
+  # Might be useful if a parent added the option but is not needed in this child.
+  def self.remove_general_option(option_cls)
+    option_cls = option_cls.constantize if option_cls.is_a? String
+    self.general_options = self.general_options.except(option_cls)
+  end
+
+  # To be called inside OptionParser block
+  # Extract the option in the command line using the OptionParser and map it to the out map.
+  # @param opts [OptionParser]
+  # @param out [Hash] Where the options shall be extracted
+  def self.register_options(opts, out)
+    options.each do |option|
+      option.register(opts, out)
+    end
+
+    general_options.each do |_cls, option|
+      option.class.register_options(opts, out)
+    end
+  end
+end

data/lib/clin/common/help_options.rb

@@ -0,0 +1,25 @@
+require 'clin'
+require 'clin/general_option'
+# Help option class
+# Add the help option to you command
+# ```
+# class MyCommand < Clin::Command
+#   general_option Clin::HelpOptions
+# end
+# ```
+# Then running you command with -h or --help will show the help menu
+class Clin::HelpOptions < Clin::GeneralOption
+  flag_option :help, 'Show the help.' do |opts, out, _|
+    out[:help] = opts
+  end
+
+  def initialize(raise: true)
+    @raise = raise
+  end
+
+
+  def execute(options)
+    return unless @raise
+    fail Clin::HelpError, options[:help] if options[:help]
+  end
+end

data/lib/clin/errors.rb

@@ -0,0 +1,31 @@
+# Contains the errors for Clin
+module Clin
+  # Parent error class for all Clin errors
+  Error = Class.new(RuntimeError)
+
+  # Error cause by the user input(when parsing command)
+  CommandLineError = Class.new(Error)
+
+  # Error when the help needs to be shown
+  HelpError = Class.new(CommandLineError)
+
+  # Error when an positional argument is wrong
+  ArgumentError = Class.new(CommandLineError)
+
+  # Error when a fixed argument is not matched
+  class FixedArgumentError < ArgumentError
+    def initialize(argument = '', got = '')
+      super("Expecting '#{argument}' but got '#{got}'")
+    end
+  end
+
+  # Error when a command is missing an argument
+  class MissingArgumentError < ArgumentError
+    def initialize(message = '')
+      super("Missing argument #{message}")
+    end
+  end
+
+  # Error when a option is wrong
+  OptionError = Class.new(CommandLineError)
+end

data/lib/clin/general_option.rb

@@ -0,0 +1,15 @@
+require 'clin'
+
+class Clin::GeneralOption < Clin::CommandOptionsMixin
+
+  def initialize(config = {})
+
+  end
+
+  # It get the params the general options needs and do whatever the option is suppose to do with it.
+  # Method called in the initialize of the command. This allow general options to be extracted when parsing a command line
+  # as well as calling the command directly in the code
+  # @param _params [Hash] Params got in the command
+  def execute(_params)
+  end
+end

data/lib/clin/option.rb

@@ -0,0 +1,102 @@
+require 'clin'
+
+# Option container.
+class Clin::Option
+  attr_accessor :name, :description, :optional_argument, :block
+  attr_reader :short, :long, :argument
+
+  def initialize(name, description, short: nil, long: nil, argument: nil, optional_argument: false, &block)
+    @name = name
+    @description = description
+    @short = short
+    @long = long
+    @optional_argument = optional_argument
+    @argument = argument
+    @block = block
+  end
+
+  # Register the option to the Option Parser
+  # @param opts [OptionParser]
+  # @param out [Hash] Out options mapping
+  def register(opts, out)
+    if @block.nil?
+      opts.on(*option_parser_arguments) do |value|
+        on(value, out)
+      end
+    else
+      opts.on(*option_parser_arguments) do |value|
+        block.call(opts, out, value)
+      end
+    end
+  end
+
+  def default_short
+    "-#{name[0].downcase}"
+  end
+
+  def default_long
+    "--#{name.downcase}"
+  end
+
+  def default_argument
+    name.to_s.upcase
+  end
+
+  # Get the short option
+  # If @short is nil it will use #default_short
+  # If @short is false it will return nil
+  # @return [String]
+  def short
+    return nil if @short === false
+    @short ||= default_short
+  end
+
+  # Get the long option
+  # If @long is nil it will use #default_long
+  # If @long is false it will return nil
+  # @return [String]
+  def long
+    return nil if @long === false
+    @long ||= default_long
+  end
+
+  # Get the argument option
+  # If @argument is nil it will use #default_argument
+  # If @argument is false it will return nil
+  # @return [String]
+  def argument
+    return nil if @argument === false
+    @argument ||= default_argument
+  end
+
+  def option_parser_arguments
+    args = [short, long_argument, description]
+    args.compact
+  end
+
+  def on(value, out)
+    out[@name] = value
+  end
+
+  def ==(other)
+    return false unless other.is_a? Clin::Option
+    @name == other.name &&
+        @description == other.description &&
+        short == other.short &&
+        long == other.long &&
+        argument == other.argument &&
+        @optional_argument == other.optional_argument &&
+        @block == other.block
+  end
+
+  protected
+  def long_argument
+    return nil unless long
+    out = long
+    if argument
+      arg = @optional_argument ? "[#{argument}]" : argument
+      out += " #{arg}"
+    end
+    out
+  end
+end

data/lib/clin/version.rb

@@ -0,0 +1,4 @@
+# Clin version
+module Clin
+  VERSION = '0.1.0'
+end

data/lib/clin.rb

@@ -0,0 +1,29 @@
+require 'active_support'
+require 'active_support/core_ext'
+require 'optparse'
+require 'clin/version'
+
+# Clin Global module. All classes and clin modules should be inside this module
+module Clin
+  def self.default_exe_name
+    'command'
+  end
+
+  # Global exe_name
+  # If this is not override it will be 'command'
+  def self.exe_name
+    @exe_name ||= Clin.default_exe_name
+  end
+
+  # Set the global exe name
+  def self.exe_name=(value)
+    @exe_name=value
+  end
+end
+
+require 'clin/command'
+require 'clin/command_options_mixin'
+require 'clin/general_option'
+require 'clin/command_dispatcher'
+require 'clin/common/help_options'
+require 'clin/errors'

data/spec/cli/argument_spec.rb

@@ -0,0 +1,117 @@
+require 'spec_helper'
+require 'clin/argument'
+
+RSpec.describe Clin::Argument do
+
+  describe '#check_optional' do
+    subject { Clin::Argument.new('') }
+    it { expect(subject.check_optional('not_optional')).to eq('not_optional') }
+    it { expect(subject.check_optional('<not_optional>')).to eq('<not_optional>') }
+    it { expect(subject.check_optional('[optional]')).to eq('optional') }
+    it { expect(subject.check_optional('[<optional>]')).to eq('<optional>') }
+    it { expect(subject.check_optional('[<optional>...]')).to eq('<optional>...') }
+    it { expect(subject.check_optional('[optional...]')).to eq('optional...') }
+    it { expect { subject.check_optional('[optional') }.to raise_error(Clin::Error) }
+    it { expect { subject.check_optional('[optional]...') }.to raise_error(Clin::Error) }
+
+    it 'expect optional to set instance variable' do
+      subject.check_optional('[optional]')
+      expect(subject.optional).to be true
+    end
+
+    it 'expect not optional to keep instance variable' do
+      subject.check_optional('not_optional')
+      expect(subject.optional).to be false
+    end
+  end
+
+  describe '#check_multiple' do
+    subject { Clin::Argument.new('') }
+    it { expect(subject.check_multiple('multiple...')).to eq('multiple') }
+    it { expect(subject.check_multiple('<multiple>...')).to eq('<multiple>') }
+    it { expect(subject.check_multiple('not_multiple')).to eq('not_multiple') }
+    it { expect(subject.check_multiple('<not_multiple>')).to eq('<not_multiple>') }
+
+    it 'expect to set instance variable' do
+      subject.check_multiple('multiple...')
+      expect(subject.multiple).to be true
+    end
+
+    it 'expect not to set instance variable' do
+      subject.check_multiple('not_multiple')
+      expect(subject.multiple).to be false
+    end
+  end
+
+  describe '#check_variable' do
+    subject { Clin::Argument.new('') }
+    it { expect(subject.check_variable('not_variable')).to eq('not_variable') }
+    it { expect(subject.check_variable('<variable>')).to eq('variable') }
+
+    it { expect { subject.check_variable('<variable') }.to raise_error(Clin::Error) }
+    it { expect { subject.check_variable('<variable...') }.to raise_error(Clin::Error) }
+    it 'expect optional to set instance variable' do
+      subject.check_variable('<variable>')
+      expect(subject.variable).to be true
+    end
+
+    it 'expect not optional to keep instance variable' do
+      subject.check_variable('not_variable')
+      expect(subject.variable).to be false
+    end
+  end
+
+  describe '#initialize' do
+    subject { Clin::Argument.new('[<optional_var_mul>...]') }
+    it { expect(subject.name).to eq('optional_var_mul') }
+    it { expect(subject.optional).to be true }
+    it { expect(subject.multiple).to be true }
+    it { expect(subject.variable).to be true }
+  end
+
+  describe 'parse' do
+    context 'when argument is optional' do
+      subject { Clin::Argument.new('[<optional>]') }
+
+      it 'get the argument' do
+        value, rem = subject.parse(%w(value1 value2))
+        expect(value).to eq('value1')
+        expect(rem).to eq(['value2'])
+      end
+
+      it 'work when there is no argument' do
+        value, rem = subject.parse([])
+        expect(value).to be nil
+        expect(rem).to eq([])
+      end
+    end
+
+    context 'when multiple arguments are allowed' do
+      subject { Clin::Argument.new('<multiple>...') }
+
+      it 'get the argument' do
+        value, rem = subject.parse(%w(value1 value2))
+        expect(value).to eq(%w(value1 value2))
+        expect(rem).to eq([])
+      end
+
+      it { expect { subject.parse([]).to raise_error(Clin::CommandLineError) } }
+    end
+
+    context 'when argument must match exactly' do
+      subject { Clin::Argument.new('argument') }
+
+      it 'get the argument' do
+        value, rem = subject.parse(['argument'])
+        expect(value).to eq('argument')
+        expect(rem).to eq([])
+      end
+      it { expect { subject.parse(['other_value']).to raise_error(Clin::CommandLineError) } }
+    end
+
+    context 'when multiple argument must match exactly' do
+      subject { Clin::Argument.new('argument...') }
+      it { expect { subject.parse(%w(argument other_value)).to raise_error(Clin::CommandLineError) } }
+    end
+  end
+end