hexdump 0.2.4 → 0.3.0

data/lib/hexdump/extensions.rb

@@ -1,4 +1,2 @@
-require 'hexdump/extensions/string'
-require 'hexdump/extensions/string_io'
-require 'hexdump/extensions/io'
-require 'hexdump/extensions/file'
+# DEPRECATED: use hexdump/core_ext instead.
+require 'hexdump/core_ext'

data/lib/hexdump/hexdump.rb

@@ -24,28 +24,25 @@ module Hexdump
   # @param [#each_byte] data
   #   The data to be hexdumped.
   #
-  # @param [Hash] options
-  #   Additional options.
-  #
-  # @option options [Integer] :width (16)
+  # @param [Integer] width (16)
   #   The number of bytes to dump for each line.
   #
-  # @option options [Integer] :endian (:little)
+  # @param [Integer] endian (:little)
   #   The endianness that the bytes are organized in. Supported endianness
   #   include `:little` and `:big`.
   #
-  # @option options [Integer] :word_size (1)
+  # @param [Integer] word_size (1)
   #   The number of bytes within a word.
   #
-  # @option options [Symbol, Integer] :base (:hexadecimal)
+  # @param [Symbol, Integer] base (:hexadecimal)
   #   The base to print bytes in. Supported bases include, `:hexadecimal`,
   #   `:hex`, `16, `:decimal`, `:dec`, `10, `:octal`, `:oct`, `8`,
   #   `:binary`, `:bin` and `2`.
   #
-  # @option options [Boolean] :ascii (false)
+  # @param [Boolean] ascii (false)
   #   Print ascii characters when possible.
   #
-  # @option options [#<<] :output ($stdout)
+  # @param [#<<] output ($stdout)
   #   The output to print the hexdump to.
   #
   # @yield [index,numeric,printable]
@@ -68,14 +65,11 @@ module Hexdump
   #   the `:output` value does not support the `#<<` method or
   #   the `:base` value was unknown.
   #
-  def self.dump(data,options={},&block)
-    output = (options.delete(:output) || $stdout)
-    dumper = Dumper.new(options)
+  def self.dump(data, output: $stdout, **options,&block)
+    dumper = Dumper.new(**options)
 
-    if block
-      dumper.each(data,&block)
-    else
-      dumper.dump(data,output)
+    if block then dumper.each(data,&block)
+    else          dumper.dump(data,output)
     end
 
     return nil
@@ -84,12 +78,9 @@ module Hexdump
   #
   # Hexdumps the object.
   #
-  # @param [Hash] options
-  #   Additional options.
-  #
   # @see Hexdump.dump
   #
-  def hexdump(options={},&block)
-    Hexdump.dump(self,options,&block)
+  def hexdump(**options,&block)
+    Hexdump.dump(self,**options,&block)
   end
 end

data/lib/hexdump/version.rb

@@ -1,4 +1,4 @@
 module Hexdump
   # hexdump version
-  VERSION = '0.2.4'
+  VERSION = '0.3.0'
 end

data/spec/{extensions_spec.rb → core_ext_spec.rb}

@@ -1,7 +1,7 @@
 require 'spec_helper'
-require 'hexdump/extensions'
+require 'hexdump/core_ext'
 
-describe "Hexdump extensions" do
+describe "Hexdump core_ext" do
   it "should include Hexdump into String" do
     expect(String).to include(Hexdump)
   end

data/spec/dumper_spec.rb

@@ -1,5 +1,4 @@
 require 'spec_helper'
-
 require 'hexdump/dumper'
 
 describe Hexdump::Dumper do
@@ -11,24 +10,23 @@ describe Hexdump::Dumper do
   let(:print_chars) { ['h', 'e', 'l', 'l', 'o'] }
   let(:data) { print_chars.join }
 
