drudge 0.4.0

data/lib/drudge/kit.rb

@@ -0,0 +1,45 @@
+require 'drudge/errors'
+require 'drudge/parsers'
+require 'drudge/command'
+
+class Drudge
+
+  # A kit is a set of commands that can be dispatched to
+  class Kit
+    include Parsers
+
+    # the name of the kit
+    attr_accessor :name
+
+    # the list of commands the kit hsa
+    attr_accessor :commands
+
+
+    def initialize(name, commands = [])
+      @name, @commands = name.to_sym, commands
+    end
+
+    # Dispatches a command within the kit
+    # The first argument is the command name
+    def dispatch(command_name, *args)
+      command = find_command(command_name) rescue nil
+
+      raise UnknownCommandError.new(name), "A command is required" unless command
+
+      command.dispatch *args
+      
+    end
+
+    # returns the argument parser for this kit
+    def argument_parser
+      commands.map { |c| (command(name) > command(c.name) > commit(c.argument_parser)).collated_arguments }
+              .reduce { |p1, p2| p1 | p2 }
+    end
+
+    private
+
+    def find_command(command_name)
+      commands.find { |c| c.name == command_name.to_sym }
+    end
+  end
+end

data/lib/drudge/parsers.rb

@@ -0,0 +1,91 @@
+require 'drudge/errors'
+require 'drudge/parsers/tokenizer'
+require 'drudge/parsers/primitives'
+
+class Drudge
+
+  module Parsers
+    include Primitives
+
+    # returns a parser that matches a :val on the input
+    # +expected+ is compared to the input using === (i.e. you can use it as a matcher for
+    # all sorts of things)
+    def value(expected = /.*/, 
+              eos_failure_msg: "expected a value", 
+              failure_msg:     -> ((_, value)) { "'#{value}' doesn't match #{expected}" })
+
+      accept(-> ((kind, value)) { kind == :val && expected === value },
+               eos_failure_msg: eos_failure_msg,
+               failure_msg: failure_msg )
+        .mapv { |_, value| value }
+        .describe expected.to_s
+
+    end
+
+    # matches the end of the stream
+    def eos(message = "Expected end-of-command")
+      super
+    end
+
+    # parses a single argument with the provided name
+    def arg(name, expected = value(/.*/))
+      expected.mapv                 { |a| [:arg, a] }
+              .with_failure_message { |msg| "#{msg} for <#{name}>" }
+              .describe "<#{name}>"
+    end
+
+    # parses a command
+    def command(name)
+      value(name.to_s, eos_failure_msg: "expected a command",
+                       failure_msg: -> ((_, val)) { "unknown command '#{val}'" })
+        .mapv { |v| [:arg, v] }
+        .describe(name.to_s)
+    end
+
+    def parser_mixin
+      ArgumentParser
+    end
+
+    module ArgumentParser
+      include Primitives::Parser
+      include Tokenizer
+      include Parsers
+
+      # tokenizes and parses an array of arguments
+      def parse(argv)
+        self[tokenize(argv)]
+      end
+
+      # tokenizes and parses an array of arguments, returning the 
+      # parsed result. Raises an error if the parse fails
+      def parse!(argv)
+        input = tokenize(argv)
+        res   = self[input]
+
+        if res.success?
+          res.result
+        else
+          raise ParseError.new(input, res.remaining), res.message
+        end
+      end
+
+      # a parser that collates the results of argument parsing
+      def collated_arguments
+        self.mapr do |results|
+          args = results.to_a.reduce({args: []}) do |a, (kind, value, *rest)|
+            case kind
+            when :arg
+              a[:args] << value
+            end
+
+            a
+          end
+
+          Single(args)
+        end
+      end        
+
+    end
+
+  end
+end

data/lib/drudge/parsers/parse_results.rb

