kaitai-struct 0.3 → 0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b07542b0b53559b463ae219d91b5132ae32443f1
-  data.tar.gz: 70117ba80efbb033f7ab465e4226b42a3c4eb238
+  metadata.gz: 023b59d1105bf10850106f5bf1ace310c9d532b7
+  data.tar.gz: 1ad3a5d47c5ce5be18b79bfbcd9910b1f0d9ed7b
 SHA512:
-  metadata.gz: 902540aad3e004cfae1a1771b462c85bbfdcdc87d0dbbe2b05d3d08fd5277d2d539eb0ed0c8cf788eac4f44afda293af5b6a624f3d47161100f67ba01343716c
-  data.tar.gz: 25fb636cef7318d76d5139e255b81a9ee4caa78f9a4b440bb4dda437e05720ca0d919bc6bcc97ea93c31952dd3447989e0cc3af72357e8fc5c6bf0e3da8f205b
+  metadata.gz: 5d5b1a4726c8c5c010baaca1cb771daf32762b84fd77cf408b91ebadd6e6a865d3fba69b32deb9618a3463e6c68789c2e9ec7cc401524939c729ab519b832457
+  data.tar.gz: 0a3dc2c987d2a327bae5b0ecff06bde62c6039df1180416aad5f4d966fab8d618b0462f29d3f64e7858caee032b7c64f572b6a4579d74eaf461f89830c7f3d54

data/lib/kaitai/struct/struct.rb

@@ -3,8 +3,13 @@ require 'stringio'
 module Kaitai
 module Struct
 
-VERSION = '0.3'
+VERSION = '0.4'
 
+##
+# Common base class for all structured generated by Kaitai Struct.
+# Stores stream object that this object was parsed from in {#_io},
+# stores reference to parent structure in {#_parent} and root
+# structure in {#_root} and provides a few helper methods.
 class Struct
 
   def initialize(_io, _parent = nil, _root = self)
@@ -13,14 +18,67 @@ class Struct
     @_root = _root
   end
 
+  ##
+  # Factory method to instantiate a Kaitai Struct-powered structure,
+  # parsing it from a local file with a given filename.
+  # @param filename [String] local file to parse
   def self.from_file(filename)
     self.new(Stream.open(filename))
   end
 
-  attr_reader :_io
+  ##
+  # Implementation of {Object#inspect} to aid debugging (at the very
+  # least, to aid exception raising) for KS-based classes. This one
+  # uses a bit terser syntax than Ruby's default one, purposely skips
+  # any internal fields (i.e. starting with `_`, such as `_io`,
+  # `_parent` and `_root`) to reduce confusion, and does no
+  # recursivity tracking (as proper general-purpose `inspect`
+  # implementation should do) because there are no endless recursion
+  # in KS-based classes by design (except for already mentioned
+  # internal navigation variables).
+  def inspect
+    vars = []
+    instance_variables.each { |nsym|
+      nstr = nsym.to_s
+
+      # skip all internal variables
+      next if nstr[0..1] == '@_'
+
+      # strip mandatory `@` at the beginning of the name for brevity
+      nstr = nstr[1..-1]
+
+      nvalue = instance_variable_get(nsym).inspect
+
+      vars << "#{nstr}=#{nvalue}"
+    }
+
+    "#{self.class}(#{vars.join(' ')})"
+  end
+
+  attr_reader :_io, :_parent, :_root
 end
 
+##
+# Kaitai::Stream is an implementation of
+# {https://github.com/kaitai-io/kaitai_struct/wiki/Kaitai-Struct-stream-API
+# Kaitai Struct stream API} for Ruby. It's implemented as a wrapper
+# for generic IO objects.
+#
+# It provides a wide variety of simple methods to read (parse) binary
+# representations of primitive types, such as integer and floating
+# point numbers, byte arrays and strings, and also provides stream
+# positioning / navigation methods with unified cross-language and
+# cross-toolkit semantics.
+#
+# Typically, end users won't access Kaitai Stream class manually, but
+# would describe a binary structure format using .ksy language and
+# then would use Kaitai Struct compiler to generate source code in
+# desired target language.  That code, in turn, would use this class
+# and API to do the actual parsing job.
 class Stream
+  ##
+  # Exception class for an error that occurs when some fixed content
+  # was expected to appear, but actual data read was different.
   class UnexpectedDataError < Exception
     def initialize(actual, expected)
       super("Unexpected fixed contents: got #{Stream.format_hex(actual)}, was waiting for #{Stream.format_hex(expected)}")
@@ -29,6 +87,10 @@ class Stream
     end
   end
 
+  ##
+  # Constructs new Kaitai Stream object.
+  # @param arg [String, IO] if String, it will be used as byte array to read data from;
+  #   if IO, if will be used literally as source of data
   def initialize(arg)
     if arg.is_a?(String)
       @_io = StringIO.new(arg)
