stupidedi 1.1.0

data/lib/stupidedi/reader/input/abstract_input.rb

@@ -0,0 +1,133 @@
+module Stupidedi
+  module Reader
+
+    #
+    # Provides an abstract interface for a positioned cursor within an
+    # element-based input stream. The main operations are implemented by the
+    # {#take} and {#drop} methods.
+    #
+    # The {DelegatedInput} subclass wraps values that already implement the
+    # interface, like {String} and {Array}. The {FileInput} subclass wraps
+    # opened `IO` streams like `File`, and possibly others.
+    #
+    # @example Reading the input
+    #   input = Input.build("abc")
+    #   input.at(0)           #=> "a"
+    #   input.take(3)         #=> "abc"
+    #
+    #   input = input.drop(1) #=> #<DelegatedInput ...>
+    #   input.at(0)           #=> "b"
+    #   input.take(3)         #=> "bc"
+    #
+    #   input = input.drop(1) #=> #<DelegatedInput ...>
+    #   input.at(0)           #=> "c"
+    #   input.take(3)         #=> "c"
+    #
+    # @example Querying the position
+    #   input = Input.build("abc\ndef\nghi")
+    #   input.offset  #=> 0
+    #   input.line    #=> 1
+    #   input.column  #=> 1
+    #
+    #   input.drop(3).bind do |in|
+    #     in.offset   #=> 3
+    #     in.line     #=> 1
+    #     in.column   #=> 4
+    #   end
+    #
+    #   input.drop(4).bind do |in|
+    #     in.offset   #=> 4
+    #     in.line     #=> 2
+    #     in.column   #=> 1
+    #   end
+    #
+    # @note The monkey-patched classes {String} and {Array} provide compatible
+    #   implementations of the abstract methods, so code written to target
+    #   this interface is backward-compatable with plain unwrapped {String}
+    #   and {Array} values.
+    #
+    class AbstractInput
+      include Inspect
+
+      # @group Querying the Position
+      ########################################################################
+
+      # The {Position} value that describes the position of the input stream
+      #
+      # @return [Position]
+      abstract :position
+
+      # The current position as the number of elements previously read
+      #
+      # @return [Integer]
+      delegate :offset, :to => :position
+
+      # The line of the current position
+      #
+      # @return [Integer]
+      delegate :line, :to => :position
+
+      # The column of the current position. The column resets to `1` each time
+      # a newline is read
+      #
+      # @return [Integer]
+      delegate :column, :to => :position
+
+      # The file name, URI, etc that identifies the input stream
+      #
+      # @return [String]
+      delegate :path, :to => :position
+
+      # @group Reading the Input
+      ########################################################################
+
+      # Read the first `n` elements
+      #
+      # @param [Integer] n number of elements to read (`n >= 0`)
+      abstract :take, :args => %w(n)
+
+      # Read a single element at the given index. Result is undefined unless
+      # the input contains enough elements, which can be tested with
+      # {#defined_at?}
+      #
+      # @param [Integer] n the index of the element to read (`n >= 0`)
+      abstract :at, :args => %w(n)
+
+      # Returns the smallest `n`, where {#at}`(n)` == `element`
+      #
+      # @param [Object] element the element to find in the input
+      #
+      # @return [Integer]
+      # @return nil if `element` is not present in the input
+      abstract :index, :args => %w(value)
+
+      # @group Advancing the Cursor
+      ########################################################################
+
+      # Advance the cursor forward `n` elements
+      #
+      # @param [Integer] n the number of elements to advance (`n >= 0`)
+      #
+      # @return [AbstractInput] new object with the remaining input
+      abstract :drop, :args => %w(n)
+
+      # @group Testing the Input
+      ########################################################################
+
+      # True if the input contains enough elements such that {#at}`(n)` is
+      # defined
+      #
+      # @param [Integer] n the index to test (`n >= 0`)
+      abstract :defined_at?, :args => %w(n)
+
+      # True if no elements remain in the input
+      abstract :empty?
+
+      # True if `other` equals the remaining input
+      #
+      # @return [Boolean]
+      abstract :==, :args => %w(other)
+    end
+
+  end
+end

data/lib/stupidedi/reader/input/delegated_input.rb

