bindata 1.8.3 → 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a1591b7284eb5311a1577007b50506a3169849cc
+  data.tar.gz: a60a5656dcb5586f12bc7fe88e98af7d12652d7a
+SHA512:
+  metadata.gz: 57b52b55ca1ab97820293d9c73b3e085542a955052b64e3873a87e7b8f0fdd84635a33843ad4aeb92dd7b089a7b988e2b9fe236c265189dbe310766811d7c5cc
+  data.tar.gz: 01a0327084e334cd02459daf396253b11f266a3c443dcf3f57e144dea6f653e98e5aa4d03249a8f5794bd867e727df609137b5e7519b400aa00cdec9c2cfc64b

data/.travis.yml

@@ -1,5 +1,5 @@
 language: ruby
 rvm:
-  - 1.8.7
+  - 1.9.3
   - 2.0.0
   - jruby

data/ChangeLog.rdoc

@@ -1,21 +1,12 @@
 = BinData Changelog
 
-== Version 1.8.3 (2014-04-16)
-
-* #eval_parameters can now call private methods.  Requested by Ole Rasmussen.
-* Can now determine state of :onlyif fields.  Requested by Ole Rasmussen.
-* Renamed #offset to #abs_offset for clarity.  #offset is now deprecated.
-* Support :byte_align for fields in structs.  Requested by Igor Yamolov.
-* Added bit fields with dynamic length.  Requested by Jacob Dam.
-
-== Version 1.8.2 (2014-02-02)
-
-* Virtual fields can now have values.
-* Bug fixes.
-
-== Version 1.8.1 (2014-01-15)
+== Version 2.0.0 (2014-02-02)
 
+* Ruby 1.8 now has its own separate branch.
+* Struct now uses symbols for field names instead of strings.
 * Added signed bitfields.  Requested by redood.
+* Virtual fields can now have names.
+* Bug fixes.
 
 == Version 1.8.0 (2014-01-06)
 

data/INSTALL

@@ -1,11 +1,12 @@
-This package is designed to be installed with rubygems.  If you don't
-have rubygems installed on your system, the older setup.rb is
-included as a convenience.
+This package is designed to be installed with rubygems.
 
-  ($ su)
-  # ruby setup.rb
+    $ gem install bindata
 
-This simple step installs bindata under the default location for Ruby
-libraries.  You can also customize the installation by supplying some
-options to setup.rb.
-Try "ruby setup.rb --help".
+If you are using ruby 1.8
+
+    $ gem install bindata -v '~> 1.8.0'
+
+If you are not using rubygems, you may like to install BinData with
+Minero Aoki's setup.rb found at:
+
+    https://github.com/rubyworks/setup

data/NEWS.rdoc

@@ -1,3 +1,22 @@
+= 2.0.0
+
+BinData 2.0.0 requires ruby 1.9 or greater.  Support for ruby 1.8 is found in
+BinData versions 1.8.x.
+
+Prior to version 2.0.0, BinData used the Ruby 1.8 conversion of strings for
+method names.  As of 2.0.0, BinData uses symbols.
+
+    class A < BinData::Record
+      uint8 :a
+      uint8 :b
+    end
+
+    # BinData 1.8.x
+    A.read "\001\002" #=> {"a"=>1, "b"=>2}
+
+    # BinData >= 2.0.0
+    A.read "\001\002" #=> {:a=>1, :b=>2}
+
 = 1.6.0
 
 Added :assert as a replacement for :check_value.  Note that :assert performs

data/README.md

@@ -43,18 +43,14 @@ for dependent and variable length fields is built in.
 
     $ gem install bindata
 
--or-
+or if running ruby 1.8
 
