drudge 0.4.0

data/features/step_definitions/scripts_steps.rb

@@ -0,0 +1,19 @@
+require 'fileutils'
+
+Given(/^the file "(.+?)" is executable$/) do |file_name|
+  in_current_dir do
+    FileUtils.chmod "a+x", file_name
+  end
+end
+
+Given(/^a Ruby script called "(.+?)" with:$/) do |script_name, contents|
+  steps %Q{
+    Given a file named "#{script_name}" with:
+    """
+    #!/usr/bin/env ruby
+    
+    #{contents}
+    """
+    And the file "#{script_name}" is executable
+  }
+end

data/features/support/env.rb

@@ -0,0 +1,5 @@
+require 'cucumber'
+require 'aruba/cucumber'
+require 'rspec/expectations'
+
+ENV['PATH'] = "#{File.expand_path '../../tmp/aruba', __dir__}#{File::PATH_SEPARATOR}#{ENV['PATH']}"

data/features/variable-length-argument-lists.feature

@@ -0,0 +1,111 @@
+Feature: Splatt Arguments
+  Ruby 2.0 supports splatt (*args) arguments. 
+  I want a close mapping between splatt arguements and the command line.
+
+Scenario Outline: Splatt arguments at the end of the command
+  Given a Ruby script called "cli" with:
+  """
+  require 'drudge'
+
+  class Cli < Drudge
+
+    desc "Greets people"
+    def greet(from, *messages)
+      puts "#{from} says: #{messages.join(', ')}" 
+    end
+
+  end
+
+  Cli.dispatch
+  """  
+  When I run `<command>`
+  Then the output should contain "<output>"
+
+  Examples: 
+     | command                                 | output                              |
+     | cli greet                               | error: expected a value for <from>: |
+     | cli greet Santa Hi                      | Santa says: Hi                      |
+     | cli greet Santa Hi Aloha                | Santa says: Hi, Aloha               |
+     | cli greet Santa Hi Aloha 'Good Morning' | Santa says: Hi, Aloha, Good Morning |
+ 
+
+  Scenario Outline: Splatt arguments in the middle of the command
+    Given a Ruby script called "cli" with:
+    """
+    require 'drudge'
+
+    class Cli < Drudge
+
+      desc "Greets people"
+      def greet(from, *messages, to)
+        puts "#{from} says: #{messages.join(', ')} to #{to}"
+      end
+    end
+
+    Cli.dispatch
+    """
+    When I run `<command>`
+    Then the output should contain "<output>"
+
+    Examples:
+       | command                      | output                             |
+       | cli greet                    | error: expected a value for <from> |
+       | cli greet Santa              | error: expected a value for <to>   |
+       | cli greet Santa Joe          | Santa says:  to Joe                |
+       | cli greet Santa Hi Joe       | Santa says: Hi to Joe              |
+       | cli greet Santa Hi Aloha Joe | Santa says: Hi, Aloha to Joe       |
+
+  Scenario Outline: Splatt arguments at the beginning of the ocmmand
+    Given a Ruby script called "cli" with:
+    """
+    require 'drudge'
+
+    class Cli < Drudge
+
+      desc "Greets people"
+      def greet(*greeters, message, to)
+        puts "#{greeters.join(', ')} all say: #{message} to #{to}"
+      end
+    end
+
+    Cli.dispatch
+    """
+    When I run `<command>`
+    Then the output should contain "<output>"
+
+    Examples:
+         | command                          | output                                |
+         | cli greet                        | error: expected a value for <message> |
+         | cli greet Hi                     | error: expected a value for <to>      |
+         | cli greet Hi Joe                 | all say: Hi to Joe                    |
+         | cli greet Santa Hi Joe           | Santa all say: Hi to Joe              |
+         | cli greet Santa Spiderman Hi Joe | Santa, Spiderman all say: Hi to Joe   |
+
+
+  Scenario Outline: Splatt arguments combined with optional arguments
+    Given a Ruby script called "cli" with:
+    """
+    require 'drudge'
+
+    class Cli < Drudge
+
+      desc "Greets people"
+      def greet(from, first_message = 'Hi', *messages,  to)
+        puts "#{from} says first #{first_message}, then #{messages.join(', ')} to #{to}"
+      end
+    end
+
+    Cli.dispatch
+    """
+    When I run `<command>`
+    Then the output should contain "<output>"
+
+    Examples:
+         | command                                        | output                                                  |
+         | cli greet                                      | error: expected a value for <from>                      |
+         | cli greet Santa                                | error: expected a value for <to>                        |
+         | cli greet Santa Joe                            | Santa says first Hi, then  to Joe                       |
+         | cli greet Santa Hello Joe                      | Santa says first Hello, then  to Joe                    |
+         | cli greet Santa Hello Aloha Joe                | Santa says first Hello, then Aloha to Joe               |
+         | cli greet Santa Hello Aloha 'Good Morning' Joe | Santa says first Hello, then Aloha, Good Morning to Joe |
+