@@ -0,0 +1,111 @@
+module Stupidedi
+  module Reader
+
+    class DelegatedInput < AbstractInput
+
+      def initialize(delegate, offset = 0, line = 1, column = 1)
+        @delegate, @offset, @line, @column =
+          delegate, offset, line, column
+      end
+
+      # @group Querying the Position
+      ########################################################################
+
+      # (see AbstractInput#offset)
+      attr_reader :offset
+
+      # (see AbstractInput#line)
+      attr_reader :line
+
+      # (see AbstractInput#column)
+      attr_reader :column
+
+      # (see AbstractInput#position)
+      def position
+        Position.new(@offset, @line, @column, nil)
+      end
+
+      # @group Reading the Input
+      ########################################################################
+
+      # (see AbstractInput#take)
+      delegate :take, :to => :@delegate
+
+      # (see AbstractInput#at)
+      delegate :at, :to => :@delegate
+
+      # (see AbstractInput#index)
+      delegate :index, :to => :@delegate
+
+      # @group Advancing the Cursor
+      ########################################################################
+
+      # (see AbstractInput#drop)
+      def drop(n)
+        raise ArgumentError, "n must be positive" unless n >= 0
+
+        suffix = @delegate.drop(n)
+        prefix = @delegate.take(n)
+
+        length = prefix.length
+        count  = prefix.count("\n")
+
+        column = unless count.zero?
+                   length - prefix.rindex("\n")
+                 else
+                   @column + length
+                 end
+
+        copy(:delegate => suffix,
+             :offset   => @offset + length,
+             :line     => @line + count,
+             :column   => column)
+      end
+
+      # @group Testing the Input
+      ########################################################################
+
+      # (see AbstractInput#defined_at?)
+      delegate :defined_at?, :to => :@delegate
+
+      # (see AbstractInput#empty?)
+      delegate :empty?, :to => :@delegate
+
+      # (see AbstractInput#==)
+      delegate :==, :to => :@delegate
+
+      # @endgroup
+      ########################################################################
+
+      # @return [void]
+      def pretty_print(q)
+        q.text("DelegateInput")
+        q.group(2, "(", ")") do
+          preview = @delegate.take(4)
+          preview = if preview.empty?
+                      "EOF"
+                    elsif preview.length <= 3
+                      preview.inspect
+                    else
+                      (preview.take(3) << "...").inspect
+                    end
+
+          q.text preview
+          q.text " at line #{@line}, column #{@column}, offset #{@offset}"
+        end
+      end
+
+    private
+
+      # @return [DelegatedInput]
+      def copy(changes = {})
+        DelegatedInput.new \
+          changes.fetch(:delegate, @delegate),
+          changes.fetch(:offset, @offset),
+          changes.fetch(:line, @line),
+          changes.fetch(:column, @column)
+      end
+    end
+
+  end
+end

data/lib/stupidedi/reader/input/file_input.rb

