baikal 1.1.0

data/lib/baikal/cursor.rb

@@ -0,0 +1,297 @@
+# $Id$
+
+require_relative '../baikal'
+
+module Baikal
+  #
+  # Represents an offset into a byte pool, permitting traversing the byte
+  # pool in a linear manner.
+  #
+  class Cursor
+    #
+    # The cursor's current offset into the underlying byte pool.
+    #
+    attr_accessor :offset
+
+    #
+    # Creates a cursor of the given +pool+, initialising it to point at
+    # its given +offset+.  If +offset+ is not given, defaults to zero, that
+    # is to say, the byte pool's beginning.
+    #
+    def initialize pool, offset = 0
+      raise 'Type mismatch' unless pool.is_a? Baikal::Pool
+      raise 'Type mismatch' unless offset.is_a? Integer
+      super()
+      @pool = pool
+      @offset = offset
+      return
+    end
+
+    #
+    # Retrieves an unsigned byte from the underlying pool's current
+    # position and advances the cursor by one byte.
+    #
+    # Error if the byte referred to by this cursor lies outside the
+    # boundaries of the underlying pool.
+    #
+    def parse_unsigned_byte
+      value = @pool.get_unsigned_byte(@offset)
+      @offset += 1
+      return value
+    end
+
+    #
+    # Retrieves an unsigned wyde from the underlying pool's current
+    # position using the pool's currently selected byte order and advances
+    # the cursor by two bytes.
+    #
+    # Error if the wyde referred to by this cursor lies outside the
+    # boundaries of the underlying pool, even partially.
+    #
+    def parse_unsigned_wyde
+      value = @pool.get_unsigned_wyde(@offset)
+      @offset += 2
+      return value
+    end
+
+    #
+    # Retrieves an unsigned tetrabyte from the underlying pool's current
+    # position using the pool's currently selected byte order and advances
+    # the cursor by four bytes.
+    #
+    # Error if the tetra referred to by this cursor lies outside the
+    # boundaries of the underlying pool, even partially.
+    #
+    def parse_unsigned_tetra
+      value = @pool.get_unsigned_tetra(@offset)
+      @offset += 4
+      return value
+    end
+
+    #
+    # Retrieves an unsigned octabyte from the underlying pool's current
+    # position using the pool's currently selected byte order and advances
+    # the cursor by eight bytes.
+    #
+    # Error if the octa referred to by this cursor lies outside the
+    # boundaries of the underlying pool, even partially.
+    #
+    def parse_unsigned_octa
+      value = @pool.get_unsigned_octa(@offset)
+      @offset += 8
+      return value
+    end
+
+    #
+    # Retrieves a signed byte from the underlying pool's current position
+    # and advances the cursor by one byte.
+    #
+    # Error if the byte referred to by this cursor lies outside the
+    # boundaries of the underlying pool.
+    #
+    def parse_signed_byte
+      value = @pool.get_signed_byte(@offset)
+      @offset += 1
+      return value
+    end
+
+    #
+    # Retrieves a signed wyde from the underlying pool's current position
+    # using the pool's currently selected byte order and advances the
+    # cursor by two bytes.
+    #
+    # Error if the wyde referred to by this cursor lies outside the
+    # boundaries of the underlying pool, even partially.
+    #
+    def parse_signed_wyde
+      value = @pool.get_signed_wyde(@offset)
+      @offset += 2
+      return value
+    end
+
+    #
+    # Retrieves a signed tetrabyte from the underlying pool's current
+    # position using the pool's currently selected byte order and advances
+    # the cursor by four bytes.
+    #
+    # Error if the tetra referred to by this cursor lies outside the
+    # boundaries of the underlying pool, even partially.
+    #
+    def parse_signed_tetra
+      value = @pool.get_signed_tetra(@offset)
+      @offset += 4
+      return value
+    end
+
+    #
+    # Retrieves a signed octabyte from the underlying pool's current
+    # position using the pool's currently selected byte order and advances
+    # the cursor by eight bytes.
+    #
+    # Error if the octa referred to by this cursor lies outside the
+    # boundaries of the underlying pool, even partially.
+    #
+    def parse_signed_octa
+      value = @pool.get_signed_octa(@offset)
+      @offset += 8
+      return value
+    end
+
+    #
+    # Retrieves an unsigned byte from the underlying pool's current
+    # position.  Does not affect the position.
+    #
+    # Error if the byte referred to by this cursor lies outside the
+    # boundaries of the underlying pool.
+    #
+    def peek_unsigned_byte
+      return @pool.get_unsigned_byte(@offset)
+    end
+
+    #
+    # Retrieves an unsigned wyde from the underlying pool's current
+    # position using the pool's currently selected byte order.  Does not
+    # affect the position.
+    #
+    # Error if the wyde referred to by this cursor lies outside the
+    # boundaries of the underlying pool, even partially.
+    #
+    def peek_unsigned_wyde
+      return @pool.get_unsigned_wyde(@offset)
+    end
+
+    #
+    # Retrieves an unsigned tetrabyte from the underlying pool's current
+    # position using the pool's currently selected byte order.  Does not
+    # affect the position.
+    #
+    # Error if the tetra referred to by this cursor lies outside the
+    # boundaries of the underlying pool, even partially.
+    #
+    def peek_unsigned_tetra
+      return @pool.get_unsigned_tetra(@offset)
+    end
+
+    #
+    # Retrieves an unsigned octabyte from the underlying pool's current
+    # position using the pool's currently selected byte order.  Does not
+    # affect the position.
+    #
+    # Error if the octa referred to by this cursor lies outside the
+    # boundaries of the underlying pool, even partially.
+    #
+    def peek_unsigned_octa
+      return @pool.get_unsigned_octa(@offset)
+    end
+
+    #
+    # Retrieves a signed byte from the underlying pool's current position.
+    # Does not affect the position.
+    #
+    # Error if the byte referred to by this cursor lies outside the
+    # boundaries of the underlying pool.
+    #
+    def peek_signed_byte
+      return @pool.get_signed_byte(@offset)
+    end
+
+    #
+    # Retrieves a signed wyde from the underlying pool's current position
+    # using the pool's currently selected byte order.  Does not affect the
+    # position.
+    #
+    # Error if the wyde referred to by this cursor lies outside the
+    # boundaries of the underlying pool, even partially.
+    #
+    def peek_signed_wyde
+      return @pool.get_signed_wyde(@offset)
+    end
+
+    #
+    # Retrieves a signed tetrabyte from the underlying pool's current
+    # position using the pool's currently selected byte order.  Does not
+    # affect the position.
+    #
+    # Error if the tetra referred to by this cursor lies outside the
+    # boundaries of the underlying pool, even partially.
+    #
+    def peek_signed_tetra
+      return @pool.get_signed_tetra(@offset)
+    end
+
+    #
+    # Retrieves a signed octabyte from the underlying pool's current
+    # position using the pool's currently selected byte order.  Does not
+    # affect the position.
+    #
+    # Error if the octa referred to by this cursor lies outside the
+    # boundaries of the underlying pool, even partially.
+    #
+    def peek_signed_octa
+      return @pool.get_signed_octa(@offset)
+    end
+
+    #
+    # Retrieves an unsigned integer of the given +size+ (which must be +1+,
+    # +2+, +4+ or +8+) from the underlying pool's current position using the
+    # pool's currently selected byte order and advances the cursor by the
+    # integer's size.
+    #
+    # Error if the integer of this size referred to by this cursor lies
+    # outside the boundaries of the underlying pool, even partially.
+    #
+    def parse_unsigned_integer size
+      value = @pool.get_unsigned_integer(size, @offset)
+      @offset += size
+      return value
+    end
+
+    #
+    # Retrieves a specified number of bytes from the underlying pool's
+    # current position and advances the cursor by the same number.
+    #
+    # Error if the blob referred to by this cursor and this byte count lies
+    # outside the boundaries of the underlying pool, even partially.
+    #
+    def parse_blob size
+      raise 'Type mismatch' unless size.is_a? Integer
+      raise 'Invalid blob size' unless size >= 0
+      blob = @pool.get_blob(@offset, size)
+      @offset += size
+      return blob
+    end
+
+    #
+    # Moves the cursor forwards by +delta+ bytes, passing a part of the
+    # byte sequence without parsing.
+    #
+    # Error if +delta+ is negative.
+    #
+    def skip delta
+      raise 'Type mismatch' unless delta.is_a? Integer
+      raise 'Invalid byte count' if delta < 0
+      @offset += delta
+      return
+    end
+
+    #
+    # Moves the cursor backwards by +delta+ bytes.
+    #
+    # Error if +delta+ is negative.
+    #
+    def unskip delta
+      raise 'Type mismatch' unless delta.is_a? Integer
+      raise 'Invalid byte count' if delta < 0
+      @offset -= delta
+      return
+    end
+
+    #
+    # Returns +true+ if the cursor has passed the last byte currently in
+    # the underlying pool or +false+ otherwise.
+    #
+    def eof?
+      return @offset >= @pool.size
+    end
+  end
+end