data/lib/drudge.rb

@@ -0,0 +1,8 @@
+require "drudge/version"
+require "drudge/class_dsl"
+require "drudge/dispatch"
+
+class Drudge
+  include ClassDSL
+  include Dispatch
+end

data/lib/drudge/class_dsl.rb

@@ -0,0 +1,106 @@
+require 'drudge/kit'
+require 'drudge/command'
+require 'drudge/errors'
+
+class Drudge
+    
+  # A DSL that allows writing of a command line
+  # tool (kit) as a class
+  module ClassDSL
+
+
+    def self.included(cls)
+      cls.singleton_class.send :include, ClassMethods
+    end
+
+    # converts this into a (command) kit, 
+    def to_kit(name = $0)
+      Kit.new name, build_commands(self.class.__commands)
+    end
+
+    private
+
+    def build_commands(commands)
+      commands.map do |c|
+        Command.new(c[:name], c[:params], 
+                    -> (*args) { self.send c[:name], *args },
+                    **c[:meta])
+      end
+    end
+
+    module ClassMethods
+
+      # When found before a method definition, it marks the 
+      # Provides a short description for the next command
+      def desc(description)
+        @__command_meta ||= {}
+        @__command_meta[:desc] = description
+      end
+
+      def method_added(m)
+        if @__command_meta and @__command_meta[:desc]
+          meth = instance_method(m)
+
+          @__commands ||= []
+          @__commands << { name:   meth.name, 
+                           params: parse_command_parameters(meth.parameters),
+                           meta:   { desc: @__command_meta[:desc] } }
+
+          @__command_meta = {}
+        end
+
+        super
+      end
+
+      def __commands
+        merged_commands((@__commands || []), (superclass.__commands rescue []))
+      end
+
+      private 
+
+      def merged_commands(newer, older)
+        # review: this method seems too complex. find a simpler implemetnation
+        case
+        when older.empty? then newer
+        when newer.empty? then older
+        else 
+          deep_merger = -> (_, old, new) do
+            if Hash === old
+              old.merge(new, &deep_merger)
+            else
+              new
+            end
+          end
+
+          non_overriden       = older.reject { |c| newer.any? { |cc| cc[:name] == c[:name] } } 
+          newer_and_overriden = newer.map do |cmd|
+            overriden = older.find { |c| c[:name] == cmd[:name] }
+
+            if overriden
+              overriden.merge(cmd, &deep_merger)
+            else
+              cmd
+            end
+          end 
+
+          non_overriden + newer_and_overriden
+        end
+      
+      end
+
+      private
+
+      def parse_command_parameters(method_parameters)
+        method_parameters.map do |kind, name|
+          case kind
+          when :req then Param.any(name)
+          when :opt then Param.any(name, optional: true)
+          when :rest then Param.any(name, splatt: true)
+          else raise "Unsupported parameter type"
+          end
+        end
+      end
+    end
+    
+  end
+end

data/lib/drudge/command.rb

