hexdump 0.3.0 → 1.0.1

data/lib/hexdump/reader.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+require 'hexdump/type'
+
+module Hexdump
+  #
+  # @api private
+  #
+  # @since 1.0.0
+  #
+  class Reader
+
+    # The type to decode the data as.
+    #
+    # @return [Type]
+    attr_reader :type
+
+    # Controls whether to offset N number of bytes before starting to read data.
+    #
+    # @return [Integer, nil]
+    attr_reader :offset
+
+    # Controls control many bytes to read.
+    #
+    # @return [Integer, nil]
+    attr_reader :length
+
+    #
+    # Initializes the reader.
+    #
+    # @param [Type] type
+    #   The type to decode the data as.
+    #
+    # @param [Integer, nil] offset
+    #   Controls whether to offset N number of bytes before starting to read
+    #   data.
+    #
+    # @param [Integer, nil] length
+    #   Controls control many bytes to read.
+    #
+    # @param [Boolean] zero_pad
+    #   Controls whether the remaining data will be padded with zeros.
+    #
+    def initialize(type, offset: nil, length: nil, zero_pad: false)
+      @type     = type
+      @offset   = offset
+      @length   = length
+      @zero_pad = zero_pad
+    end
+
+    def zero_pad?
+      @zero_pad
+    end
+
+    #
+    # Reads each byte from the given data.
+    #
+    # @yield [byte]
+    #
+    # @yieldparam [Integer] byte
+    #
+    # @return [Enumerator]
+    #
+    # @raise [ArgumentError]
+    #
+    def each_byte(data)
+      return enum_for(__method__,data) unless block_given?
+
+      unless data.respond_to?(:each_byte)
+        raise(ArgumentError,"the given data must respond to #each_byte")
+      end
+
+      count = 0
+
+      data.each_byte do |b|
+        count += 1
+
+        # offset the first @offset number of bytes
+        if @offset.nil? || count > @offset
+          yield b
+        end
+
+        # stop reading after @length number of bytes
+        break if @length && count >= @length
+      end
+    end
+
+    #
+    # Reads each string of the same number of bytes as the {#type}'s
+    # {Type#size size}.
+    #
+    # @param [#each_byte] data
+    #
+    # @yield [slice]
+    #
+    # @yieldparam [String] slice
+    #
+    # @raise [ArgumentError]
+    #
+    def each_slice(data)
+      return enum_for(__method__,data) unless block_given?
+
+      unless data.respond_to?(:each_byte)
+        raise(ArgumentError,"the given data must respond to #each_byte")
+      end
+
+      if @type.size == 1
+        each_byte(data) do |b|
+          yield b.chr
+        end
+      else
+        buffer = String.new("\0" * @type.size, capacity: @type.size,
+                                               encoding: Encoding::BINARY)
+        index  = 0
+
+        each_byte(data) do |b|
+          buffer[index] = b.chr(Encoding::BINARY)
+          index += 1
+
+          if index >= @type.size
+            yield buffer.dup
+            index = 0
+          end
+        end
+
+        if index > 0
+          if @zero_pad
+            # zero pad the rest of the buffer
+            (index..(@type.size - 1)).each do |i|
+              buffer[i] = "\0"
+            end
+
+            yield buffer
+          else
+            # yield the remaining partial buffer
+            yield buffer[0,index]
+          end
+        end
+      end
+    end
+
+    #
+    # @param [#each_byte] data
+    #
+    # @yield [raw, uint]
+    #
+    # @yieldparam [String] raw
+    #
+    # @yieldparam [Integer, nil] uint
+    #
+    # @return [Enumerator]
+    #
+    # @raise [ArgumentError]
+    #
+    def each_uint(data,&block)
+      return enum_for(__method__,data) unless block_given?
+
+      unless data.respond_to?(:each_byte)
+        raise(ArgumentError,"the given data must respond to #each_byte")
+      end
+
+      if @type.size == 1
+        each_byte(data) do |b|
+          yield b.chr, b
+        end
+      else
+        pack_format = case @type.size
+                      when 1
+                        'c'
+                      when 2
+                        case @type.endian
+                        when :little then 'S<'
+                        when :big    then 'S>'
+                        else
+                          raise(TypeError,"unsupported endian #{@type.endian} for #{@type.inspect}")
+                        end
+                      when 4
+                        case @type.endian
+                        when :little then 'L<'
+                        when :big    then 'L>'
+                        else
+                          raise(TypeError,"unsupported endian #{@type.endian} for #{@type.inspect}")
+                        end
+                      when 8
+                        case @type.endian
+                        when :little then 'Q<'
+                        when :big    then 'Q>'
+                        else
+                          raise(TypeError,"unsupported endian #{@type.endian} for #{@type.inspect}")
+                        end
+                      else
+                        raise(TypeError,"unsupported type size #{@type.size} for #{@type.inspect}")
+                      end
+
+        each_slice(data) do |slice|
+          yield slice, slice.unpack1(pack_format)
+        end
+      end
+    end
+
+    #
+    # @param [#each_byte] data
+    #
+    # @yield [raw, int]
+    #
+    # @yieldparam [String] raw
+    #
+    # @yieldparam [Integer, nil] int
+    #
+    # @return [Enumerator]
+    #
+    def each_int(data)
+      return enum_for(__method__,data) unless block_given?
+
+      pack_format = case @type.size
+                    when 1
+                      'c'
+                    when 2
+                      case @type.endian
+                      when :little then 's<'
+                      when :big    then 's>'
+                      else
+                        raise(TypeError,"unsupported endian #{@type.endian} for #{@type.inspect}")
+                      end
+                    when 4
+                      case @type.endian
+                      when :little then 'l<'
+                      when :big    then 'l>'
+                      else
+                        raise(TypeError,"unsupported endian #{@type.endian} for #{@type.inspect}")
+                      end
+                    when 8
+                      case @type.endian
+                      when :little then 'q<'
+                      when :big    then 'q>'
+                      else
+                        raise(TypeError,"unsupported endian #{@type.endian} for #{@type.inspect}")
+                      end
+                    else
+                      raise(TypeError,"unsupported type size #{@type.size} for #{@type.inspect}")
+                    end
+
+      each_slice(data) do |slice|
+        yield slice, slice.unpack1(pack_format)
+      end
+    end
+
+    #
+    # @param [#each_byte] data
+    #
+    # @yield [raw, float]
+    #
+    # @yieldparam [String] raw
+    #
+    # @yieldparam [Float, nil] float
+    #
+    # @return [Enumerator]
+    #
+    def each_float(data)
+      return enum_for(__method__,data) unless block_given?
+
+      pack_format = case @type.endian
+                    when :little
+                      case @type.size
+                      when 4 then 'e'
+                      when 8 then 'E'
+                      else
+                        raise(TypeError,"unsupported type size #{@type.size} for #{@type.inspect}")
+                      end
+                    when :big
+                      case @type.size
+                      when 4 then 'g'
+                      when 8 then 'G'
+                      else
+                        raise(TypeError,"unsupported type size #{@type.size} for #{@type.inspect}")
+                      end
+                    else
+                      raise(TypeError,"unsupported endian #{@type.endian} for #{@type.inspect}")
+                    end
+
+      each_slice(data) do |slice|
+        yield slice, slice.unpack1(pack_format)
+      end
+    end
+
+    #
+    # @param [#each_byte] data
+    #
+    # @yield [raw, value]
+    #
+    # @yieldparam [String] raw
+    #
+    # @yieldparam [Integer, Float, nil] value
+    #
+    # @return [Enumerator]
+    #
+    def each(data,&block)
+      return enum_for(__method__,data) unless block
+
+      case @type
+      when Type::UInt
+        each_uint(data,&block)
+      when Type::Float
+        each_float(data,&block)
+      when Type::Int
+        each_int(data,&block)
+      else
+        raise(TypeError,"unsupported type: #{@type.inspect}")
+      end
+    end
+
+  end
+end