@@ -39,57 +101,109 @@ class Stream
     end
   end
 
+  ##
+  # Convenience method to create a Kaitai Stream object, opening a
+  # local file with a given filename.
+  # @param filename [String] local file to open
   def self.open(filename)
     self.new(File.open(filename, 'rb:ASCII-8BIT'))
   end
 
+  # Test endianness of the platform
+  @@big_endian = [0x0102].pack('s') == [0x0102].pack('n')
+
   # ========================================================================
-  # Forwarding of IO API calls
+  # Stream positioning
   # ========================================================================
 
+  ##
+  # Check if stream pointer is at the end of stream.
+  # @return [true, false] true if we are located at the end of the stream
   def eof?; @_io.eof?; end
+
+  ##
+  # Set stream pointer to designated position.
+  # @param x [Fixnum] new position (offset in bytes from the beginning of the stream)
   def seek(x); @_io.seek(x); end
-  def pos; @_io.pos; end
 
-  # Test endianness of the platform
-  @@big_endian = [0x0102].pack('s') == [0x0102].pack('n')
+  ##
+  # Get current position of a stream pointer.
+  # @return [Fixnum] pointer position, number of bytes from the beginning of the stream
+  def pos; @_io.pos; end
 
-  def ensure_fixed_contents(size, expected)
-    buf = @_io.read(size)
-    actual = buf.bytes
-    if actual != expected
-      raise UnexpectedDataError.new(actual, expected)
-    end
-    buf
-  end
+  ##
+  # Get total size of the stream in bytes.
+  # @return [Fixnum] size of the stream in bytes
+  def size; @_io.size; end
 
   # ========================================================================
-  # Unsigned
+  # Integer numbers
   # ========================================================================
 
-  def read_u1
-    read_bytes(1).unpack('C')[0]
+  # ------------------------------------------------------------------------
+  # Signed
+  # ------------------------------------------------------------------------
+
+  def read_s1
+    read_bytes(1).unpack('c')[0]
   end
 
-  def read_u2le
-    read_bytes(2).unpack('v')[0]
+  # ........................................................................
+  # Big-endian
+  # ........................................................................
+
+  def read_s2be
+    to_signed(read_u2be, SIGN_MASK_16)
   end
 
-  def read_u4le
-    read_bytes(4).unpack('V')[0]
+  def read_s4be
+    to_signed(read_u4be, SIGN_MASK_32)
+  end
+
+  if @@big_endian
+    def read_s8be
+      read_bytes(8).unpack('q')[0]
+    end
+  else
+    def read_s8be
+      to_signed(read_u8be, SIGN_MASK_64)
+    end
+  end
+
+  # ........................................................................
+  # Little-endian
+  # ........................................................................
+
+  def read_s2le
+    to_signed(read_u2le, SIGN_MASK_16)
+  end
+
+  def read_s4le
+    to_signed(read_u4le, SIGN_MASK_32)
   end
 
   unless @@big_endian
-    def read_u8le
-      read_bytes(8).unpack('Q')[0]
+    def read_s8le
+      read_bytes(8).unpack('q')[0]
     end
   else
-    def read_u8le
-      a, b = read_bytes(8).unpack('VV')
-      (b << 32) + a
+    def read_s8le
+      to_signed(read_u8le, SIGN_MASK_64)
     end
   end
 
+  # ------------------------------------------------------------------------
+  # Unsigned
+  # ------------------------------------------------------------------------
+
+  def read_u1
+    read_bytes(1).unpack('C')[0]
+  end
+
+  # ........................................................................
+  # Big-endian
+  # ........................................................................
+
   def read_u2be
     read_bytes(2).unpack('n')[0]
   end
@@ -109,56 +223,67 @@ class Stream
     end
   end
 
-  # ========================================================================
-  # Signed
-  # ========================================================================
-
-  def read_s1
-    read_bytes(1).unpack('c')[0]
-  end
+  # ........................................................................
+  # Little-endian
+  # ........................................................................
 
-  def read_s2le
-    to_signed(read_u2le, SIGN_MASK_16)
+  def read_u2le
+    read_bytes(2).unpack('v')[0]
   end
 
-  def read_s4le
-    to_signed(read_u4le, SIGN_MASK_32)
+  def read_u4le
+    read_bytes(4).unpack('V')[0]
   end
 
   unless @@big_endian
-    def read_s8le
-      read_bytes(8).unpack('q')[0]
+    def read_u8le
+      read_bytes(8).unpack('Q')[0]
     end
   else
