hexdump 0.3.0 → 1.0.1

data/lib/hexdump/mixin.rb

@@ -0,0 +1,192 @@
+require_relative 'hexdump'
+
+module Hexdump
+  #
+  # Provides a {hexdump Mixin#hexdump} method that can be included into objects.
+  #
+  #     class DataObject
+  #     
+  #       include Hexdump::Mixin
+  #       
+  #       def each_byte
+  #         # ...
+  #       end
+  #     
+  #     end
+  #     
+  #     data.hexdump
+  #
+  # @api public
+  #
+  # @since 1.0.0
+  #
+  module Mixin
+    #
+    # Prints a hexdumps of the object.
+    #
+    # @param [#print] output ($stdout)
+    #   The output to print the hexdump to.
+    #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments for {Hexdump#initialize}.
+    #
+    # @option kwargs [:int8, :uint8, :char, :uchar, :byte, :int16, :int16_le, :int16_be, :int16_ne, :uint16, :uint16_le, :uint16_be, :uint16_ne, :short, :short_le, :short_be, :short_ne, :ushort, :ushort_le, :ushort_be, :ushort_ne, :int32, :int32_le, :int32_be, :int32_ne, :uint32, :uint32_le, :uint32_be, :uint32_ne, :int, :long, :long_le, :long_be, :long_ne, :uint, :ulong, :ulong_le, :ulong_be, :ulong_ne, :int64, :int64_le, :int64_be, :int64_ne, :uint64, :uint64_le, :uint64_be, :uint64_ne, :long_long, :long_long_le, :long_long_be, :long_long_ne, :ulong_long, :ulong_long_le, :ulong_long_be, :ulong_long_ne, :float, :float_le, :float_be, :float_ne, :double, :double_le, :double_be, :double_ne] :type (:byte)
+    #   The type to decode the data as.
+    #
+    # @option kwargs [Integer, nil] :offset
+    #   Controls whether to skip N number of bytes before starting to read data.
+    #
+    # @option kwargs [Integer, nil] :length
+    #   Controls control many bytes to read.
+    #
+    # @option kwargs [Boolean] :zero_pad (false)
+    #   Enables or disables zero padding of data, so that the remaining bytes
+    #   can be decoded as a uint, int, or float.
+    #
+    # @option kwargs [Integer] :columns (16)
+    #   The number of bytes to dump for each line.
+    #
+    # @option kwargs [Integer, nil] :group_columns
+    #   Separate groups of columns with an additional space.
+    #
+    # @option kwargs [Integer, :type, nil] :group_chars
+    #   Group chars into columns.
+    #   If `:type`, then the chars will be grouped by the `type`'s size.
+    #
+    # @option kwargs [Boolean] :repeating
+    #   Controls whether to omit repeating duplicate rows data with a `*`.
+    #
+    # @option kwargs [16, 10, 8, 2] :base (16)
+    #   The base to print bytes in.
+    #
+    # @option kwargs [16, 10, 8, 2] :index_base (16)
+    #   Control the base that the index is displayed in.
+    #
+    # @option kwargs [Boolean] :chars_column (true)
+    #   Controls whether to display the characters column.
+    #
+    # @option kwargs [:ascii, :utf8, Encoding, nil] :encoding
+    #   The encoding to display the characters in.
+    #
+    # @option kwargs [Integer, nil] :index_offset
+    #   The offset to start the index at.
+    #
+    # @option kwargs [Boolean, Hash{:index,:numeric,:chars => Symbol,Array<Symbol>}] :style
+    #   Enables theming of index, numeric, or chars columns.
+    #
+    # @option kwargs [Boolean, Hash{:index,:numeric,:chars => Hash{String,Regexp => Symbol,Array<Symbol>}}] :highlights
+    #   Enables selective highlighting of index, numeric, or chars columns.
+    #
+    # @yield [hexdump]
+    #   If a block is given, it will be passed the newly initialized hexdump
+    #   instance.
+    #
+    # @yieldparam [Hexdump::Hexdump] hexdump
+    #   The newly initialized hexdump instance.
+    #
+    # @raise [ArgumentError]
+    #   The given data does not define the `#each_byte` method,
+    #   the `:output` value does not support the `#<<` method or
+    #   the `:base` value was unknown.
+    #
+    # @example
+    #   obj.hexdump
+    #   # ...
+    #
+    # @example Hexdumping to a custom output:
+    #   File.open('hexdump.txt') do |output|
+    #     obj.hexdump(output: output)
+    #   end
+    #
+    # @example Hexdumping to an Array:
+    #   lines = []
+    #   obj.hexdump(output: lines)
+    #
+    def hexdump(output: $stdout, **kwargs,&block)
+      hexdump = ::Hexdump::Hexdump.new(**kwargs,&block)
+
+      hexdump.hexdump(self, output: output)
+    end
+
+    #
+    # Outputs the hexdump to a String.
+    #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments for {Hexdump#initialize}.
+    #
+    # @option kwargs [:int8, :uint8, :char, :uchar, :byte, :int16, :int16_le, :int16_be, :int16_ne, :uint16, :uint16_le, :uint16_be, :uint16_ne, :short, :short_le, :short_be, :short_ne, :ushort, :ushort_le, :ushort_be, :ushort_ne, :int32, :int32_le, :int32_be, :int32_ne, :uint32, :uint32_le, :uint32_be, :uint32_ne, :int, :long, :long_le, :long_be, :long_ne, :uint, :ulong, :ulong_le, :ulong_be, :ulong_ne, :int64, :int64_le, :int64_be, :int64_ne, :uint64, :uint64_le, :uint64_be, :uint64_ne, :long_long, :long_long_le, :long_long_be, :long_long_ne, :ulong_long, :ulong_long_le, :ulong_long_be, :ulong_long_ne, :float, :float_le, :float_be, :float_ne, :double, :double_le, :double_be, :double_ne] :type (:byte)
+    #   The type to decode the data as.
+    #
+    # @option kwargs [Integer, nil] :offset
+    #   Controls whether to skip N number of bytes before starting to read data.
+    #
+    # @option kwargs [Integer, nil] :length
+    #   Controls control many bytes to read.
+    #
+    # @option kwargs [Boolean] :zero_pad (false)
+    #   Enables or disables zero padding of data, so that the remaining bytes
+    #   can be decoded as a uint, int, or float.
+    #
+    # @option kwargs [Integer] :columns (16)
+    #   The number of bytes to dump for each line.
+    #
+    # @option kwargs [Integer, nil] :group_columns
+    #   Separate groups of columns with an additional space.
+    #
+    # @option kwargs [Integer, :type, nil] :group_chars
+    #   Group chars into columns.
+    #   If `:type`, then the chars will be grouped by the `type`'s size.
+    #
+    # @option kwargs [Boolean] :repeating
+    #   Controls whether to omit repeating duplicate rows data with a `*`.
+    #
+    # @option kwargs [16, 10, 8, 2] :base (16)
+    #   The base to print bytes in.
+    #
+    # @option kwargs [16, 10, 8, 2] :index_base (16)
+    #   Control the base that the index is displayed in.
+    #
+    # @option kwargs [Integer, nil] :index_offset
+    #   The offset to start the index at.
+    #
+    # @option kwargs [Boolean] :chars_column (true)
+    #   Controls whether to display the characters column.
+    #
+    # @option kwargs [:ascii, :utf8, Encoding, nil] :encoding
+    #   The encoding to display the characters in.
+    #
+    # @option kwargs [Boolean, Hash{:index,:numeric,:chars => Symbol,Array<Symbol>}] :style
+    #   Enables theming of index, numeric, or chars columns.
+    #
+    # @option kwargs [Boolean, Hash{:index,:numeric,:chars => Hash{String,Regexp => Symbol,Array<Symbol>}}] :highlights
+    #   Enables selective highlighting of index, numeric, or chars columns.
+    #
+    # @yield [hexdump]
+    #   If a block is given, it will be passed the newly initialized hexdump
+    #   instance.
+    #
+    # @yieldparam [Hexdump::Hexdump] hexdump
+    #   The newly initialized hexdump instance.
+    #
+    # @return [String]
+    #   The output of the hexdump.
+    #
+    # @raise [ArgumentError]
+    #   The given data does not define the `#each_byte` method,
+    #   the `:base` value was unknown.
+    #
+    # @note
+    #   **Caution:** this method appends each line of the hexdump to a String,
+    #   and that String can grow quite large and consume a lot of memory.
+    #
+    # @example
+    #   obj.hexdump
+    #   # => "..."
+    #
+    def to_hexdump(**kwargs,&block)
+      hexdump = ::Hexdump::Hexdump.new(**kwargs,&block)
+
+      hexdump.dump(self)
+    end
+  end
+end

