jbangert-bindata 1.5.0

data/examples/nbt.rb

@@ -0,0 +1,178 @@
+require 'bindata'
+
+# An example reader for Minecraft's NBT format.
+# http://www.minecraft.net/docs/NBT.txt
+#
+# This is an example of how to write a BinData
+# declaration for a recursively defined file format.
+module Nbt
+
+  TAG_NAMES = {
+     0 => "End",
+     1 => "Byte",
+     2 => "Short",
+     3 => "Int",
+     4 => "Long",
+     5 => "Float",
+     6 => "Double",
+     7 => "Byte_Array",
+     8 => "String",
+     9 => "List",
+    10 => "Compound"
+  }
+
+  # NBT.txt line 25
+  class TagEnd < BinData::Primitive
+    def get; ""; end
+    def set(v); end
+
+    def to_formatted_s(indent = 0); to_s; end
+  end
+
+  # NBT.txt line 31
+  class TagByte < BinData::Int8
+    def to_formatted_s(indent = 0); to_s; end
+  end
+
+  # NBT.txt line 34
+  class TagShort < BinData::Int16be
+    def to_formatted_s(indent = 0); to_s; end
+  end
+
+  # NBT.txt line 37
+  class TagInt < BinData::Int32be
+    def to_formatted_s(indent = 0); to_s; end
+  end
+
+  # NBT.txt line 40
+  class TagLong < BinData::Int64be
+    def to_formatted_s(indent = 0); to_s; end
+  end
+
+  # NBT.txt line 43
+  class TagFloat < BinData::FloatBe
+    def to_formatted_s(indent = 0); to_s; end
+  end
+
+  # NBT.txt line 46
+  class TagDouble < BinData::DoubleBe
+    def to_formatted_s(indent = 0); to_s; end
+  end
+
+  # NBT.txt line 49
+  class TagByteArray < BinData::Record
+    int32be :len, :value => lambda { data.length }
+    string  :data, :read_length => :len
+
+    def to_formatted_s(indent = 0)
+      "[#{len} bytes]"
+    end
+  end
+
+  # NBT.txt line 53
+  class TagString < BinData::Primitive
+    int16be :len, :value => lambda { data.length }
+    string  :data, :read_length => :len
+
+    def get
+      self.data
+    end
+
+    def set(v)
+      self.data = v
+    end
+
+    def to_formatted_s(indent = 0); to_s; end
+  end
+
+  ## Payload is the most important class to understand.
+  ## This abstraction allows recursive formats.
+  ## eg. lists can contain lists can contain lists. 
+
+  # Forward references used by Payload
+  class TagCompound < BinData::Record; end
+  class TagList < BinData::Record; end
+
+  # NBT.txt line 10
+  class Payload < BinData::Choice
+    tag_end        0
+    tag_byte       1
+    tag_short      2
+    tag_int        3
+    tag_long       4
+    tag_float      5
+    tag_double     6
+    tag_byte_array 7
+    tag_string     8
+    tag_list       9
+    tag_compound   10
+  end
+
+  # NBT.txt line 6, 27
+  class NamedTag < BinData::Record
+    int8 :tag_id
+    tag_string :name,    :onlyif => :not_end_tag?
+    payload    :payload, :onlyif => :not_end_tag?, :selection => :tag_id
+
+    def not_end_tag?
+      tag_id != 0
+    end
+
+    def to_formatted_s(indent = 0)
+      "  " * indent +
+      "TAG_#{TAG_NAMES[tag_id]}(\"#{name}\"): " +
+      payload.to_formatted_s(indent) + "\n"
+    end
+  end
+
+  # NBT.txt line 57
+  class TagList < BinData::Record
+    int8 :tag_id
+    int32be :len, :value => lambda { data.length }
+    array :data, :initial_length => :len do
+      payload :selection => :tag_id
+    end
+
+    def to_formatted_s(indent = 0)
+      pre = "  " * indent
+      tag_type = "TAG_#{TAG_NAMES[tag_id]}"
+
+      "#{len} entries of type #{tag_type}\n" +
+      pre + "{\n" + 
+        data.collect { |el| "  #{pre}#{tag_type}: #{el.to_formatted_s(indent + 1)}\n" }.join("") +
+      pre + "}"
+    end
+  end
+
+  # NBT.txt line 63
+  class TagCompound < BinData::Record
+    array :data, :read_until => lambda { element.tag_id == 0 } do
+      named_tag
+    end
+
+    def to_formatted_s(indent = 0)
+      pre = "  " * indent
+      "#{data.length - 1} entries\n" +
+      pre + "{\n" + 
+        data[0..-2].collect { |el| el.to_formatted_s(indent + 1) }.join("") +
+      pre + "}"
+    end
+  end
+
+  # NBT.txt line 3
+  class Nbt < NamedTag
+    def self.read(io)
+      require 'zlib'
+      super(Zlib::GzipReader.new(io))
+    end
+  end
+end
+
+if $0 == __FILE__
+  require 'stringio'
+
+  bigtest_nbt = StringIO.new "\037\213\b\000\000\000\000\000\000\003\355T\317O\032A\024~\302\002\313\226\202\261\304\020c\314\253\265\204\245\333\315B\021\211\261\210\026,\232\r\032\330\2501\206\270+\303\202.\273fw\260\361\324K{lz\353?\323#\177C\317\275\366\277\240\303/{i\317\275\3602\311\367\346\275o\346{o&y\002\004TrO,\016x\313\261M\215x\364\343pb>\b{\035\307\245\223\030\017\202G\335\356\204\002b\265\242\252\307xv\\W\313\250U\017\e\310\326\036j\225\206\206\r\255~X{\217\203\317\203O\203o\317\003\020n[\216>\276\2458Ld\375\020\352\332t\246\#@\334f.i\341\265\323\273s\372v\v)\333\v\340\357\350=\0368[\357\021\bV\365\336]\337\v@\340^\267\372d\267\004\000\214ALs\306\bUL\323 .}\244\300\310\302\020\263\272\336X\vS\243\356D\216E\0030\261'S\214L\361\351\024\243S\214\205\341\331\237\343\263\362D\201\245|3\335\330\273\307\252u\023_(\034\b\327.\321Y?\257\035\e`!Y\337\372\361\005\376\301\316\374\235\275\000\274\361@\311\370\205B@F\376\236\353\352\017\223:h\207`\273\35327\243(\n\216\273\365\320ic\312N\333\351\354\346\346+;\275%\276dI\t=\252\273\224\375\030~\350\322\016\332o\025L\261h>+\341\233\234\204\231\274\204\005\teY\026E\000\377/(\256/\362\302\262\244.\035 wZ;\271\214\312\347)\337QA\311\026\265\305m\241*\255,\3051\177\272z\222\216^\235_\370\022\005#\e\321\366\267w\252\315\225r\274\236\337X]K\227\256\222\027\271D\320\200\310\372>\277\263\334T\313\aun\243\266vY\222\223\251\334QP\231k\3145\346\032\377W#\bB\313\351\e\326x\302\354\376\374z\373}x\323\204\337\324\362\244\373\b\006\000\000"
+
+  nbt = Nbt::Nbt.read(bigtest_nbt)
+  puts nbt.to_formatted_s
+end