-  it "should only accept known :base values" do
-    expect {
-      described_class.new(data, :base => :foo)
-    }.to raise_error(ArgumentError)
-  end
+  describe "#initialize" do
+    it "should only accept known base: values" do
+      expect {
+        described_class.new(data, base: :foo)
+      }.to raise_error(ArgumentError)
+    end
 
-  it "should only accept known :endian values" do
-    expect {
-      described_class.new(data, :endian => :foo)
-    }.to raise_error(ArgumentError)
+    it "should only accept known endian: values" do
+      expect {
+        described_class.new(data, endian: :foo)
+      }.to raise_error(ArgumentError)
+    end
   end
 
   describe "each_word" do
     let(:data) { 'ABAB' }
     let(:bytes) { [0x41, 0x42, 0x41, 0x42] }
-    let(:shorts_le) { [0x4241, 0x4241] }
-    let(:shorts_be) { [0x4142, 0x4142] }
-    let(:custom_words) { [0x414241, 0x42] }
 
     it "should check if the data defines '#each_byte'" do
       expect {
@@ -40,22 +38,34 @@ describe Hexdump::Dumper do
       expect(subject.each_word(data).to_a).to be == bytes
     end
 
-    it "should allow iterating over custom word-sizes" do
-      dumper = described_class.new(:word_size => 3)
+    context "when initialized with a custom word_size:" do
+      subject { described_class.new(word_size: 3) }
 
-      expect(dumper.each_word(data).to_a).to be == custom_words
+      let(:custom_words) { [0x414241, 0x42] }
+
+      it "should allow iterating over custom word-sizes" do
+        expect(subject.each_word(data).to_a).to be == custom_words
+      end
     end
 
-    it "should iterate over little-endian words by default" do
-      dumper = described_class.new(:word_size => 2)
+    context "when initialized with default endian:" do
+      subject { described_class.new(word_size: 2) }
 
-      expect(dumper.each_word(data).to_a).to be == shorts_le
+      let(:shorts_le) { [0x4241, 0x4241] }
+
+      it "should iterate over little-endian words by default" do
+        expect(subject.each_word(data).to_a).to be == shorts_le
+      end
     end
 
-    it "should iterate over big-endian words" do
-      dumper = described_class.new(:word_size => 2, :endian => :big)
+    context "when initialized with endian: :big" do
+      subject { described_class.new(word_size: 2, endian: :big) }
+
+      let(:shorts_be) { [0x4142, 0x4142] }
 
-      expect(dumper.each_word(data).to_a).to be == shorts_be
+      it "should iterate over big-endian words" do
+        expect(subject.each_word(data).to_a).to be == shorts_be
+      end
     end
   end
 
@@ -74,72 +84,86 @@ describe Hexdump::Dumper do
     end
 
     it "should provide the index within the data for each line" do
-      dumper = described_class.new(:width => 10)
       indices = []
 
-      dumper.each('A' * 100) do |index,hex,print|
+      subject.each('A' * (16 * 10)) do |index,hex,print|
         indices << index
       end
 
-      expect(indices).to be == [0, 10, 20, 30, 40, 50, 60, 70, 80, 90]
+      expect(indices).to be == [0, 16, 32, 48, 64, 80, 96, 112, 128, 144]
     end
 
-    it "should allow configuring the width, in bytes, of each line" do
-      dumper = described_class.new(:width => 10)
-      widths = []
+    context "when initialized with a custom wdith:" do
+      let(:width) { 10 }
 
-      dumper.each('A' * 100) do |index,hex,print|
-        widths << hex.length
-      end
+      subject { described_class.new(width: width) }
 
-      expect(widths).to be == ([10] * 10)
-    end
+      it "should change the width, in bytes, of each line" do
+        widths = []
+        count  = 10
 
-    it "should hexdump the remaining bytes" do
-      dumper = described_class.new(:width => 10)
-      chars = (['B'] * 4)
-      string = chars.join
-      leading = ('A' * 100)
-      remainder = nil
+        subject.each('A' * (width * count)) do |index,hex,print|
+          widths << hex.length
+        end
 
-      dumper.each(leading + string) do |index,hex,print|
-        remainder = print
+        expect(widths).to be == ([width] * count)
       end
+    end
+
+    context "when there are leftover bytes" do
+      let(:width) { 10 }
+
+      subject { described_class.new(width: width) }
 
-      expect(remainder).to be == chars
+      let(:chars)   { ['B'] * 4 }
+      let(:string)  { chars.join }
+      let(:leading) { 'A' * 100 }
+
+      it "should hexdump the remaining bytes" do
+        remainder = nil
+
+        subject.each(leading + string) do |index,hex,print|
+          remainder = print
+        end
+
+        expect(remainder).to be == chars
+      end
     end
 
     it "should provide the hexadecimal characters for each line" do
-      dumper = described_class.new(:width => 10)
       chars = []
+      length = (16 * 10)
 
-      dumper.each(data * 100) do |index,hex,print|
+      subject.each(data * length) do |index,hex,print|
         chars += hex
       end
 
-      expect(chars).to be == (hex_chars * 100)
+      expect(chars).to be == (hex_chars * length)
     end
 
-    it "should allow printing ASCII characters in place of hex characters" do
-      dumper = described_class.new(:ascii => true)
-      chars = []
+    context "when initialized with ascii: true" do
+      subject { described_class.new(ascii: true) }
 
-      dumper.each(data) do |index,hex,print|
-        chars += hex
-      end
+      it "should allow printing ASCII characters in place of hex characters" do
+        chars = []
+
+        subject.each(data) do |index,hex,print|
+          chars += hex
+        end
 
-      expect(chars).to be == print_chars
+        expect(chars).to be == print_chars
+      end
     end
 
     it "should provide the print characters for each line" do
-      dumper = described_class.new(:width => 10)
       chars = []
+      length = (16 * 10)
 
-      dumper.each(data * 100) do |index,hex,print|
+      subject.each(data * length) do |index,hex,print|
         chars += print
       end
 
-      expect(chars).to be == (print_chars * 100)
+      expect(chars).to be == (print_chars * length)
     end
 
     it "should map unprintable characters to '.'" do
@@ -153,108 +177,153 @@ describe Hexdump::Dumper do
       expect(chars).to be == (['.'] * unprintable.length)
     end
 
-    it "should support dumping bytes in decimal format" do
-      dumper = described_class.new(:base => :decimal)
-      chars = []
+    context "when initialized with base: :decimal" do
+      subject { described_class.new(base: :decimal) }
 
-      dumper.each(data) do |index,hex,print|
-        chars += hex
-      end
+      it "should support dumping bytes in decimal format" do
+        chars = []
 
-      expect(chars).to be == decimal_chars
+        subject.each(data) do |index,hex,print|
+          chars += hex
+        end
+
+        expect(chars).to be == decimal_chars
+      end
     end
 
-    it "should support dumping bytes in octal format" do
-      dumper = described_class.new(:base => :octal)
-      chars = []
+    context "when initialized with base: :octal" do
+      subject { described_class.new(base: :octal) }
 
-      dumper.each(data) do |index,hex,print|
-        chars += hex
-      end
+      it "should support dumping bytes in octal format" do
+        chars = []
+
+        subject.each(data) do |index,hex,print|
+          chars += hex
+        end
 
-      expect(chars).to be == octal_chars
+        expect(chars).to be == octal_chars
+      end
     end
 
-    it "should support dumping bytes in binary format" do
-      dumper = described_class.new(:base => :binary)
-      chars = []
+    context "when initialized with base: :binary" do
+      subject { described_class.new(base: :binary) }
 
-      dumper.each(data) do |index,hex,print|
-        chars += hex
-      end
+      it "should support dumping bytes in binary format" do
+        chars = []
 
-      expect(chars).to be == binary_chars
+        subject.each(data) do |index,hex,print|
+          chars += hex
+        end
+
+        expect(chars).to be == binary_chars
+      end
     end
 
-    context ":word_size" do
+    context "when initialized with word_size: and endian:" do
       let(:options) { {:word_size => 2, :endian => :little} }
-
       let(:hex_words) { ['6568', '6c6c', '006f'] }
-      let(:decimal_words) { ['25960', '27756', '  111'] }
-      let(:octal_words) { ['062550', '066154', '000157'] }
-      let(:binary_words) { ['0110010101101000', '0110110001101100', '0000000001101111'] }
 
-      it "should dump words in hexadecimal" do
-        dumper = described_class.new(options)
+      subject { described_class.new(**options) }
+
+      it "should dump words in hexadecimal by default" do
         words = []
 
-        dumper.each(data) do |index,hex,print|
+        subject.each(data) do |index,hex,print|
           words += hex
         end
 
         expect(words).to be == hex_words
       end
 
-      it "should dump words in decimal" do
-        dumper = described_class.new(options.merge(:base => :decimal))
-        words = []
+      context "and base: :decimal" do
+        subject { described_class.new(base: :decimal, **options) }
 
-        dumper.each(data) do |index,dec,print|
-          words += dec
-        end
+        let(:decimal_words) { ['25960', '27756', '  111'] }
 
-        expect(words).to be == decimal_words
-      end
+        it "should dump words in decimal" do
+          words = []
 
-      it "should dump words in octal" do
-        dumper = described_class.new(options.merge(:base => :octal))
-        words = []
+          subject.each(data) do |index,dec,print|
+            words += dec
+          end
 
-        dumper.each(data) do |index,oct,print|
-          words += oct
+          expect(words).to be == decimal_words
         end
+      end
+
+      context "and base: :octal" do
+        subject { described_class.new(base: :octal, **options) }
+
+        let(:octal_words) { ['062550', '066154', '000157'] }
+
+        it "should dump words in octal" do
+          words = []
 
-        expect(words).to be == octal_words
+          subject.each(data) do |index,oct,print|
+            words += oct
+          end
+
+          expect(words).to be == octal_words
+        end
       end
 
-      it "should dump words in binary" do
-        dumper = described_class.new(options.merge(:base => :binary))
-        words = []
+      context "and base: :binary" do
+        subject { described_class.new(base: :binary, **options) }
+
+        let(:binary_words) { ['0110010101101000', '0110110001101100', '0000000001101111'] }
+
+        it "should dump words in binary" do
+          words = []
 
-        dumper.each(data) do |index,bin,print|
-          words += bin
+          subject.each(data) do |index,bin,print|
+            words += bin
+          end
+
+          expect(words).to be == binary_words
         end
+      end
+    end
 
-        expect(words).to be == binary_words
+    it "must return the number of bytes read" do
+      length = 100
+      data   = 'A' * length
+
+      expect(subject.each(data) { |index,hex,print| }).to be == length
+    end
+
+    context "when no block is given" do
+      it "must return an Enumerator" do
+        expect(subject.each(data)).to be_kind_of(Enumerator)
       end
     end
   end
 
   describe "#dump" do
-    it "should check if the :output supports the '#<<' method" do
+    it "should check if the output supports the '#<<' method" do
       expect {
         subject.dump(data,Object.new)
       }.to raise_error(ArgumentError)
     end
 
+    let(:index_format) { "%.8x" }
+
     it "should append each line of the hexdump to the output" do
       lines = []
 
       subject.dump(data,lines)
 
-      expect(lines.length).to be(1)
+      expect(lines.length).to be(2)
+      expect(lines[0]).to start_with(index_format % 0)
       expect(lines[0]).to include(hex_chars.join(' '))
-      expect(lines[0]).to include(print_chars.join)
+      expect(lines[0]).to end_with("|#{print_chars.join}|#{$/}")
+    end
+
+    it "must always print the total number of bytes read on the last line" do
+      lines = []
+
+      subject.dump(data,lines)
+
+      expect(lines.last).to start_with(index_format % data.length)
     end
   end
 end