@@ -0,0 +1,155 @@
+module Stupidedi
+  module Reader
+
+    #
+    # @note This class is not thread-safe. If more than one `Thread` has access
+    #   to the same instance, and they simultaneously call methods on that
+    #   instance, the methods may produce incorrect results and the object might
+    #   be left in an inconsistent state.
+    #
+    class FileInput < AbstractInput
+
+      # @return [IO]
+      attr_reader :io
+
+      def initialize(io, offset = 0, line = 1, column = 1, size = io.stat.size)
+        @io, @offset, @line, @column, @size =
+          io, offset, line, column, size
+      end
+
+      # @group Querying the Position
+      ########################################################################
+
+      # (see AbstractInput#offset)
+      attr_reader :offset
+
+      # @return [Integer]
+      # (see AbstractInput#line)
+      attr_reader :line
+
+      # (see AbstractInput#column)
+      attr_reader :column
+
+      # (see AbstractInput#path)
+      attr_reader :path
+
+      # (see AbstractInput#position)
+      def position
+        Position.new(@offset, @line, @column, @io.path)
+      end
+
+      # @group Reading the Input
+      ########################################################################
+
+      # (see AbstractInput#take)
+      # @return [String]
+      def take(n)
+        @io.seek(@offset)
+
+        # Calling @io.read with more than the number of available bytes will
+        # return nil, so we have to calculate how many bytes remain
+        @io.read((n <= @size) ? n : @size)
+      end
+
+      # (see AbstractInput#at)
+      # @return [String]
+      def at(n)
+        raise ArgumentError, "n must be positive" unless n >= 0
+
+        @io.seek(@offset + n)
+        @io.read(1)
+      end
+
+      # (see AbstractInput#index)
+      def index(value)
+        @io.seek(@offset)
+        length = value.length
+
+        # We need to start with value != buffer, and this is a reasonable guess
+        buffer = "\377" * length
+
+        until @io.eof?
+          buffer.slice!(0)
+          buffer << @io.read(1)
+
+          if buffer == value
+            return @io.tell - @offset - length
+          end
+        end
+      end
+
+      # @group Advancing the Cursor
+      ########################################################################
+
+      # (see AbstractInput#drop)
+      def drop(n)
+        raise ArgumentError, "n must be positive" unless n >= 0
+
+        @io.seek(@offset)
+        prefix = @io.read(n)
+        suffix = @io
+
+        length = prefix.length
+        count  = prefix.count("\n")
+
+        column = unless count.zero?
+                   length - prefix.rindex("\n")
+                 else
+                   @column + length
+                 end
+
+        copy(:offset => @offset + length,
+             :line   => @line + count,
+             :column => column,
+             :size   => @size - length)
+      end
+
+      # @group Testing the Input
+      ########################################################################
+
+      # (see AbstractInput#defined_at?)
+      def defined_at?(n)
+        n < @size
+      end
+
+      # (see AbstractInput#empty?)
+      def empty?
+        @io.eof?
+      end
+
+      # @endgroup
+      ########################################################################
+
+      # @return [void]
+      def pretty_print(q)
+        q.text("FileInput")
+        q.group(2, "(", ")") do
+          preview = take(4)
+          preview = if preview.empty?
+                      "EOF"
+                    elsif preview.length <= 3
+                      preview.inspect
+                    else
+                      (preview.take(3) << "...").inspect
+                    end
+
+          q.text preview
+          q.text " at line #{@line}, column #{@column}, offset #{@offset}, file #{File.basename(@io.path)}"
+        end
+      end
+
+    private
+
+      # @return [FileInput]
+      def copy(changes = {})
+        FileInput.new \
+          changes.fetch(:io, @io),
+          changes.fetch(:offset, @offset),
+          changes.fetch(:line, @line),
+          changes.fetch(:column, @column),
+          changes.fetch(:size, @size)
+      end
+    end
+
+  end
+end

data/lib/stupidedi/reader/input.rb

@@ -0,0 +1,30 @@
+module Stupidedi
+  module Reader
+
+    module Input
+    end
+
+    class << Input
+      # @group Constructors
+      #########################################################################
+
+      # @return [Input]
+      def build(o, *args)
+        case o
+        when AbstractInput
+          o
+        when IO
+          FileInput.new(o, *args)
+        when String, Array
+          DelegatedInput.new(o, *args)
+        else
+          raise TypeError
+        end
+      end
+
+      # @endgroup
+      #########################################################################
+    end
+
+  end
+end

data/lib/stupidedi/reader/position.rb

@@ -0,0 +1,69 @@
+module Stupidedi
+  module Reader
+
+    class Position
+      include Inspect
+
+      # @return [Integer]
+      attr_reader :offset
+
+      # @return [Integer]
+      attr_reader :line
+
+      # @return [Integer]
+      attr_reader :column
+
+      # @return [String, Pathname]
+      attr_reader :path
+
+      def initialize(offset, line, column, path)
+        @offset, @line, @column, @path =
+          offset, line, column, path
+      end
+
+      def copy(changes = {})
+        Position.new \
+          changes.fetch(:offset, @offset),
+          changes.fetch(:line, @line),
+          changes.fetch(:column, @column),
+          changes.fetch(:path, @path)
+      end
+
+      # @return [String]
+      def inspect
+        if @path.present?
+          "file #{@path}, line #{@line}, column #{@column}"
+        else
+          "line #{@line}, column #{@column}"
+        end
+      end
+
+      # @return [void]
+      def pretty_print(q)
+        q.text "Position"
+        q.group(2, "(", ")") do
+          q.breakable ""
+          q.text "line #{@line},"
+          q.breakable
+          q.text "column #{@column},"
+          q.breakable
+          q.text "offset #{@offset}"
+
+          unless @path.nil?
+            q.text ","
+            q.breakable
+            q.text "path #{@path}"
+          end
+        end
+      end
+    end
+
+    class << Position
+      def caller(offset = 1)
+        path, line, method = Stupidedi.caller(offset + 1)
+        new(nil, line, nil, path)
+      end
+    end
+
+  end
+end