@@ -0,0 +1,254 @@
+class Drudge
+  module Parsers
+
+    # Classes representing parse results
+    module ParseResults
+
+      module FactoryMethods
+        # helper methods for constructing 
+
+        def Success(value, remaining)
+          Success.new(value, remaining) 
+        end
+
+        def Failure(message, remaining)
+          Failure.new(message, remaining)
+        end
+
+        def Error(message, remaining)
+          Error.new(message, remaining)
+        end
+
+        def Empty()
+          Empty.new
+        end
+
+        def Single(value)
+          Single.new(value)
+        end
+
+        def Seq(arr)
+          Seq.new(arr)
+        end
+      end
+
+      include FactoryMethods
+
+      # Identifies a parse result. It can be a Success or NotSuccess
+      module ParseResult
+        # applies the provided block to the containing ParseValue
+        # returns a new ParseResult containing the modified value
+        def map ; end
+
+        # applies the provied block to the contained parse value
+        def map_in_parse_value; end
+
+        # monadic bind (or flat_map) of two sequential results
+        def flat_map; end 
+
+        def flat_map_with_next(&parser_producer); end
+
+        # Combines this result with the other by applying the '+' operator
+        # on the underlying ParseValue
+        # takes care of failure / success combinatorics  are observed
+        def +(other)
+          self.flat_map do |res|
+            other.map do |other_res|
+              res + other_res
+            end
+          end
+        end
+
+        # returns true if the ParseResult was successful 
+        def success?; end
+      end
+
+      # A successful parse result. Contains a ParseValue as 
+      # the parse_result attr.
+      Success = Struct.new(:parse_result, :remaining) do
+        include ParseResult
+
+        def map
+          self.class.new(yield(parse_result), remaining)
+        end
+
+        def map_in_parse_value(&f)
+          self.class.new(parse_result.map(&f), remaining)
+        end
+
+        def flat_map
+          yield parse_result
+        end
+
+        def flat_map_with_next(&next_parser_producer)
+          next_parser_producer[self][remaining]
+        end
+
+        def success?
+          true
+        end
+
+        def empty?
+          Empty === parse_result
+        end
+
+        # fully unwraps the parse result
+        def result
+          if empty?
+            nil
+          else
+            parse_result.value
+          end
+        end
+
+      end
+
+      # an unsuccesful parse result
+      module NotSuccess
+        include ParseResult
+
+        def map
+          self
+        end
+
+        def map_in_parse_value
+          self
+        end
+
+        # propagate error
+        def flat_map
+          self
+        end
+
+        def flat_map_with_next(&_)
+          self
+        end
+
+        def success?
+          false
+        end
+
+      end
+
+      # A failure that allows for backtracking
+      Failure = Struct.new(:message, :remaining) do
+        include NotSuccess
+      end
+
+      # An error doesn't allow backtracking
+      Error = Struct.new(:message, :remaining) do
+        include NotSuccess
+      end
+
+
+      # A parse value is a wrapper around the values 
+      # produced by parsers  that allow for 
+      # concatanations (monoidal)
+      module ParseValue
+        include FactoryMethods
+
+        # returns the 'zero' of the parse, value
+        def self.zero
+          Empty()
+        end
+
+        # Concatenation of parse values
+        def +(other); end 
+
+        # converts the value into an array
+        def to_a; end
+      end 
+
+
+      class Empty
+        include ParseValue
+
+        def map
+          self
+        end
+
+        def flat_map
+          self
+        end
+
+        def +(other)
+          other
+        end
+
+        def to_a
+          []
+        end
+
+        def ==(other)
+          Empty === other
+        end
+
+        alias :eql? :==
+      end
+
+      Single = Struct.new(:value) do
+        include ParseValue
+
+        def map
+          self.class.new(yield value)
+        end
+
+        def flat_map
+          yield value
+        end
+
+        def +(other)
+          case other
+
+          when Empty
+            self
+
+          when Single 
+            Seq([self.value, other.value])
+
+          when Seq
+            Seq([self.value] + other.value)
+          end
+        end
+
+        def to_a
+          [value]
+        end
+
+      end
+
+      # A sequence of succesful results 
+      Seq = Struct.new(:value) do
+        include ParseValue
+
+        def map
+          self.class.new(yield value)
+        end
+
+        def flat_map
+          yield value
+        end
+
+        def +(other)
+          case other
+
+          when Empty
+            self 
+
+          when Single
+            Seq(self.value + [other.value])
+
+          when Seq
+            Seq(self.value + other.value)
+          end
+        end
+
+        def to_a
+          value
+        end
+      end
+
+    end
+
+  end
+end