-    def read_s8le
-      to_signed(read_u8le, SIGN_MASK_64)
+    def read_u8le
+      a, b = read_bytes(8).unpack('VV')
+      (b << 32) + a
     end
   end
 
-  def read_s2be
-    to_signed(read_u2be, SIGN_MASK_16)
-  end
+  # ========================================================================
+  # Floating point numbers
+  # ========================================================================
 
-  def read_s4be
-    to_signed(read_u4be, SIGN_MASK_32)
+  # ------------------------------------------------------------------------
+  # Big-endian
+  # ------------------------------------------------------------------------
+
+  def read_f4be
+    read_bytes(4).unpack('g')[0]
   end
 
-  if @@big_endian
-    def read_s8be
-      read_bytes(8).unpack('q')[0]
-    end
-  else
-    def read_s8be
-      to_signed(read_u8be, SIGN_MASK_64)
-    end
+  def read_f8be
+    read_bytes(8).unpack('G')[0]
   end
 
-  # ========================================================================
+  # ------------------------------------------------------------------------
+  # Little-endian
+  # ------------------------------------------------------------------------
 
-  def read_bytes_full
-    @_io.read
+  def read_f4le
+    read_bytes(4).unpack('e')[0]
+  end
+
+  def read_f8le
+    read_bytes(8).unpack('E')[0]
   end
 
+  # ========================================================================
+  # Byte arrays
+  # ========================================================================
+
+  ##
+  # Reads designated number of bytes from the stream.
+  # @param n [Fixnum] number of bytes to read
+  # @return [String] read bytes as byte array
+  # @raise [EOFError] if there were less bytes than requested
+  #   available in the stream
   def read_bytes(n)
     r = @_io.read(n)
     if r
@@ -170,6 +295,33 @@ class Stream
     r
   end
 
+  ##
+  # Reads all the remaining bytes in a stream as byte array.
+  # @return [String] all remaining bytes in a stream as byte array
+  def read_bytes_full
+    @_io.read
+  end
+
+  ##
+  # Reads next len bytes from the stream and ensures that they match
+  # expected fixed byte array. If they differ, throws a
+  # {UnexpectedDataError} runtime exception.
+  # @param len [Fixnum] number of bytes to read
+  # @param expected [String] contents to be expected
+  # @return [String] read bytes as byte array, which are guaranteed to
+  #   equal to expected
+  # @raise [UnexpectedDataError]
+  def ensure_fixed_contents(len, expected)
+    buf = @_io.read(len)
+    actual = buf.bytes
+    if actual != expected
+      raise UnexpectedDataError.new(actual, expected)
+    end
+    buf
+  end
+
+  # ========================================================================
+  # Strings
   # ========================================================================
 
   def read_str_eos(encoding)
@@ -201,7 +353,47 @@ class Stream
   end
 
   # ========================================================================
+  # Byte array processing
+  # ========================================================================
+
+  ##
+  # Performs a XOR processing with given data, XORing every byte of
+  # input with a single given value.
+  # @param data [String] data to process
+  # @param key [Fixnum] value to XOR with
+  # @return [String] processed data
+  def process_xor_one(data, key)
+    data.bytes.map { |x| x ^ key }.pack('C*')
+  end
+
+  ##
+  # Performs a XOR processing with given data, XORing every byte of
+  # input with a key array, repeating key array many times, if
+  # necessary (i.e. if data array is longer than key array).
+  # @param data [String] data to process
+  # @param key [String] array of bytes to XOR with
+  # @return [String] processed data
+  def process_xor_many(data, key)
+    kb = key.bytes
+    kl = kb.size
+    ki = 0
+    data.bytes.map { |x|
+      r = x ^ kb[ki]
+      ki += 1
+      ki = 0 if ki >= kl
+      r
+    }.pack('C*')
+  end
 
+  ##
+  # Performs a circular left rotation shift for a given buffer by a
+  # given amount of bits, using groups of groupSize bytes each
+  # time. Right circular rotation should be performed using this
+  # procedure with corrected amount.
+  # @param data [String] source data to process
+  # @param amount [Fixnum] number of bits to shift by
+  # @param group_size [Fixnum] number of bytes per group to shift
+  # @return [String] copy of source array with requested shift applied
   def process_rotate_left(data, amount, group_size)
     raise NotImplementedError.new("unable to rotate group #{group_size} bytes yet") unless group_size == 1
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kaitai-struct
 version: !ruby/object:Gem::Version
-  version: '0.3'
+  version: '0.4'
 platform: ruby
 authors:
 - Mikhail Yakshin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-19 00:00:00.000000000 Z
+date: 2016-08-09 00:00:00.000000000 Z
 dependencies: []
 description: |
   Kaitai Struct is a declarative language used for describe various binary data structures, laid out in files or in memory: i.e. binary file formats, network stream packet formats, etc.