drudge 0.4.0

data/lib/drudge/parsers/tokenizer.rb

@@ -0,0 +1,70 @@
+class Drudge
+  module Parsers
+
+    # tokenization of commandline arguments.
+    module Tokenizer
+      extend self
+
+      # tokenizes the arg-v list into an array of sexps
+      # the sexps are then suitable for the Drudge::parsers parser 
+      # combinators
+      def tokenize(argv)
+        argv.map.with_index do |arg, index|
+          [:val, arg, loc(index, arg.length)]
+        end
+      end
+
+      # given an array of sexps (as returned by tokenize) produce 
+      # a string representatio of that
+      def untokenize(sexps)
+        sexps.map do |type, arg, *_|
+          case type
+          when :val
+            arg
+          end
+        end.join(" ")
+      end
+
+      # produces a string that underlines a specific token 
+      # if no token is provided, the end of string is underlined
+      def underline_token(input, token, underline_char: '~')
+        line                 = untokenize(input)
+
+        if token
+          _, _, meta         = token
+          location           = meta[:loc]
+          _, _, token_length = location
+          white_space        = index_of_sexp_in_untokenized(input, location)
+        else
+          white_space        = line.length + 1
+          token_length       = 1
+          underline_char     = '^'
+        end
+
+        " " * white_space + underline_char * token_length
+      end
+
+
+      private 
+
+      def loc(index, start = 0, len)
+        {loc: [index, start, len]}
+      end
+
+      def index_of_sexp_in_untokenized(input, loc)
+        l_index, l_start, l_len = loc
+
+        prefix =
+        if l_index == 0 
+          0
+        else 
+          input[0..l_index - 1].map       { |_, _, meta|       meta[:loc]    }
+          .reduce(0) { |sum, (_, _, len)| sum + len + 1 } 
+        end
+
+        prefix + l_start
+      end
+    end
+
+  end
+end

data/lib/drudge/version.rb

@@ -0,0 +1,3 @@
+class Drudge
+  VERSION = "0.4.0"
+end

data/spec/drudge/class_dsl_spec.rb

@@ -0,0 +1,125 @@
+require 'spec_helper'
+
+require 'drudge/class_dsl'
+
+
+class Drudge
+  
+  class Sample
+    include ClassDSL
+
+    desc "An action with no params"
+    def verify
+      puts "Verified."
+    end
+  end
+
+  class AnotherSample < Sample
+
+    desc "a second action"
+    def second
+      puts "Second."
+    end
+  end
+
+
+  class OverridenCommand < Sample
+
+    desc "a second action"
+    def second
+      puts "Second."
+    end
+
+    def verify
+      puts "From overriden." 
+      super
+    end
+
+  end
+
+  class OverridenWithDesc < Sample
+
+    desc "Refined description"
+    def verify
+      puts "From overriden."
+      super
+    end
+
+  end
+
+  describe ClassDSL do
+
+    describe "defining actions" do
+
+      context "the 'desc' keyword marks a command" do
+
+        describe "the kit built from this class" do 
+          subject(:kit) { Sample.new.to_kit(:cli) }
+
+          its(:name) { should eq :cli }
+          its(:commands) { should have(1).items }
+
+          describe "the command 'verify'" do 
+            subject(:command) { kit.commands[0] }
+
+            its(:name)   { should eq :verify }
+            its(:params) { should be_empty }
+            its(:desc)   { should eq "An action with no params" }
+
+            it "has a body that invokes the verify method" do
+              expect_capture { command.dispatch }.to eq("Verified.\n")
+            end
+          end
+        end
+      end
+    end
+
+
+    describe "inheritance" do
+      describe "a sub-class adds to the actions from its parent" do
+
+        describe "the kit built from the sub-class" do
+          subject(:kit) { AnotherSample.new.to_kit(:cli) }
+
+          its(:commands) { should have(2).items }
+
+          it "should contain the command from the superclass as first element" do
+            expect(kit.commands[0].name).to eq :verify
+          end
+
+          it "should contain the command from the sub class as second element (because it was defined later)" do
+            expect(kit.commands[1].name).to eq :second
+          end
+        end
+
+        describe "the kit built from the parent class" do
+          subject(:kit) { Sample.new.to_kit(:cli) } 
+
+          its(:commands) { should have(1).items }
+        end
+      end
+
+      describe "a command whose corresponding method is overriden" do
+        it "invokes the metod in the sub-class and that method can call 'super' in normal fashion" do
+          kit = OverridenCommand.new.to_kit
+
+          expect_capture { kit.dispatch :verify }.to eq("From overriden.\nVerified.\n")
+        end
+      end
+
+      describe "kit with a command whose corresponding method and metdadata is overriden" do
+        subject(:kit) { OverridenWithDesc.new.to_kit(:cli) }
+
+        its(:commands) { should have(1).item }
+
+        describe "the overriden command" do
+          subject { kit.commands[0] }
+
+          its(:desc) { should eq "Refined description" }
+        end
+      end
+
+    end
+  end
+  
+end