@@ -0,0 +1,100 @@
+require 'drudge/errors'
+require 'drudge/parsers'
+
+class Drudge
+
+  # Describes a command and helps executing it
+  # 
+  # The command is defined by a name and a list of arguments (see class Param).
+  # The body of the command is a lambda that accepts exactly the arguments
+
+  class Command
+    include Parsers
+
+    # The name of the command
+    attr_reader :name
+
+    # The list of parameters
+    attr_reader :params
+
+    # The command's body
+    attr_reader :body
+
+    # An optional short desicription of the command
+    attr_reader :desc
+
+    # Initializes a new command
+    def initialize(name, params = [], body, desc: "")
+      @name   = name.to_sym
+      @params = params
+      @body   = body
+
+      @desc   = desc
+    end
+
+    # runs the command 
+    def dispatch(*args)
+      @body.call(*args)
+    rescue ArgumentError => e
+      raise CommandArgumentError.new(name), e.message
+    end
+
+    # creates an argument parser for the command
+    def argument_parser
+      end_of_args = eos("extra command line arguments provided")
+
+      parser = params.reverse.reduce(end_of_args) do |rest, param|
+        p = param.argument_parser
+
+        case
+        when param.optional? then ((p > rest) | rest).describe("[#{p}] #{rest}")
+        when param.splatt? then (p.repeats(till: rest) > rest).describe("[#{p} ...] #{rest}")
+        else p > rest
+        end
+      end
+    end
+
+  end
+
+  # Represents a command parameter
+  class Param
+    include Parsers
+
+    TYPES = %i[any string]
+
+    # the argument's name
+    attr_reader :name
+
+    # the  argument's type
+    attr_reader :type
+
+    attr_reader :optional
+    alias_method :optional?, :optional
+
+    attr_reader :splatt
+    alias_method :splatt?, :splatt
+    
+    def initialize(name, type, optional: false, splatt: false)
+      @name = name.to_sym
+      @type = type.to_sym
+      @optional = !! optional 
+      @splatt = !! splatt
+    end
+
+    # returns a parser that is able to parse arguments
+    # fitting this parameter
+    def argument_parser
+      arg(name, value(/.+/))
+    end
+
+    # factory methods for every type of parameter
+    class << self
+      TYPES.each do |type|
+        define_method type do |name, *rest|
+          new(name, type, *rest)
+        end
+      end
+    end
+  end
+
+end

data/lib/drudge/dispatch.rb

@@ -0,0 +1,41 @@
+require 'drudge/ext'
+require 'drudge/parsers/tokenizer'
+
+class Drudge
+
+  module Dispatch
+
+    def self.included(cls)
+      cls.singleton_class.send :include, ClassMethods
+    end
+
+    module ClassMethods
+      Tokenizer = Drudge::Parsers::Tokenizer
+
+      # Runs the CLI with the specified arguments
+      def dispatch(command_name = File.basename($0), args = ARGV)
+        cli_kit       = self.new.to_kit(command_name)
+        complete_args = command_name, *args
+
+        argument_parser       = cli_kit.argument_parser
+        _, *command_arguments = argument_parser.parse!(complete_args)[:args]
+
+        cli_kit.dispatch(*command_arguments)
+
+      rescue CliError => e
+        puts "#{e.command}: #{e.message}"
+      rescue ParseError => pe
+        $stderr.puts <<-EOS.undent
+          error: #{pe.message}:
+
+              #{Tokenizer.untokenize(pe.input)}
+              #{Tokenizer.underline_token(pe.input, 
+                                          pe.remaining_input.first)}
+        EOS
+
+
+      end
+
+    end
+  end
+end

data/lib/drudge/errors.rb

@@ -0,0 +1,30 @@
+class Drudge
+  # a c
+  class CliError < StandardError
+    # the command that produced the error
+    attr_reader :command
+
+    def initialize(command)
+      @command = command.to_s
+    end
+  end
+
+  # Identifies a parse error
+  class ParseError < StandardError
+
+    attr_reader :remaining_input
+    attr_reader :input
+
+    def initialize(input, remaining_input)
+      @input, @remaining_input = input, remaining_input
+    end
+    
+  end
+
+  # Identifies a problem with the arguments
+  class CommandArgumentError < CliError; end
+
+  # The user asked to execute a command that doesn't exist
+  class UnknownCommandError < CliError; end
+end
+

data/lib/drudge/ext.rb

@@ -0,0 +1,17 @@
+# Extensions to standard classes
+
+class String
+
+  # undents the string by removeing as much leading space
+  # as the first line has. 
+  #
+  # Useful for cases like: 
+  #   puts <<-EOS.undent
+  #     bla bla bla
+  #     bla 
+  #   EOS
+  #
+  def undent
+    gsub(/^.{#{slice(/^ +/).length}}/, '')
+  end unless method_defined?(:undent)
+end