data/lib/stupidedi/reader/result.rb

@@ -0,0 +1,168 @@
+module Stupidedi
+  module Reader
+
+    module Result
+
+      # @return [Position]
+      def position
+        if @remainder.respond_to?(:position)
+          @remainder.position
+        end
+      end
+
+      # @return [Integer]
+      def offset
+        if @remainder.respond_to?(:offset)
+          @remainder.offset
+        end
+      end
+
+      # @return [Integer]
+      def line
+        if @remainder.respond_to?(:line)
+          @remainder.line
+        end
+      end
+
+      # @return [Integer]
+      def column
+        if @remainder.respond_to?(:column)
+          @remainder.column
+        end
+      end
+    end
+
+    class << Result
+      # @group Constructors
+      #########################################################################
+
+      # @return [Result::Success]
+      def success(value, remainder)
+        Success.new(value, remainder)
+      end
+
+      # @return [Result::Failure]
+      def failure(reason, remainder, fatal)
+        Failure.new(reason, remainder, fatal)
+      end
+
+      # @endgroup
+      #########################################################################
+    end
+
+    class Success < Either::Success
+      include Result
+
+      attr_reader :remainder
+
+      def initialize(value, remainder)
+        @value, @remainder = value, remainder
+      end
+
+      # @return [Success]
+      def copy(changes = {})
+        Success.new \
+          changes.fetch(:value, @value),
+          changes.fetch(:remainder, @remainder)
+      end
+
+      def fatal?
+        false
+      end
+
+      # @return [Boolean]
+      def ==(other)
+        if other.is_a?(self.class)
+          @value == other.value and @remainder == other.remainder
+        else
+          @value == other
+        end
+      end
+
+      # @return [void]
+      def pretty_print(q)
+        q.text "Result.success"
+        q.group(2, "(", ")") do
+          q.breakable ""
+          q.pp @value
+          q.text ","
+          q.breakable
+          q.pp @remainder
+        end
+      end
+
+      # Override {Enumerable#blank?} since we're not really {Enumerable}
+      def blank?
+        false
+      end
+
+    private
+
+      def deconstruct(block)
+        block.call(@value, @remainder)
+      end
+
+      def failure(reason)
+        Failure.new(reason, @remainder, false)
+      end
+    end
+
+    class Failure < Either::Failure
+      include Result
+
+      attr_reader :remainder
+
+      def initialize(reason, remainder, fatal)
+        @reason, @remainder, @fatal =
+          reason, remainder, fatal
+      end
+
+      # @return [Failure]
+      def copy(changes = {})
+        Failure.new \
+          changes.fetch(:reason, @reason),
+          changes.fetch(:remainder, @remainder),
+          changes.fetch(:fatal, @fatal)
+      end
+
+      def fatal?
+        @fatal
+      end
+
+      def fatal
+        copy(:fatal => true)
+      end
+
+      # @return [Boolean]
+      def ==(other)
+        if other.is_a?(self.class)
+          @reason == other.reason
+        else
+          @reason == other
+        end
+      end
+
+      # @return [void]
+      def pretty_print(q)
+        q.text "Result.failure"
+        q.group(2, "(", ")") do
+          q.breakable ""
+          q.pp @reason
+          q.text ","
+          q.breakable
+          q.pp @remainder
+          q.text ","
+          q.breakable
+          q.text "#{@fatal ? "" : "non-"}fatal"
+        end
+      end
+
+    private
+
+      def deconstruct(block)
+        block.call(@reason, @remainder)
+      end
+    end
+
+  end
+end