data/lib/hexdump/module_methods.rb

@@ -0,0 +1,132 @@
+require_relative 'hexdump'
+
+module Hexdump
+  #
+  # Provides the {hexdump ModuleMethods#hexdump} top-level method that can be
+  # extended into modules.
+  #
+  #     module Context
+  #     
+  #       extend Hexdump::ModuleMethods
+  #       
+  #     end
+  #     
+  module ModuleMethods
+    #
+    # Hexdumps the given data.
+    #
+    # @param [#each_byte] data
+    #   The data to be hexdumped.
+    #
+    # @param [#print] output ($stdout)
+    #   The output to print the hexdump to.
+    #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments for {Hexdump#initialize}.
+    #
+    # @option kwargs [:int8, :uint8, :char, :uchar, :byte, :int16, :int16_le, :int16_be, :int16_ne, :uint16, :uint16_le, :uint16_be, :uint16_ne, :short, :short_le, :short_be, :short_ne, :ushort, :ushort_le, :ushort_be, :ushort_ne, :int32, :int32_le, :int32_be, :int32_ne, :uint32, :uint32_le, :uint32_be, :uint32_ne, :int, :long, :long_le, :long_be, :long_ne, :uint, :ulong, :ulong_le, :ulong_be, :ulong_ne, :int64, :int64_le, :int64_be, :int64_ne, :uint64, :uint64_le, :uint64_be, :uint64_ne, :long_long, :long_long_le, :long_long_be, :long_long_ne, :ulong_long, :ulong_long_le, :ulong_long_be, :ulong_long_ne, :float, :float_le, :float_be, :float_ne, :double, :double_le, :double_be, :double_ne] :type (:byte)
+    #   The type to decode the data as.
+    #
+    # @option kwargs [Integer, nil] :offset
+    #   Controls whether to skip N number of bytes before starting to read data.
+    #
+    # @option kwargs [Integer, nil] :length
+    #   Controls control many bytes to read.
+    #
+    # @option kwargs [Boolean] :zero_pad (false)
+    #   Enables or disables zero padding of data, so that the remaining bytes
+    #   can be decoded as a uint, int, or float.
+    #
+    # @option kwargs [Integer] :columns (16)
+    #   The number of bytes to dump for each line.
+    #
+    # @option kwargs [Integer, nil] :group_columns
+    #   Separate groups of columns with an additional space.
+    #
+    # @option kwargs [Integer, :type, nil] :group_chars
+    #   Group chars into columns.
+    #   If `:type`, then the chars will be grouped by the `type`'s size.
+    #
+    # @option kwargs [Boolean] :repeating
+    #   Controls whether to omit repeating duplicate rows data with a `*`.
+    #
+    # @option kwargs [16, 10, 8, 2] :base (16)
+    #   The base to print bytes in.
+    #
+    # @option kwargs [16, 10, 8, 2] :index_base (16)
+    #   Control the base that the index is displayed in.
+    #
+    # @option kwargs [Integer, nil] :index_offset
+    #   The offset to start the index at.
+    #
+    # @option kwargs [Boolean] :chars_column (true)
+    #   Controls whether to display the characters column.
+    #
+    # @option kwargs [:ascii, :utf8, Encoding, nil] :encoding
+    #   The encoding to display the characters in.
+    #
+    # @option kwargs [Boolean, Hash{:index,:numeric,:chars => Symbol,Array<Symbol>}] :style
+    #   Enables theming of index, numeric, or chars columns.
+    #
+    # @option kwargs [Boolean, Hash{:index,:numeric,:chars => Hash{String,Regexp => Symbol,Array<Symbol>}}] :highlights
+    #   Enables selective highlighting of index, numeric, or chars columns.
+    #
+    # @yield [hexdump]
+    #   If a block is given, it will be passed the newly initialized hexdump
+    #   instance.
+    #
+    # @yieldparam [Hexdump::Hexdump] hexdump
+    #   The newly initialized hexdump instance.
+    #
+    # @raise [ArgumentError]
+    #   The given data does not define the `#each_byte` method,
+    #   the `:output` value does not support the `#<<` method or
+    #   the `:base` value was unknown.
+    #
+    # @example
+    #   hexdump("hello\0")
+    #   # 00000000  68 65 6c 6c 6f 00                                |hello.|
+    #   # 00000006
+    #
+    # @example Hexdumping to a custom output:
+    #   File.open('hexdump.txt') do |output|
+    #     hexdump("hello\0", output: output)
+    #   end
+    #
+    # @example Hexdumping to an Array:
+    #   lines = []
+    #   hexdump("hello\0", output: lines)
+    #
+    # @example Hexdumping with ANSI styling:
+    #   Hexdump.hexdump(style: {index: :white, numeric: :green, chars: :cyan})
+    #
+    # @example Hexdumping with ANSI highlighting:
+    #   Hexdump.hexdump("hello\0", highlights: {
+    #                                index: {/00$/ => [:white, :bold]},
+    #                                numeric: {
+    #                                  /^[8-f][0-9a-f]$/ => :faint,
+    #                                  /f/  => :cyan,
+    #                                  '00' => [:black, :on_red]
+    #                                },
+    #                                chars: {/[^\.]+/ => :green}
+    #                              })
+    #
+    # @example Configuring the hexdump with a block:
+    #   Hexdump.hexdump("hello\0") do |hexdump|
+    #     hexdump.type = :uint16
+    #     # ...
+    #   
+    #     hexdump.theme do |theme|
+    #       theme.index.highlight(/00$/, [:white, :bold])
+    #       theme.numeric.highlight(/^[8-f][0-9a-f]$/, :faint)
+    #       # ...
+    #     end
+    #   end
+    #
+    def hexdump(data, output: $stdout, **kwargs,&block)
+      hexdump = ::Hexdump::Hexdump.new(**kwargs,&block)
+
+      hexdump.hexdump(data, output: output)
+    end
+  end
+end