data/lib/hexdump/theme/ansi.rb

@@ -0,0 +1,82 @@
+module Hexdump
+  class Theme
+    #
+    # Represents an ANSI control sequence.
+    #
+    # @api private
+    #
+    # @since 1.0.0
+    #
+    class ANSI
+      # ANSI reset control sequence
+      RESET = "\e[0m"
+
+      PARAMETERS = {
+        reset:     RESET,
+
+        bold:      "\e[1m",
+        faint:     "\e[2m",
+        italic:    "\e[3m",
+        underline: "\e[4m",
+        invert:    "\e[7m",
+        strike:    "\e[9m",
+        black:     "\e[30m",
+        red:       "\e[31m",
+        green:     "\e[32m",
+        yellow:    "\e[33m",
+        blue:      "\e[34m",
+        magenta:   "\e[35m",
+        cyan:      "\e[36m",
+        white:     "\e[37m",
+
+        on_black:   "\e[40m",
+        on_red:     "\e[41m",
+        on_green:   "\e[42m",
+        on_yellow:  "\e[43m",
+        on_blue:    "\e[44m",
+        on_magenta: "\e[45m",
+        on_cyan:    "\e[46m",
+        on_white:   "\e[47m"
+      }
+
+      # The style name(s).
+      #
+      # @return [Symbol, Array<Symbol>] style
+      attr_reader :parameters
+
+      # The ANSI string.
+      #
+      # @return [String]
+      attr_reader :string
+
+      #
+      # Initializes an ANSI control sequence.
+      #
+      # @param [Symbol, Array<Symbol>] parameters
+      #   The ANSI styling parameters. See {PARAMETERS}.
+      #
+      def initialize(parameters)
+        @parameters = parameters
+
+        @string = String.new
+
+        Array(parameters).each do |name|
+          @string << PARAMETERS.fetch(name) do
+            raise(ArgumentError,"unknown ANSI parameter: #{name}")
+          end
+        end
+      end
+
+      #
+      # Returns the ANSI string.
+      #
+      # @return [String]
+      #
+      def to_s
+        @string
+      end
+
+      alias to_str to_s
+    end
+  end
+end