data/lib/bindata.rb

@@ -0,0 +1,33 @@
+# BinData -- Binary data manipulator.
+# Copyright (c) 2007 - 2013 Dion Mendel.
+
+require 'bindata/version'
+require 'bindata/array'
+require 'bindata/bits'
+require 'bindata/choice'
+require 'bindata/count_bytes_remaining'
+require 'bindata/float'
+require 'bindata/int'
+require 'bindata/primitive'
+require 'bindata/record'
+require 'bindata/rest'
+require 'bindata/skip'
+require 'bindata/string'
+require 'bindata/stringz'
+require 'bindata/struct'
+require 'bindata/trace'
+require 'bindata/alignment'
+require 'bindata/deprecated'
+
+# = BinData
+# 
+# A declarative way to read and write structured binary data.
+# 
+# A full reference manual is available online at
+# http://bindata.rubyforge.org/manual.html
+#
+# == License
+#
+# BinData is released under the same license as Ruby.
+#
+# Copyright (c) 2007 - 2013 Dion Mendel.

data/lib/bindata/alignment.rb

@@ -0,0 +1,83 @@
+require 'bindata/base_primitive'
+
+module BinData
+  # Resets the stream alignment to the next byte.  This is
+  # only useful when using bit-based primitives.
+  #
+  #    class MyRec < BinData::Record
+  #      bit4 :a
+  #      resume_byte_alignment
+  #      bit4 :b
+  #    end
+  #
+  #    MyRec.read("\x12\x34") #=> {"a" => 1, "b" => 3}
+  #
+  class ResumeByteAlignment < BinData::Base
+    def clear; end
+    def clear?; true; end
+    def assign(val); end
+    def snapshot; nil; end
+    def do_num_bytes; 0; end
+
+    def do_read(io)
+      io.reset_read_bits
+    end
+
+    def do_write(io)
+      io.flushbits
+    end
+  end
+
+  # A monkey patch to force byte-aligned primitives to
+  # become bit-aligned.  This allows them to be used at
+  # non byte based boundaries.
+  #
+  #     class BitString < BinData::String
+  #       bit_aligned
+  #     end
+  #
+  #     class MyRecord < BinData::Record
+  #       bit4       :preamble
+  #       bit_string :str, :length => 2
+  #     end
+  #
+  module BitAligned
+    class BitAlignedIO
+      def initialize(io)
+        @io = io
+      end
+      def readbytes(n)
+        n.times.inject("") do |bytes, i|
+          bytes << @io.readbits(8, :big).chr
+        end
+      end
+      def method_missing(sym, *args, &block)
+        @io.send(sym, *args, &block)
+      end
+    end
+
+    def read_and_return_value(io)
+      super(BitAlignedIO.new(io))
+    end
+
+    def do_num_bytes
+      super.to_f
+    end
+
+    def do_write(io)
+      value_to_binary_string(_value).each_byte { |v| io.writebits(v, 8, :big) }
+    end
+  end
+
+  class BasePrimitive < BinData::Base
+    def self.bit_aligned
+      include BitAligned
+    end
+  end
+
+  class Primitive < BinData::BasePrimitive
+    def self.bit_aligned
+      fail "'bit_aligned' is not needed for BinData::Primitives"
+    end
+  end
+end