data/lib/hexdump/numeric/binary.rb

@@ -0,0 +1,55 @@
+require_relative 'exceptions'
+require_relative '../format_string'
+
+module Hexdump
+  module Numeric
+    #
+    # @api private
+    #
+    # @since 1.0.0
+    #
+    class Binary < FormatString
+
+      SIZE_TO_WIDTH = {
+        1 => 8,  # 0xff.to_s(2).length
+        2 => 16, # 0xffff.to_s(2).length
+        4 => 32, # 0xffffffff.to_s(2).length
+        8 => 64  # 0xffffffffffffffff.to_s(2).length
+      }
+
+      # @return [Integer]
+      attr_reader :width
+
+      #
+      # Initializes the binary format.
+      #
+      # @param [Type::Int, Type::UInt] type
+      #
+      # @raise [NotImplementedError]
+      #
+      # @raise [IncompatibleTypeError]
+      #
+      # @raise [TypeError]
+      #
+      def initialize(type)
+        case type
+        when Type::Int, Type::UInt
+          @width = SIZE_TO_WIDTH.fetch(type.size) do
+            raise(NotImplementedError,"type #{type} with unsupported size #{type.size}")
+          end
+
+          if type.signed?
+            super("% .#{@width}b"); @width += 1
+          else
+            super("%.#{@width}b")
+          end
+        when Type::Float
+          raise(IncompatibleTypeError,"cannot format floating-point numbers in binary")
+        else
+          raise(TypeError,"unsupported type: #{type.inspect}")
+        end
+      end
+
+    end
+  end
+end