data/lib/hexdump/theme/rule.rb

@@ -0,0 +1,159 @@
+require_relative 'ansi'
+
+require 'strscan'
+
+module Hexdump
+  class Theme
+    #
+    # Represents a color highlighting rule.
+    #
+    # @api private
+    #
+    # @since 1.0.0
+    #
+    class Rule
+
+      # The default style to apply to strings.
+      #
+      # @return [ANSI, nil]
+      attr_reader :style
+
+      # Highlighting rules for exact strings.
+      #
+      # @return [Hash{String => ANSI}]
+      attr_reader :highlight_strings
+
+      # Highlighting rules for matching substrings.
+      #
+      # @return [Hash{String => ANSI}]
+      attr_reader :highlight_regexps
+
+      #
+      # Initializes the color.
+      #
+      # @param [Symbol, Array<Symbol>] style
+      #   The default style name(s). See {ANSI::PARAMETERS}.
+      #
+      # @param [Hash{String,Regexp => Symbol,Array<Symbol>}, nil] highlights
+      #   Optional highlighting rules.
+      #
+      def initialize(style: nil, highlights: nil)
+        @reset = ANSI::RESET
+        
+        @style = if style
+                   ANSI.new(style)
+                 end
+
+        @highlight_strings = {}
+        @highlight_regexps = {}
+
+        if highlights
+          highlights.each do |pattern,style|
+            highlight(pattern,style)
+          end
+        end
+      end
+
+      #
+      # The highlighting rules.
+      #
+      # @return [Hash{String,Regexp => ANSI}]
+      #   The combination of {#highlight_strings} and {#highlight_regexps}.
+      #
+      def highlights
+        @highlight_strings.merge(@highlight_regexps)
+      end
+
+      #
+      # Adds a highlighting rule.
+      # 
+      # @param [String, Regexp] pattern
+      #   The exact String to highlight or regular expression to highlight.
+      #
+      # @param [Symbol, Array<Symbol>] style
+      #   The style name(s). See {ANSI::PARAMETERS}.
+      #
+      # @raise [ArgumentError]
+      #   The given pattern was not a String or Regexp.
+      #
+      # @example
+      #   hexdump.style.numeric.highlight('00', :faint)
+      #
+      # @example
+      #   hexdump.style.index.highlight(/00$/, [:white, :bold])
+      #
+      # @api public
+      #
+      def highlight(pattern,style)
+        ansi = ANSI.new(style)
+
+        case pattern
+        when String
+          @highlight_strings[pattern] = ansi
+        when Regexp
+          @highlight_regexps[pattern] = ansi
+        else
+          raise(ArgumentError,"pattern must be a String or Regexp: #{pattern.inspect}")
+        end
+      end
+
+      #
+      # Applies coloring/highlighting to a string.
+      #
+      # @param [String] string
+      #   The string to color/highlight.
+      #
+      # @return [String]
+      #   The colored the string.
+      #
+      def apply(string)
+        if (!@highlight_strings.empty? || !@highlight_regexps.empty?)
+          apply_highlight(string)
+        elsif @style
+          "#{@style}#{string}#{@reset}"
+        else
+          string
+        end
+      end
+
+      private
+
+      def apply_highlight(string)
+        if (ansi = @highlight_strings[string])
+          # highlight the whole string
+          "#{ansi}#{string}#{@reset}"
+        else
+          scanner    = StringScanner.new(string)
+          new_string = String.new
+
+          until scanner.eos?
+            matched = false
+
+            @highlight_regexps.each do |regexp,ansi|
+              if (match = scanner.scan(regexp))
+                # highlight the match
+                new_string << "#{ansi}#{match}#{@reset}"
+                new_string << "#{@style}" unless scanner.eos?
+                matched = true
+                break
+              end
+            end
+
+            unless matched
+              # next char
+              new_string << scanner.getch
+            end
+          end
+
+          if @style
+            new_string.prepend(@style) unless new_string.start_with?("\e")
+            new_string << @reset       unless new_string.end_with?(@reset)
+          end
+
+          new_string
+        end
+      end
+
+    end
+  end
+end