data/lib/bindata/array.rb

@@ -0,0 +1,335 @@
+require 'bindata/base'
+require 'bindata/dsl'
+
+module BinData
+  # An Array is a list of data objects of the same type.
+  #
+  #   require 'bindata'
+  #
+  #   data = "\x03\x04\x05\x06\x07\x08\x09"
+  #
+  #   obj = BinData::Array.new(:type => :int8, :initial_length => 6)
+  #   obj.read(data) #=> [3, 4, 5, 6, 7, 8]
+  #
+  #   obj = BinData::Array.new(:type => :int8,
+  #                            :read_until => lambda { index == 1 })
+  #   obj.read(data) #=> [3, 4]
+  #
+  #   obj = BinData::Array.new(:type => :int8,
+  #                            :read_until => lambda { element >= 6 })
+  #   obj.read(data) #=> [3, 4, 5, 6]
+  #
+  #   obj = BinData::Array.new(:type => :int8,
+  #           :read_until => lambda { array[index] + array[index - 1] == 13 })
+  #   obj.read(data) #=> [3, 4, 5, 6, 7]
+  #
+  #   obj = BinData::Array.new(:type => :int8, :read_until => :eof)
+  #   obj.read(data) #=> [3, 4, 5, 6, 7, 8, 9]
+  #
+  # == Parameters
+  #
+  # Parameters may be provided at initialisation to control the behaviour of
+  # an object.  These params are:
+  #
+  # <tt>:type</tt>::           The symbol representing the data type of the
+  #                            array elements.  If the type is to have params
+  #                            passed to it, then it should be provided as
+  #                            <tt>[type_symbol, hash_params]</tt>.
+  # <tt>:initial_length</tt>:: The initial length of the array.
+  # <tt>:read_until</tt>::     While reading, elements are read until this
+  #                            condition is true.  This is typically used to
+  #                            read an array until a sentinel value is found.
+  #                            The variables +index+, +element+ and +array+
+  #                            are made available to any lambda assigned to
+  #                            this parameter.  If the value of this parameter
+  #                            is the symbol :eof, then the array will read
+  #                            as much data from the stream as possible.
+  #
+  # Each data object in an array has the variable +index+ made available
+  # to any lambda evaluated as a parameter of that data object.
+  class Array < BinData::Base
+    include DSLMixin
+    include Enumerable
+
+    dsl_parser :array
+
+    mandatory_parameter :type
+    optional_parameters :initial_length, :read_until
+    mutually_exclusive_parameters :initial_length, :read_until
+
+    class << self
+
+      def sanitize_parameters!(params) #:nodoc:
+        unless params.has_parameter?(:initial_length) or
+                 params.has_parameter?(:read_until)
+          # ensure one of :initial_length and :read_until exists
+          params[:initial_length] = 0
+        end
+
+        params.warn_replacement_parameter(:read_length, :initial_length)
+
+        params.merge!(dsl_params)
+
+        if params.needs_sanitizing?(:type)
+          el_type, el_params = params[:type]
+          params[:type] = params.create_sanitized_object_prototype(el_type, el_params)
+        end
+      end
+    end
+
+    def initialize_shared_instance
+      @element_prototype = get_parameter(:type)
+    end
+
+    def initialize_instance
+      @element_list = nil
+    end
+
+    def clear?
+      @element_list.nil? or elements.all? { |el| el.clear? }
+    end
+
+    def clear
+      initialize_instance
+    end
+
+    def assign(array)
+      raise ArgumentError, "can't set a nil value for #{debug_name}" if array.nil?
+
+      @element_list = to_storage_formats(array.to_ary)
+    end
+
+    def snapshot
+      elements.collect { |el| el.snapshot }
+    end
+
+    def find_index(obj)
+      elements.index(obj)
+    end
+    alias_method :index, :find_index
+
+    # Returns the first index of +obj+ in self.
+    #
+    # Uses equal? for the comparator.
+    def find_index_of(obj)
+      elements.index { |el| el.equal?(obj) }
+    end
+
+    def push(*args)
+      insert(-1, *args)
+      self
+    end
+    alias_method :<<, :push
+
+    def unshift(*args)
+      insert(0, *args)
+      self
+    end
+
+    def concat(array)
+      insert(-1, *array.to_ary)
+      self
+    end
+
+    def insert(index, *objs)
+      extend_array(index - 1)
+      elements.insert(index, *to_storage_formats(objs))
+      self
+    end
+
+    # Returns the element at +index+.
+    def [](arg1, arg2 = nil)
+      if arg1.respond_to?(:to_int) and arg2.nil?
+        slice_index(arg1.to_int)
+      elsif arg1.respond_to?(:to_int) and arg2.respond_to?(:to_int)
+        slice_start_length(arg1.to_int, arg2.to_int)
+      elsif arg1.is_a?(Range) and arg2.nil?
+        slice_range(arg1)
+      else
+        raise TypeError, "can't convert #{arg1} into Integer" unless arg1.respond_to?(:to_int)
+        raise TypeError, "can't convert #{arg2} into Integer" unless arg2.respond_to?(:to_int)
+      end
+    end
+    alias_method :slice, :[]
+
+    def slice_index(index)
+      extend_array(index)
+      at(index)
+    end
+
+    def slice_start_length(start, length)
+      elements[start, length]
+    end
+
+    def slice_range(range)
+      elements[range]
+    end
+    private :slice_index, :slice_start_length, :slice_range
+
+    # Returns the element at +index+.  Unlike +slice+, if +index+ is out
+    # of range the array will not be automatically extended.
+    def at(index)
+      elements[index]
+    end
+
+    # Sets the element at +index+.
+    def []=(index, value)
+      extend_array(index)
+      elements[index].assign(value)
+    end
+
+    # Returns the first element, or the first +n+ elements, of the array.
+    # If the array is empty, the first form returns nil, and the second
+    # form returns an empty array.
+    def first(n = nil)
+      if n.nil? and empty?
+        # explicitly return nil as arrays grow automatically
+        nil
+      elsif n.nil?
+        self[0]
+      else
+        self[0, n]
+      end
+    end
+
+    # Returns the last element, or the last +n+ elements, of the array.
+    # If the array is empty, the first form returns nil, and the second
+    # form returns an empty array.
+    def last(n = nil)
+      if n.nil?
+        self[-1]
+      else
+        n = length if n > length
+        self[-n, n]
+      end
+    end
+
+    def length
+      elements.length
+    end
+    alias_method :size, :length
+
+    def empty?
+      length.zero?
+    end
+
+    # Allow this object to be used in array context.
+    def to_ary
+      collect { |el| el }
+    end
+
+    def each
+      elements.each { |el| yield el }
+    end
+
+    def debug_name_of(child) #:nodoc:
+      index = find_index_of(child)
+      "#{debug_name}[#{index}]"
+    end
+
+    def offset_of(child) #:nodoc:
+      index = find_index_of(child)
+      sum = sum_num_bytes_below_index(index)
+
+      child.do_num_bytes.is_a?(Integer) ? sum.ceil : sum.floor
+    end
+
+    def do_read(io) #:nodoc:
+      if has_parameter?(:initial_length)
+        elements.each { |el| el.do_read(io) }
+      elsif has_parameter?(:read_until)
+        read_until(io)
+      end
+    end
+
+    def do_write(io) #:nodoc:
+      elements.each { |el| el.do_write(io) }
+    end
+
+    def do_num_bytes #:nodoc:
+      sum_num_bytes_for_all_elements
+    end
+
+    #---------------
+    private
+
+    def extend_array(max_index)
+      max_length = max_index + 1
+      while elements.length < max_length
+        append_new_element
+      end
+    end
+
+    def to_storage_formats(els)
+      els.collect { |el| new_element(el) }
+    end
+
+    def read_until(io)
+      if get_parameter(:read_until) == :eof
+        read_until_eof(io)
+      else
+        read_until_condition(io)
+      end
+    end
+
+    def read_until_eof(io)
+      loop do
+        element = append_new_element
+        begin
+          element.do_read(io)
+        rescue EOFError, IOError
+          elements.pop
+          break
+        end
+      end
+    end
+
+    def read_until_condition(io)
+      loop do
+        element = append_new_element
+        element.do_read(io)
+        variables = { :index => self.length - 1, :element => self.last,
+                      :array => self }
+        break if eval_parameter(:read_until, variables)
+      end
+    end
+
+    def elements
+      if @element_list.nil?
+        @element_list = []
+        if has_parameter?(:initial_length)
+          eval_parameter(:initial_length).times do
+            @element_list << new_element
+          end
+        end
+      end
+      @element_list
+    end
+
+    def append_new_element
+      element = new_element
+      elements << element
+      element
+    end
+
+    def new_element(value = nil)
+      @element_prototype.instantiate(value, self)
+    end
+
+    def sum_num_bytes_for_all_elements
+      sum_num_bytes_below_index(length)
+    end
+
+    def sum_num_bytes_below_index(index)
+      (0...index).inject(0) do |sum, i|
+        nbytes = elements[i].do_num_bytes
+
+        if nbytes.is_a?(Integer)
+          sum.ceil + nbytes
+        else
+          sum + nbytes
+        end
+      end
+    end
+  end
+end