data/lib/hexdump/numeric/char_or_int.rb

@@ -0,0 +1,95 @@
+require_relative '../format_string'
+
+module Hexdump
+  module Numeric
+    #
+    # @api private
+    #
+    # @since 1.0.0
+    #
+    class CharOrInt < FormatString
+
+      # @return [Hexadecimal, Decimal, Octal, Binary]
+      attr_reader :base
+
+      # @return [Encoding, nil]
+      attr_reader :encoding
+
+      #
+      # Initializes the character format.
+      #
+      # @param [Hexadecimal, Decimal, Octal, Binary] base
+      #   The numeric base format to fallback to if a value does not map to a
+      #   character.
+      #
+      # @param [Encoding, nil] encoding
+      #   The optional encoding to convert bytes to.
+      #
+      def initialize(base,encoding=nil)
+        @base     = base
+        @encoding = encoding
+        
+        super("%#{@base.width}s")
+      end
+
+      #
+      # The string width associated with the numeric base.
+      #
+      # @return [Integer]
+      #
+      def width
+        @base.width
+      end
+
+      #
+      # Formats a given ASCII byte value to a character or numeric format.
+      #
+      # @param [Integer] value
+      #   The ASCII byte value.
+      #
+      # @return [String]
+      #   The character or numeric formatted value.
+      #
+      def %(value)
+        if value == 0x00
+          super("\\0")
+        elsif value == 0x07
+          super("\\a")
+        elsif value == 0x08
+          super("\\b")
+        elsif value == 0x09
+          super("\\t")
+        elsif value == 0x0a
+          super("\\n")
+        elsif value == 0x0b
+          super("\\v")
+        elsif value == 0x0c
+          super("\\f")
+        elsif value == 0x0d
+          super("\\r")
+        else
+          if @encoding
+            if value >= 0x00
+              char = value.chr(@encoding) rescue nil
+
+              if char && char =~ /[[:print:]]/
+                super(char)
+              else
+                @base % value
+              end
+            else
+              @base % value
+            end
+          else
+            if (value >= 0x20 && value <= 0x7e)
+              super(value.chr)
+            else
+              @base % value
+            end
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/hexdump/numeric/decimal.rb