data/spec/drudge/command_spec.rb

@@ -0,0 +1,81 @@
+require 'spec_helper'
+
+require 'drudge/command'
+
+class Drudge
+
+  describe Command do
+
+    context "command execution" do
+
+      describe "a command with no parameters" do 
+        subject do
+          Command.new(:verify, -> { puts "Verified." })
+        end
+
+        it "can be executed by calling the dispatch method" do
+          expect_capture { subject.dispatch }.to eq("Verified.\n")
+        end
+
+        describe "#dispatch" do
+          context "with no arguments"
+          it "doesn't accept normal arguments" do
+            expect { subject.dispatch(1) }.to raise_error(CommandArgumentError)
+          end
+
+          it "doesn't accept keyword arguments" do
+            expect { subject.dispatch(greeting: "hello") }.to raise_error(CommandArgumentError)
+          end
+        end
+      end
+
+    end
+
+    describe "a command with a couple of parameters" do 
+      subject do
+        Command.new(:greet,
+                    [ Param.any(:greeter),
+                      Param.any(:greeted)],
+                      -> (greeter, greeted) { puts "#{greeter} says 'hello' to #{greeted}" })
+      end
+
+      describe "#dispatch" do
+        it "accepts two arguments" do
+          expect_capture { subject.dispatch("Santa", "Superman") }.to eq("Santa says 'hello' to Superman\n")
+        end
+
+        it "raises an error when called with a wrong number of arguments" do
+          expect { subject.dispatch }.to raise_error(CommandArgumentError)
+          expect { subject.dispatch("Santa") }.to raise_error(CommandArgumentError)
+        end
+      end
+    end
+
+    describe "The command's description" do
+      subject do
+        Command.new(:verify, -> { puts "Verified." }, desc: "Verification")
+      end
+
+      its(:desc) { should eq "Verification" }
+    end
+
+    describe "Argument parsers" do
+      describe "a command called 'greet' with one parameter" do
+        subject(:command) do
+          Command.new(:greet, [Param.any(:greeted)], -> { puts "Hello" })
+        end
+
+        describe "the argument parser generated by this command" do
+          subject(:parser) do
+            command.argument_parser.collated_arguments
+          end
+
+          it { should tokenize_and_parse(%w[Joe]).as({args: %w[Joe]}) }
+          it { should_not tokenize_and_parse(%w[]) }
+          it { should_not tokenize_and_parse(%w[Joe Green]) }
+        end
+
+      end
+    end
+  end
+end

data/spec/drudge/kit_spec.rb