data/lib/baikal/hexdump.rb

@@ -0,0 +1,257 @@
+# $Id: hexdump.rb 1275 2009-10-03 10:28:54Z digwuren $
+
+module Baikal
+  #
+  # Hexdumps bytes from +data_source+ into the given +port+ (by default,
+  # +$stdout+) using the given format (by default, +DEFAULT_HEXDUMP_FORMAT+).
+  # Uses the +length+ method of +data_source+ to determine byte count and the
+  # +[]+ method with integer range arguments to extract row-sized slices.
+  # +data_source+ being a +String+ instance behaves as expected.
+  #
+  def Baikal::hexdump data_source, port = $stdout, format = Hexdump::DEFAULT_HEXDUMP_FORMAT
+    row = Hexdump::Row.new
+    row.expected_size = format.bytes_per_row
+    # iterate over rows
+    row.offset = 0
+    block_row_counter = 0
+    while row.offset < data_source.bytesize do
+      if format.rows_per_block != 0 then
+        block_row_counter += 1
+        if block_row_counter == format.rows_per_block then
+          port.puts # block separator
+          block_row_counter = 0
+        end
+      end
+      row.data = data_source.unpack "@#{row.offset} C#{format.bytes_per_row}"
+      format.format_row row, port
+      row.offset += format.bytes_per_row
+    end
+    return
+  end
+
+  module Hexdump
+    #
+    # Represents the row currently being processed by +hexdump+.
+    #
+    class Row
+      #
+      # Offset of the first byte on this row.
+      #
+      attr_accessor :offset
+
+      #
+      # The row's expected size, as per +Hexdump::Format#bytes_per_row+.
+      #
+      attr_accessor :expected_size
+
+      #
+      # Bytes of this row in an +Array+ instance.  For the last row, some of
+      # the trailing elements may be +nil+.
+      #
+      attr_accessor :data
+    end
+
+    #
+    # Represents a particular field of a hexdump format.  Abstract class; see
+    # +Field::Offset+, +Field::Decoration+, and +Field::Data+ as practical
+    # hexdump fields.
+    #
+    class Field
+      #
+      # Returns a string representing this field's contribution to dumping
+      # +row+, an instance of +Hexdump::Row+
+      #
+      def format row
+      end
+
+      #
+      # The +Offset+ field outputs the offset of a hexdump row, formatted
+      # via a printf template.
+      #
+      class Offset < Field
+        def initialize template
+          super()
+          @template = template
+          return
+        end
+
+        def format row
+          return sprintf(@template, row.offset)
+        end
+      end
+
+      #
+      # The +Decoration+ field outputs a literal string.
+      #
+      class Decoration < Field
+        def initialize content
+          super()
+          @content = content
+          return
+        end
+
+        def format row
+          return @content
+        end
+      end
+
+      #
+      # The +Data+ field outputs data on a hexdump row, formatted using a
+      # supplied +Proc+ instance.  +grouping_rules+ are specified as
+      # pairs of group size and separator.  All group sizes are processed
+      # in parallel.  In group boundaries where multiple grouping rules
+      # would match, only the leftmost one is used.
+      #
+      class Data < Field
+        def initialize formatter, *grouping_rules
+          super()
+          @formatter = formatter
+          @grouping_rules = grouping_rules
+          return
+        end
+
+        def format row
+          output = ""
+          (0 ... row.expected_size).each do |column|
+            if column != 0 then
+              rule = @grouping_rules.detect{|divisor, separator| column % divisor == 0}
+              output << rule[1] if rule
+            end
+            output << @formatter.call(row.data[column])
+          end
+          return output
+        end
+
+        #
+        # Formats the byte as a zero-padded two-digit lowercase hexadecimal number.
+        #
+        # :stopdoc: Unfortunately, RDoc gets confused by thunk constants.
+        LOWERCASE_HEX = proc do |value|
+          if value then
+            raise 'Type mismatch' unless value.is_a? Integer
+            sprintf("%02x", value)
+          else
+            "  "
+          end
+        end
+
+        #
+        # Formats the byte as a zero-padded two-digit uppercase hexadecimal number.
+        #
+        UPPERCASE_HEX = proc do |value|
+          if value then
+            raise 'Type mismatch' unless value.is_a? Integer
+            sprintf("%02X", value)
+          else
+            "  "
+          end
+        end
+
+        #
+        # Formats the byte as a zero-padded three-digit octal number.
+        #
+        OCTAL = proc do |value|
+          if value then
+            raise 'Type mismatch' unless value.is_a? Integer
+            sprintf("%03o", value)
+          else
+            "   "
+          end
+        end
+
+        #
+        # Formats the byte as a space-padded three-digit decimal number.
+        #
+        DECIMAL = proc do |value|
+          if value then
+            raise 'Type mismatch' unless value.is_a? Integer
+            sprintf("%3i", value)
+          else
+            "   "
+          end
+        end
+
+        #
+        # Formats the byte as an ASCII character.  Nonprintable characters are
+        # replaced by a period.
+        #
+        ASCII = proc do |value|
+          if value then
+            raise 'Type mismatch' unless value.is_a? Integer
+            value >= 0x20 && value <= 0x7E ? value.chr : "."
+          else
+            " "
+          end
+        end
+
+        #
+        # Decodes the byte as a Latin-1 character and formats it in UTF-8.
+        # Nonprintable characters are replaced by a period, as in
+        # +ASCII+.
+        #
+        LATIN1 = proc do |value|
+          if value then
+            raise 'Type mismatch' unless value.is_a? Integer
+            if (0x20 .. 0x7E).include? value or (0xA0 .. 0xFF).include? value then
+              [value].pack('U')
+            else
+              "."
+            end
+          else
+            " "
+          end
+        end
+
+        # :startdoc:
+      end
+    end
+
+    #
+    # Describes a textual hexdump format.
+    #
+    class Format
+      attr_reader :rows_per_block # zero indicates no block separation
+      attr_reader :bytes_per_row # zero indicates no group separation
+      attr_reader :fields
+
+      #
+      # Creates a new +Hexdump::Format+ instance with the specified structure.
+      # +bytes_per_row+ specifies the number of bytes to be listed on every
+      # row; +fields+ (a list of +Hexdump::Field+ instances) contains the
+      # formatting rules.  +rows_per_block+, if given and nonzero, will cause
+      # an empty line to be printed after every block of that many rows.
+      #
+      def initialize bytes_per_row, fields, rows_per_block = 0
+        super()
+        @bytes_per_row = bytes_per_row
+        @fields = fields
+        @rows_per_block = rows_per_block
+        return
+      end
+
+      #
+      # Formats a given +row+ (an instance of +Hexdump::Row+) according to
+      # formatting rules embodied in this +Hexdump_Format+ instance and
+      # outputs the result into the given +port+
+      #
+      def format_row row, port
+        raise 'Type mismatch' unless row.is_a? Hexdump::Row
+        port.puts @fields.map{|field| field.format(row)}.join('')
+        return
+      end
+    end
+
+    #
+    # The default hexdump format uses five-digit offsets (fits up to a
+    # mebibyte of data, which should be enough for everybody) and lists the
+    # content on sixteen bytes per row, both in hexadecimal (grouped by
+    # four bytes) and ASCII-or-dot form.
+    #
+    DEFAULT_HEXDUMP_FORMAT = Format.new(16, [
+      Field::Offset.new("%05X: "),
+      Field::Data.new(Field::Data::UPPERCASE_HEX, [4, '  '], [1, ' ']),
+      Field::Decoration.new("  "),
+      Field::Data.new(Field::Data::ASCII),
+    ])
+  end
+end