@@ -0,0 +1,56 @@
+require_relative '../format_string'
+
+module Hexdump
+  module Numeric
+    #
+    # @api private
+    #
+    # @since 1.0.0
+    #
+    class Decimal < FormatString
+
+      INT_SIZE_TO_WIDTH = {
+        1 => 3,  # 0xff.to_s(10).length
+        2 => 5,  # 0xffff.to_s(10).length
+        4 => 10, # 0xffffffff.to_s(10).length
+        8 => 20  # 0xffffffffffffffff.to_s(10).length
+      }
+
+      FLOAT_SIZE_TO_WIDTH = {
+        4 => 15,
+        8 => 24
+      }
+
+      # @return [Integer]
+      attr_reader :width
+
+      #
+      # Initializes the decimal format.
+      #
+      # @param [Type:Int, Type::UInt, Type::Float] type
+      #
+      def initialize(type)
+        widths = case type
+                 when Type::Float then FLOAT_SIZE_TO_WIDTH
+                 else                  INT_SIZE_TO_WIDTH
+                 end
+
+        @width = widths.fetch(type.size) do
+          raise(NotImplementedError,"type #{type} with unsupported size #{type.size}")
+        end
+
+        case type
+        when Type::Float
+          super("% #{@width}g"); @width += 1
+        else
+          if type.signed?
+            super("% #{@width}d"); @width += 1
+          else
+            super("%#{@width}d")
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/hexdump/numeric/exceptions.rb