@@ -0,0 +1,50 @@
+require 'spec_helper'
+
+require 'drudge/kit'
+
+class Drudge
+
+  describe Kit do
+    describe "command execution" do
+
+      describe "a Kit with two zero-arg commands" do
+        subject(:kit) do 
+          Kit.new(:cli, 
+                  [dummy_cmd(:hello),
+                   dummy_cmd(:goodbye)])
+        end
+
+        it "executes the known command 'hello'" do
+          expect_capture { subject.dispatch "hello" }.to eq("hello\n")
+        end
+
+        it "requries a command to run" do 
+          expect { subject.dispatch }.to raise_error
+        end
+
+        it "reports an error for an unknown command" do
+          expect { subject.dispatch("bla") }.to raise_error(UnknownCommandError)
+        end
+
+        it "doesn't accept extra arguments" do
+          expect { subject.dispatch "hello", "dear", "sir" }.to raise_error(CommandArgumentError)
+        end
+
+        describe "#argument_parser" do
+          subject { kit.argument_parser }
+
+          it { should tokenize_and_parse(%w[cli hello]).as({args: %w[cli hello]}) }
+          it { should tokenize_and_parse(%w[cli goodbye]).as({args: %w[cli goodbye]}) }
+
+          it { should_not tokenize_and_parse(%w[cli foo]) }
+          it { should_not tokenize_and_parse(%w[cli hello someone]) }
+
+          it { should_not tokenize_and_parse([]) }
+        end
+
+      end
+
+    end
+  end
+
+end

data/spec/drudge/parsers/parse_results_spec.rb

@@ -0,0 +1,47 @@
+require 'spec_helper'
+require 'drudge/parsers/parse_results'
+
+class Drudge
+  module Parsers
+
+    describe ParseResults do
+      include ParseResults
+
+      describe ParseResult do 
+
+        describe ".+" do 
+          context "Success() + Success()" do 
+            it "is a a Success where '+' is applied to the underlying ParseValue" do
+              expect(Success(Single(1), [2, 3]) + Success(Single(2), [3])).to eq Success(Seq([1, 2]), [3])
+              expect(Success(Empty(), [2, 3]) + Success(Single(2), [3])).to eq Success(Single(2), [3])
+              expect(Success(Seq([1, 2]), [3, 4]) + Success(Single(3), [4])).to eq (Success(Seq([1, 2, 3]), [4]))
+            end
+          end
+          context "Success() + NoSuccess()" do
+            it "is a Failure()" do 
+              expect(Success(Single(1), [2, 3]) + Failure("error", [3])).to eq Failure("error", [3])
+            end
+          end
+
+          context "NoSuccess() + Success()" do
+            it "is a Failure()" do
+              expect(Failure("error", [3]) + Success(Single(2), [3, 4])).to eq Failure("error", [3])
+            end
+          end
+        end
+      end
+
+      describe ".success?" do 
+        it "returns true for a Success()" do
+          expect(Success(Single(1), []).success?).to be_true
+        end
+
+        it "returns false for all NoSuccess() parse results" do
+          expect(Failure("error", []).success?).to be_false
+          expect(Error("error", []).success?).to be_false
+        end
+      end
+    end
+
+  end
+end

data/spec/drudge/parsers/primitives_spec.rb