data/lib/drudge/parsers/primitives.rb

@@ -0,0 +1,278 @@
+require 'drudge/parsers/parse_results'
+
+class Drudge
+  module Parsers
+
+    # Parser primitives
+    module Primitives
+      include ParseResults
+
+      # a method that helps bulding parsers
+      # converts a block into a parser
+      def parser(&prs)
+        prs.singleton_class.send :include, parser_mixin
+        prs
+      end
+
+      # produces a parser that expects the +expected+ value
+      # +expected+ can is checked using '===' so 
+      #  accept(String) -> will accept any string
+      #  accept(2) -> will accept 2
+      #  accept(-> v { v / 2 == 4 }) will use the lambda to check the value
+      #  accept { |v| v / 2 == 4 } is also possible
+      def accept(expected = nil, 
+                 eos_failure_msg: "expected a #{expected}", 
+                 failure_msg: -> value { "'#{value}' doesn't match #{expected}" },
+                  &expected_block)
+
+        expected = expected_block if expected_block
+
+        to_message = -> (value, msg) do 
+          case msg
+          when String
+            msg
+          when Proc
+            msg[value]
+          end
+        end
+
+        parser do |input|
+          value, *rest = input
+
+          case 
+          when input.nil? || input.empty?
+            Failure(to_message[value, eos_failure_msg], input)
+          when expected === value
+            Success(Single(value), rest)
+          else
+            Failure(to_message[value, failure_msg], input)
+          end
+        end
+      end
+
+      # returns a parser that always succeeds with the provided ParseValue
+      def success(parse_value)
+        parser { |input| Success(parse_value, input) }.describe "SUCC: #{parse_value}"
+      end
+
+     # matches the end of the stream
+     def eos(message)
+      parser do |input|
+        if input.empty?
+          Success(Empty(), [])
+        else
+          Failure(message, input)
+        end
+      end.describe ""
+    end        
+
+      # Commits the provided parser. If +prs+ returns
+      # a +Failure+, it will be converted into an +Error+ that 
+      # will stop backtracking inside a '|' operator
+      def commit(prs)
+        parser do |input|
+          result = prs[input]
+
+          case result
+          when Success, Error
+            result
+          when Failure
+            Error(result.message, result.remaining)
+          end
+        end.describe(prs.to_s)
+      end
+
+      # Returns the module which is to be mixed in in every
+      # constructed parser. Can be overriden to mix in 
+      # additonal features
+      def parser_mixin
+        Parser
+      end
+      protected :parser_mixin
+
+      # This modules contains the parser combinators
+      module Parser
+        include ParseResults
+        include Primitives
+
+        # Returns a new parser that applies the parser function to the 
+        # parse result of self
+        def map(&f)
+          parser { |input| f[self[input]] }.describe(self.to_s)
+        end
+
+        # like map but yields the actual value of the parse result 
+        # (ParseResult contains ParseValue which contains the actual value)
+        # wrapped value. Usefull if you want to know if the result was 
+        # a sequence or not
+        def map_in_parse_value(&f)
+          parser { |input| self[input].map { |pr| pr.map &f } }.describe(self.to_s)
+        end
+
+        alias_method :mapv, :map_in_parse_value
+
+        # likemap but yields the the contents of the ParseResult instead of the vrapped value
+        def map_in_parse_result(&f)
+          parser { |input| self[input].map &f }.describe(self.to_s)
+        end
+
+        alias_method :mapr, :map_in_parse_result
+
+        # monadic bind (or flat map) for a parser
+        # f should take the result of the current parser and return a the parser that will consume
+        # the next input. Used for sequencing
+        def flat_map(&f)
+          parser do |input|
+            self[input].flat_map_with_next &f
+          end
+        end
+
+        # Returns a parser that, if self is successful will dicard its result
+        # Used in combination with sequencing to achieve lookahead / lookbehind
+        def discard
+          parser do |input|
+            result = self[input]
+
+            if Success === result
+              Success(Empty(), result.remaining)
+            else
+              result
+            end
+          end.describe(self.to_s)
+        end
+
+        # sequening: returns a parser that succeeds if self succeeds,
+        # follwing by the otheer parser on the remaining input
+        # returns a Tuple of both results
+        def >(other)
+          self.flat_map do |result1|
+            other.map do |result2|
+              result1 + result2
+            end
+          end.describe("#{self.to_s} #{other.to_s}")
+        end
+
+        # sequencing: same as '>' but returns only the result of the +other+ 
+        # parser, discarding the result of the first 
+        def >=(other)
+          (self.discard > other)
+        end
+
+        # sequencing: same as '>' but returns only the result of +self+, disregarding
+        # the result of the +other+ 
+        def <=(other)
+          (self > other.discard)
+        end
+
+        # alternation: try this parser and if it fails (but not with an Error)
+        # try the +other+ parser 
+        def |(other)
+          parser do |input|
+            result1 = self[input]
+
+            case result1
+            when Success
+              result1
+            when Failure
+              result2 = other[input]
+
+              # return the failure that happened earlier in the stream
+              if Failure == result2 && result1.remaining.count > result2.remaining.count
+                result1
+              else
+                result2
+              end
+            when Error
+              result1
+            end
+          end.describe("#{self.to_s} | #{other.to_s}")
+        end
+
+        # makes this parser opitonal
+        def optional
+          self.map do |parse_result|
+            case parse_result
+            when Success
+              parse_result
+            else
+              Success(Empty(), parse_result.remaining)
+            end
+          end.describe("[#{self.to_s}]")
+        end
+
+        # creates a parser that will reject a whatever this parser succeeds in parsing
+        # if this parser fails, the 'rejected' version will succeed with Empty() nad 
+        # will not consume any input
+        def reject
+          parser do |input|
+            result = self[input]
+
+            if result.success?
+              Failure("Unexpected #{self.to_s}", result.remaining)
+            else
+              Success(Empty(), input)
+            end
+          end.describe("!#{self.to_s}")
+        end
+
+        # returns a parser that repeatedly parses 
+        # with +self+ until it fails
+        def repeats(kind = :*, till: self.reject | eos("eos"))
+
+          case kind
+          when :* then (rep1(till: till) | success(Empty())).describe("[#{self} ...]")
+          when :+ then rep1(till: till).describe( "#{self} [#{self} ...]")
+          else raise "Unknown repetition kind for #{self}"
+          end
+        end
+
+
+        def rep1(till: self.reject)
+          parser do |input|
+            results = self[input]
+            remaining = results.remaining
+
+            if results.success?
+              while results.success? && !till[remaining].success?
+                results += self[remaining]
+                remaining = results.remaining
+              end
+            end
+
+            till_result = till[remaining]
+            if till_result.success?
+              results
+            else
+              till_result
+            end
+          end
+        end
+
+        private :rep1
+
+        # attach a description to the parser
+        def describe(str)
+          self.define_singleton_method(:to_s) do
+            str
+          end
+
+          self
+        end
+
+        # converts the failure message 
+        def with_failure_message(&failure_converter) 
+          parser do |input|
+            result = self[input]
+
+            case result
+            when Success
+              result
+            when Failure
+              Failure(failure_converter[result.message, input], result.remaining)
+            end
+          end.describe self.to_s
+        end
+      end
+    end
+  end
+end