@@ -0,0 +1,11 @@
+module Hexdump
+  module Numeric
+    #
+    # @api private
+    #
+    # @since 1.0.0
+    #
+    class IncompatibleTypeError < TypeError
+    end
+  end
+end

data/lib/hexdump/numeric/hexadecimal.rb

@@ -0,0 +1,59 @@
+require_relative '../format_string'
+
+module Hexdump
+  module Numeric
+    #
+    # @api private
+    #
+    # @since 1.0.0
+    #
+    class Hexadecimal < FormatString
+
+      INT_SIZE_TO_WIDTH = {
+        1 => 2, # 0xff.to_s(16).length
+        2 => 4, # 0xffff.to_s(16).length
+        4 => 8, # 0xffffffff.to_s(16).length
+        8 => 16 # 0xffffffffffffffff.to_s(16).length
+      }
+
+      FLOAT_WIDTH = 20
+
+      # @return [Integer]
+      attr_reader :width
+
+      #
+      # Initializes the hexadecimal format.
+      #
+      # @param [Type::Int, Type::UInt, Type::Float] type
+      #
+      def initialize(type)
+        case type
+        when Type::Float
+          if RUBY_ENGINE == 'jruby'
+            # XXX: https://github.com/jruby/jruby/issues/5122
+            begin
+              "%a" % 1.0
+            rescue ArgumentError
+              raise(NotImplementedError,"jruby #{RUBY_ENGINE_VERSION} does not support the \"%a\" format string")
+            end
+          end
+
+          # NOTE: jruby does not currently support the %a format string
+          @width = FLOAT_WIDTH
+          super("% #{@width}a"); @width += 1
+        else
+          @width = INT_SIZE_TO_WIDTH.fetch(type.size) do
+            raise(NotImplementedError,"type #{type} with unsupported size #{type.size}")
+          end
+
+          if type.signed?
+            super("% .#{@width}x"); @width += 1
+          else
+            super("%.#{@width}x")
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/hexdump/numeric/octal.rb

@@ -0,0 +1,55 @@
+require_relative 'exceptions'
+require_relative '../format_string'
+
+module Hexdump
+  module Numeric
+    #
+    # @api private
+    #
+    # @since 1.0.0
+    #
+    class Octal < FormatString
+
+      SIZE_TO_WIDTH = {
+        1 => 3,  # 0xff.to_s(7).length
+        2 => 6,  # 0xffff.to_s(7).length
+        4 => 11, # 0xffffffff.to_s(7).length
+        8 => 22  # 0xffffffffffffffff.to_s(7).length
+      }
+
+      # @return [Integer]
+      attr_reader :width
+
+      #
+      # Initializes the octal format.
+      #
+      # @param [Type::Int, Type::UInt] type
+      #
+      # @raise [NotImplementedError]
+      #
+      # @raise [IncompatibleTypeError]
+      #
+      # @raise [TypeError]
+      #
+      def initialize(type)
+        case type
+        when Type::Int, Type::UInt
+          @width = SIZE_TO_WIDTH.fetch(type.size) do
+            raise(NotImplementedError,"type #{type} with unsupported size #{type.size}")
+          end
+
+          if type.signed?
+            super("% .#{@width}o"); @width += 1
+          else
+            super("%.#{@width}o")
+          end
+        when Type::Float
+          raise(IncompatibleTypeError,"cannot format floating-point numbers in octal")
+        else
+          raise(TypeError,"unsupported type: #{type.inspect}")
+        end
+      end
+
+    end
+  end
+end

data/lib/hexdump/numeric.rb

@@ -0,0 +1,5 @@
+require_relative 'numeric/binary'
+require_relative 'numeric/octal'
+require_relative 'numeric/decimal'
+require_relative 'numeric/hexadecimal'
+require_relative 'numeric/char_or_int'