-    $ sudo ruby setup.rb
+    $ gem install bindata -v '~> 1.8.0'
 
 # Documentation
 
 [Read the wiki](http://github.com/dmendel/bindata/wiki).
 
--or-
-
-    $ rake manual
-
 # Contact
 
 If you have any queries / bug reports / suggestions, please contact me

data/Rakefile

@@ -14,5 +14,3 @@ Rake::TestTask.new do |t|
 end
 
 task :default => :test
-
-Dir['tasks/**/*.rake'].each { |t| load t }

data/bindata.gemspec

@@ -19,9 +19,6 @@ Gem::Specification.new do |s|
 
   s.add_development_dependency('rake')
   s.add_development_dependency('minitest', "> 5.0.0")
-  s.add_development_dependency('haml', ["< 4.0.0"])
-  s.add_development_dependency('maruku')
-  s.add_development_dependency('syntax')
   s.description = <<-END.gsub(/^ +/, "")
     BinData is a declarative way to read and write binary file formats.
 

data/examples/gzip.rb

@@ -1,115 +1,65 @@
 require 'bindata'
-require 'forwardable'
+require 'zlib'
 
 # An example of a reader / writer for the GZIP file format as per rfc1952.
-# Note that compression is not implemented to keep the example small.
-class Gzip
-  extend Forwardable
-
-  # Known compression methods
-  DEFLATE = 8
-
-  class Extra < BinData::Record
-    endian :little
-
-    uint16 :len,  :length => lambda { data.length }
-    string :data, :read_length => :len
-  end
-
-  class Header < BinData::Record
-    endian :little
-
-    uint16  :ident,      :asserted_value => 0x8b1f
-    uint8   :compression_method, :initial_value => DEFLATE
-
-    bit3    :freserved,  :asserted_value => 0
-    bit1    :fcomment,   :value => lambda { comment.length > 0 ? 1 : 0 }
-    bit1    :ffile_name, :value => lambda { file_name.length > 0 ? 1 : 0 }
-    bit1    :fextra,     :value => lambda { extra.len > 0 ? 1 : 0 }
-    bit1    :fcrc16,     :value => 0  # see comment below
-    bit1    :ftext
-
-    # Never include header crc.  This is because the current versions of the
-    # command-line version of gzip (up through version 1.3.x) do not
-    # support header crc's, and will report that it is a "multi-part gzip
-    # file" and give up.
-
-    uint32  :mtime
-    uint8   :extra_flags
-    uint8   :os,         :initial_value => 255   # unknown OS
-
-    # These fields are optional depending on the bits in flags
-    extra   :extra,      :onlyif => lambda { fextra.nonzero? }
-    stringz :file_name,  :onlyif => lambda { ffile_name.nonzero? }
-    stringz :comment,    :onlyif => lambda { fcomment.nonzero? }
-    uint16  :crc16,      :onlyif => lambda { fcrc16.nonzero? }
-  end
-
-  class Footer < BinData::Record
-    endian :little
+# See notes at the end of this file for implementation discussions.
+class Gzip < BinData::Record
+  # Binary representation of a ruby Time object
+  class Mtime < BinData::Primitive
+    uint32le :time
+
+    def set(val)
+      self.time = val.to_i
+    end
 
-    uint32 :crc32
-    uint32 :uncompressed_size
+    def get
+      Time.at(time)
+    end
   end
 
-  def initialize
-    @header = Header.new
-    @footer = Footer.new
-  end
+  # Known compression methods
+  DEFLATE = 8
 
-  attr_accessor :compressed
-  def_delegators :@header, :file_name=, :file_name
-  def_delegators :@header, :comment=, :comment, :comment?
-  def_delegators :@header, :compression_method
-  def_delegators :@footer, :crc32, :uncompressed_size
+  endian :little
 
-  def mtime
-    Time.at(@header.mtime.snapshot)
-  end
+  uint16  :ident,      :asserted_value => 0x8b1f
+  uint8   :compression_method, :initial_value => DEFLATE
 
-  def mtime=(tm)
-    @header.mtime = tm.to_i
-  end
+  bit3    :freserved,  :asserted_value => 0
+  bit1    :fcomment,   :value => lambda { comment.length > 0 ? 1 : 0 }
+  bit1    :ffile_name, :value => lambda { file_name.length > 0 ? 1 : 0 }
+  bit1    :fextra,     :value => lambda { extra.len > 0 ? 1 : 0 }
+  bit1    :fcrc16,     :value => 0  # see note at end of file
+  bit1    :ftext
 
-  def total_size
-    @header.num_bytes + @compressed.size + @footer.num_bytes
-  end
+  mtime   :mtime
+  uint8   :extra_flags
+  uint8   :os,         :initial_value => 255   # unknown OS
 
-  def compressed_data
-    @compressed
-  end
+  # The following fields are optional depending on the bits in flags
 
-  def set_compressed_data(compressed, crc32, uncompressed_size)
-    @compressed               = compressed
-    @footer.crc32             = crc32
-    @footer.uncompressed_size = uncompressed_size
+  struct  :extra,      :onlyif => lambda { fextra.nonzero? } do
+    uint16 :len,  :length => lambda { data.length }
+    string :data, :read_length => :len
   end
+  stringz :file_name,  :onlyif => lambda { ffile_name.nonzero? }
+  stringz :comment,    :onlyif => lambda { fcomment.nonzero? }
+  uint16  :crc16,      :onlyif => lambda { fcrc16.nonzero? }
 
-  def read(file_name)
-    File.open(file_name, "r") do |io|
-      @header.read(io)
-
-      # Determine the size of the compressed data.  This is needed because
-      # we don't actually uncompress the data.  Ideally the uncompression
-      # method would read the correct number of bytes from the IO and the
-      # IO would be positioned ready to read the footer.
+  # The length of compressed data must be calculated from the current file offset
+  count_bytes_remaining :bytes_remaining
+  string :compressed_data, :read_length => lambda { bytes_remaining - footer.num_bytes }
 
-      pos = io.pos
-      io.seek(-@footer.num_bytes, IO::SEEK_END)
-      compressed_size = io.pos - pos
-      io.seek(pos)
-
-      @compressed = io.read(compressed_size)
-      @footer.read(io)
-    end
+  struct :footer do
+    uint32 :crc32
+    uint32 :uncompressed_size
   end
 
-  def write(file_name)
-    File.open(file_name, "w") do |io|
-      @header.write(io)
-      io.write(@compressed)
-      @footer.write(io)
-    end
+  def data=(data)
+    # Zlib.deflate includes a header + footer which we must discard
+    self.compressed_data = Zlib::Deflate.deflate(data)[2..-5]
+    self.footer.crc32 = Zlib::crc32(data)
+    self.footer.uncompressed_size = data.size
   end
 end
 
@@ -117,28 +67,30 @@ if __FILE__ == $0
   # Write a gzip file.
   print "Creating a gzip file ... "
   g = Gzip.new
-  # Uncompressed data is "the cat sat on the mat"
-  g.set_compressed_data("+\311HUHN,Q(\006\342\374<\205\022 77\261\004\000",
-                        3464689835, 22)
+  g.data = "the cat sat on the mat"
   g.file_name = "poetry"
   g.mtime = Time.now
   g.comment = "A stunning piece of prose"
-  g.write("poetry.gz")
+  File.open("poetry.gz", "w") do |io|
+    g.write(io)
+  end
   puts "done."
   puts
 
   # Read the created gzip file.
   print "Reading newly created gzip file ... "
   g = Gzip.new
-  g.read("poetry.gz")
+  File.open("poetry.gz", "r") do |io|
+    g.read(io)
+  end
   puts "done."
   puts
 
   puts "Printing gzip file details in the format of gzip -l -v"
 
   # compression ratio
-  ratio = 100.0 * (g.uncompressed_size - g.compressed.size) /
-            g.uncompressed_size
+  ratio = 100.0 * (g.footer.uncompressed_size - g.compressed_data.size) /
+            g.footer.uncompressed_size
 
   comp_meth = (g.compression_method == Gzip::DEFLATE) ? "defla" : ""
 
@@ -146,16 +98,28 @@ if __FILE__ == $0
   puts "method  crc     date  time           compressed        " +
        "uncompressed  ratio uncompressed_name"
   puts "%5s %08x %6s %5s %19s %19s %5.1f%% %s"  % [comp_meth,
-                                                   g.crc32,
+                                                   g.footer.crc32,
                                                    g.mtime.strftime('%b %d'),
                                                    g.mtime.strftime('%H:%M'),
-                                                   g.total_size,
-                                                   g.uncompressed_size,
+                                                   g.num_bytes,
+                                                   g.footer.uncompressed_size,
                                                    ratio,
                                                    g.file_name]
-  puts "Comment: #{g.comment}" if g.comment?
+  puts "Comment: #{g.comment}" if g.comment != ""
   puts
 
   puts "Executing gzip -l -v"
   puts `gzip -l -v poetry.gz`
 end
+
+# Notes:
+#
+# Mtime: A convenience wrapper that allow a ruby Time object to be used instead
+# of manually dealing with the raw form (seconds since 1 Jan 1970)
+#
+# rfc1952 specifies an optional crc16 field.  The gzip command line client
+# uses this field for multi-part gzip.  Hence we ignore this.
+
+# We are cheating and using the Zlib library for compression.  We can't use
+# this library for decompression as zlib requires an adler32 checksum while
+# gzip uses crc32.

data/examples/tcp_ip.rb

@@ -39,8 +39,6 @@ end
 
 # TCP Protocol Data Unit
 class TCP_PDU < BinData::Record
-  mandatory_parameter :packet_length
-
   endian :big
 
   uint16 :src_port
@@ -60,7 +58,7 @@ class TCP_PDU < BinData::Record
   uint16 :checksum
   uint16 :urg_ptr
   string :options, :read_length => :options_length_in_bytes
-  string :payload, :read_length => lambda { packet_length - payload.rel_offset }
+  rest   :payload
 
   def options_length_in_bytes
     (doff - 5 ) * 4
@@ -69,15 +67,13 @@ end
 
 # UDP Protocol Data Unit
 class UDP_PDU < BinData::Record
-  mandatory_parameter :packet_length
-
   endian :big
 
   uint16 :src_port
   uint16 :dst_port
   uint16 :len
   uint16 :checksum
-  string :payload, :read_length => lambda { packet_length - payload.rel_offset }
+  rest   :payload
 end
 
 # IP Protocol Data Unit
@@ -97,10 +93,12 @@ class IP_PDU < BinData::Record
   ip_addr :src_addr
   ip_addr :dest_addr
   string :options, :read_length => :options_length_in_bytes
-  choice :payload, :selection => :protocol do
-    tcp_pdu  6, :packet_length => :payload_length_in_bytes
-    udp_pdu 17, :packet_length => :payload_length_in_bytes
-    string :default, :read_length => :payload_length_in_bytes
+  buffer :payload, :length => :payload_length_in_bytes do
+    choice :payload, :selection => :protocol do
+      tcp_pdu  6
+      udp_pdu 17
+      rest    :default
+    end
   end
 
   def header_length_in_bytes

data/lib/bindata.rb

@@ -1,6 +1,10 @@
 # BinData -- Binary data manipulator.
 # Copyright (c) 2007 - 2014 Dion Mendel.
 
+if RUBY_VERSION <= "1.9"
+  fail "BinData requires ruby >= 1.9.3. Use BinData version 1.8.x instead"
+end
+
 require 'bindata/version'
 require 'bindata/array'
 require 'bindata/bits'

data/lib/bindata/base.rb

@@ -233,17 +233,16 @@ module BinData
       end
     end
 
-    # Returns the offset (in bytes) of this object with respect to its most
-    # distant ancestor.
-    def abs_offset
+    # Returns the offset of this object wrt to its most distant ancestor.
+    def offset
       if @parent
-        @parent.abs_offset + @parent.offset_of(self)
+        @parent.offset + @parent.offset_of(self)
       else
         0
       end
     end
 
-    # Returns the offset (in bytes) of this object with respect to its parent.
+    # Returns the offset of this object wrt to its parent.
     def rel_offset
       if @parent
         @parent.offset_of(self)
@@ -282,11 +281,7 @@ module BinData
     end
 
     def binary_string(str)
-      if str.respond_to?(:force_encoding)
-        str.to_s.dup.force_encoding(Encoding::BINARY)
-      else
-        str.dup
-      end
+      str.to_s.dup.force_encoding(Encoding::BINARY)
     end
   end
 end