@@ -0,0 +1,262 @@
+require 'spec_helper'
+require 'drudge/parsers/primitives'
+
+
+class Drudge
+  module Parsers
+
+    describe Primitives do
+      include Primitives
+
+      describe ".parser: a parser function (lambda) that recognizes the next token on the input that wrapped in a ParseResult" do
+
+        subject(:p) do
+          parser { |input| if input[0][0] == :val then Success(Single(input[0][1]), input.drop(1)) else Failure("f", input) end } 
+        end
+
+        it "accepts an enum of sexps (obtained from tokenize) as its single argument" do
+          expect { p[[[:val, "test"]]] }.not_to raise_error
+        end
+
+        context "given the input [[:val, 'test']]" do
+          it "parses the value and consumes the input that produced it" do 
+            expect(p[[[:val, "test"]]]).to eq(Success(Single("test"), []))
+          end
+        end
+
+        context "given the input [[:val, 'test'], [:foo, 'bar']]" do
+          it "parses the value and return the remaining input" do
+            expect(p[[[:val, "test"], [:foo, "bar"]]]).to eq(Success(Single("test"), [[:foo, "bar"]]))
+          end
+        end
+
+        context "given the input [[:foo, 'bar'], [:val, 'test']]" do
+          it "doesn't parse the input and returns Failure" do
+            input = [[:foo, 'bar'], [:val, 'test']]
+            expect(p[input]).to eq(Failure("f", input))
+          end
+        end
+      end
+
+      # a parser that expects a value declared in +expected 
+      def value(expected)
+        parser do |input|
+          first, *rest = input
+
+          case 
+          when first.nil? 
+            Failure("Expected a value", input)
+          when first[0] == :val && expected === first[1]
+            Success(Single(first[1]), rest)
+          else
+            Failure("'#{first[1]}' doesn't match #{expected}", input)
+          end
+        end.describe expected
+      end
+
+      describe ".commit" do
+        let(:prs) do
+          p = parser do |input|
+            Failure("fail", input)
+          end
+
+          commit(p)
+        end
+
+        it "converts parser Failures into Errors" do
+          input = [[:val, "Hello"]]
+          result = prs[input]
+
+          expect(result).to be_kind_of(Error)
+          expect(result.message).to eq("fail")
+        end
+      end
+
+      describe "parser combinators" do
+
+        describe ".mapv" do
+          context "applied on a value('something') parser" do
+            subject { value('something').mapv { |r| { args: [r] } } }
+
+            it { should parse([[:val, "something"]]).as({ args: ['something']}) } 
+            it { should_not parse([[:val, "something else"]]) }
+          end
+        end
+
+        describe ".>" do
+          context "value('something') > value(/-t.+/)" do
+            subject { value('something') > value(/-t.+/) }
+
+            it { should parse([[:val, 'something'], [:val, '-tower']]).as(['something', '-tower']) }
+            it { should parse([[:val, 'something'], [:val, '-tower']]) }
+            it { should_not parse([[:val, 'something']])}
+          end
+
+          context "value('something') > value('followed by') > value('else')" do
+            subject { value('something') > value('followed by') > value('else') }
+
+            it { should parse([[:val, 'something'], [:val, 'followed by'], [:val, 'else']]).as(['something', 'followed by', 'else']) }
+            it { should_not parse([[:val, 'something']]) }
+            it { should_not parse([:val, 'something'], [:val, 'other'], [:val, 'else']) }
+          end
+        end
+
+        describe ".>=" do
+          context "value('something') >= value('else')" do
+            subject { value('something') >= value('else') }
+
+            it { should tokenize_and_parse(%w[something else]).as('else') }
+            
+            it { should_not tokenize_and_parse(%w[something other]) }
+            it { should_not tokenize_and_parse(%w[other else]) }
+            it { should_not tokenize_and_parse([]) }
+          end
+        end
+
+
+        describe ".<=" do
+          context "value('something') <= value('else')" do
+            subject { value('something') <= value('else') }
+
+            it { should tokenize_and_parse(%w[something else]).as('something') }
+
+            it { should_not tokenize_and_parse(%w[something other]) }
+            it { should_not tokenize_and_parse(%w[other else]) }
+            it { should_not tokenize_and_parse([]) }
+          end
+        end
+
+        describe ".|" do
+          context "value('something') | value('else')" do
+            subject { value('something') | value('else') }
+
+            it { should tokenize_and_parse(%w[something]).as('something') }
+            it { should tokenize_and_parse(%w[else]).as('else') }
+            it { should_not tokenize_and_parse(%w[other stuff]) }
+
+            its(:to_s) { should eq("something | else") }
+          end
+        end
+
+        describe ".optonal" do
+          context "value('something').optional"  do
+            subject { value('something').optional }
+
+            it { should tokenize_and_parse(%w[something]).as('something') }
+            it { should tokenize_and_parse(%w[]).as(nil) }
+            it { should tokenize_and_parse(%w[other]).as(nil) }
+          end
+
+          context "value('something').optional > value(/.+/)" do
+            subject { value('something').optional > value(/.+/) }
+
+            it { should tokenize_and_parse(%w[something other]).as(['something', 'other']) }
+            it { should tokenize_and_parse(%w[other]).as('other') }
+
+            it { should_not tokenize_and_parse(%w[something]).as('something') }
+            it { should_not tokenize_and_parse(%w[]) }
+          end
+        end
+
+
+        describe ".repeats" do
+          shared_examples "repetitive parser" do |word|
+            it { should tokenize_and_parse([word]).as(word) }
+            it { should tokenize_and_parse([word, word]).as([word, word]) } 
+            it { should tokenize_and_parse([word, word, word]).as([word, word, word]) }
+            it { should tokenize_and_parse([word, word, "not-#{word}"]).as([word, word]) }
+          end
+
+          context "zero or more repetitions" do
+            shared_examples "parser for zero or more repetitions" do |word|
+              it { should tokenize_and_parse(["not-#{word}"]).as(nil) }
+              it { should tokenize_and_parse([]).as(nil) }
+            end
+
+            describe "no arguments means repeats(:*)" do
+              subject { value('hi').repeats }
+              it_behaves_like "repetitive parser", 'hi'
+              it_behaves_like  "parser for zero or more repetitions" , 'hi'
+            end
+
+            describe "repeats(:*)" do
+              subject { value('hi').repeats(:*) }
+
+              it_behaves_like "repetitive parser", 'hi'
+              it_behaves_like  "parser for zero or more repetitions" , 'hi'
+            end
+          end
+
+          context "one or more repetitions" do
+            describe "repeats(:+)" do
+              subject { value('hi').repeats(:+) }
+
+              it_behaves_like "repetitive parser", 'hi'
+
+              it { should_not tokenize_and_parse(["not-hi"]) }
+              it { should_not tokenize_and_parse([]) }
+            end
+          end
+
+          context "with till:" do 
+            shared_examples "terminated repeating parser" do |word, terminal|
+              it { should tokenize_and_parse([word, terminal]).as(word) }
+              it { should tokenize_and_parse([word, word, terminal]).as([word, word]) }
+              it { should tokenize_and_parse([word, word, terminal, word]).as([word, word]) }
+
+            end
+
+
+            describe "value('hi').repeats(till: value('no'))" do
+              subject { value('hi').repeats(till: value('no')) }
+
+              it_behaves_like "terminated repeating parser", "hi", "no"
+
+              it { should tokenize_and_parse(%w[no]).as(nil) }
+            end
+
+            describe "value('hi').repeats(:+, till: value('no')" do
+              subject { value('hi').repeats(:+, till: value('no')) }
+
+              it_behaves_like "terminated repeating parser", "hi", "no"
+
+              it { should_not tokenize_and_parse(%w[no]) }
+
+              it { should_not tokenize_and_parse(%w[hi hi]) }
+              it { should_not tokenize_and_parse([]) }
+
+            end
+
+            describe "terminated repeating parser is non-greedy" do
+              shared_examples "non-greedy terminated repeating parser" do |word, terminal_sequence|
+                it { should tokenize_and_parse([word, *terminal_sequence]).as(word) }
+                it { should tokenize_and_parse([word, *terminal_sequence, *terminal_sequence]).as(word) }
+              end
+
+              describe "value('hi').repeats(till: value('hi') > value('no'))" do
+                subject { value('hi').repeats(till: (value('hi') > value('no'))) }
+
+                it_behaves_like "non-greedy terminated repeating parser", 'hi', ['hi', 'no']
+
+                it { should tokenize_and_parse(%w[hi hi]).as(nil) }
+                it { should tokenize_and_parse(%w[hi]).as(nil) }
+              end
+
+              describe "value('hi').repeats(:+, till: value('hi') > value('no'))" do
+                subject { value('hi').repeats(:+, till: (value('hi') > value('no'))) }
+
+                it_behaves_like "non-greedy terminated repeating parser", 'hi', ['hi', 'no']
+
+                it { should_not tokenize_and_parse(%w[hi hi]) }
+                it { should_not tokenize_and_parse(%w[hi]) }
+              end
+
+
+            end
+          end
+        end
+
+      end        
+    end
+  end
+end