data/lib/hexdump/theme.rb

@@ -0,0 +1,61 @@
+require_relative 'theme/rule'
+
+module Hexdump
+  #
+  # Represents a hexdump theme (styling + highlighting).
+  #
+  # @api semipublic
+  #
+  # @since 1.0.0
+  #
+  class Theme
+
+    # The index styling/highlights.
+    #
+    # @return [Rule, nil]
+    #
+    # @api public
+    attr_reader :index
+
+    # The numeric styling/highlights.
+    #
+    # @return [Rule, nil]
+    #
+    # @api public
+    attr_reader :numeric
+
+    # The chars styling/highlights.
+    #
+    # @return [Rule, nil]
+    #
+    # @api public
+    attr_reader :chars
+
+    #
+    # Initializes the theme.
+    #
+    # @param [Hash{:index,:numeric,:chars => Symbol,Array<Symbol>,nil}] style
+    #   The default style of the index, numeric, and/or chars columns.
+    #
+    # @param [Hash{:index,:numeric,:chars => Hash{String,Regexp => Symbol,Array<Symbol>},nil}] highlights
+    #   The highlighting rules for the index, numeric, and/or chars columns.
+    #
+    def initialize(style: {}, highlights: {})
+      @index   = Rule.new(
+                   style:      style[:index],
+                   highlights: highlights[:index]
+                 )
+
+      @numeric = Rule.new(
+                   style:      style[:numeric],
+                   highlights: highlights[:numeric]
+                 )
+
+      @chars   = Rule.new(
+                   style:      style[:chars],
+                   highlights: highlights[:chars]
+                )
+    end
+
+  end
+end