kaitai-struct 0.7 → 0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: f864fb7a549cb0ffb83d39e1e1a8f3e58feba59b
-  data.tar.gz: f398b795f794ac82e4ab78838dc4f7eb1f773cbe
+SHA256:
+  metadata.gz: cbdd2b873476556b609d64f78e10c3ef35ea5ede048ac5ee57a03a24f523bfac
+  data.tar.gz: db41f46711b11efcf12a982e282181ae20d25831f408b7a3e7e668791f14701b
 SHA512:
-  metadata.gz: 9682c42a2b4636b58255f6b0ed111ba399e182e34269515707471206ae217bd72e26c336749b7737a3c5fa6a9b48eb640cfe0a21bfb4db464420797ef3dce7fb
-  data.tar.gz: 1d6cf8627185ada694d03f2303259f21341f34e4091197907bcc9397b703dc7ba232c7fa36d5bd1244f707ba0dcb2ce1a7a690df65fa8a8fe599ffd5814d6510
+  metadata.gz: ea4b2780d4efa7c645175957059073f6506ee5e39d2525b62f7a5de41816d0115dde2980948ab47e8994b1a7fc97cb94e8fab7692882244fc7d9b58b18b3e8b3
+  data.tar.gz: 99cec16629be56c07b1df24f4a091fbffdd6240341dc0130ef6a5d04195a91c37d6238c4991ba3782667514cf25ae7746aa2fdd3aa307c34352c0dd0698ea4c9

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2015-2022 Kaitai Project
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,5 +1,8 @@
 # Kaitai Struct: runtime library for Ruby
 
+[![Gem version](https://img.shields.io/gem/v/kaitai-struct)](https://rubygems.org/gems/kaitai-struct/)
+[![Gem downloads](https://img.shields.io/gem/dt/kaitai-struct)](https://rubygems.org/gems/kaitai-struct/#:~:text=TOTAL%20DOWNLOADS)
+
 This library implements Kaitai Struct API for Ruby.
 
 Kaitai Struct is a declarative language used for describe various binary
@@ -35,30 +38,7 @@ to install this runtime library.
 
 ### Manually
 
-This library is intentionally kept as very simple, one-file `.rb`
-file. One can just copy it to your project from this
-repository. Usually you won't `require` it directly, it will be loaded
-by Ruby source code generate by Kaitai Struct compiler.
-
-## Licensing
-
-Copyright 2015-2017 Kaitai Project: MIT license
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+This library is intentionally kept as very simple, one `.rb` file.
+You can just copy it to your project from [this repository](https://github.com/kaitai-io/kaitai_struct_ruby_runtime).
+Usually you won't `require` it directly, it will be loaded
+by Ruby source code generated by Kaitai Struct compiler.

data/lib/kaitai/struct/struct.rb

@@ -3,7 +3,7 @@ require 'stringio'
 module Kaitai
 module Struct
 
-VERSION = '0.7'
+VERSION = '0.10'
 
 ##
 # Common base class for all structured generated by Kaitai Struct.
@@ -60,9 +60,8 @@ end
 
 ##
 # Kaitai::Struct::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.
+# {Kaitai Stream API}[https://doc.kaitai.io/stream_api.html] 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
@@ -77,6 +76,9 @@ end
 # and API to do the actual parsing job.
 class Stream
   ##
+  # Unused since Kaitai Struct Compiler v0.9+ - compatibility with
+  # older versions.
+  #
   # Exception class for an error that occurs when some fixed content
   # was expected to appear, but actual data read was different.
   class UnexpectedDataError < Exception
@@ -87,6 +89,7 @@ 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;
@@ -110,6 +113,12 @@ class Stream
     self.new(File.open(filename, 'rb:ASCII-8BIT'))
   end
 
+  ##
+  # Closes underlying IO object.
+  def close
+    @_io.close
+  end
+
   # Test endianness of the platform
   @@big_endian = [0x0102].pack('s') == [0x0102].pack('n')
 
@@ -118,7 +127,7 @@ class Stream
   ##
   # 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
+  def eof?; @_io.eof? and @bits_left == 0; end
 
   ##
   # Set stream pointer to designated position.
@@ -282,36 +291,72 @@ class Stream
     @bits = 0
   end
 
-  def read_bits_int(n)
+  def read_bits_int_be(n)
+    res = 0
+
     bits_needed = n - @bits_left
+    @bits_left = -bits_needed % 8
+
     if bits_needed > 0
       # 1 bit  => 1 byte
       # 8 bits => 1 byte
       # 9 bits => 2 bytes
-      bytes_needed = ((bits_needed - 1) / 8) + 1
+      bytes_needed = ((bits_needed - 1) / 8) + 1 # `ceil(bits_needed / 8)`
       buf = read_bytes(bytes_needed)
       buf.each_byte { |byte|
-        @bits <<= 8
-        @bits |= byte
-        @bits_left += 8
+        res = res << 8 | byte
       }
+
+      new_bits = res
+      res = res >> @bits_left | @bits << bits_needed
+      @bits = new_bits # will be masked at the end of the function
+    else
+      res = @bits >> -bits_needed # shift unneeded bits out
     end
 
-    # raw mask with required number of 1s, starting from lowest bit
-    mask = (1 << n) - 1
-    # shift mask to align with highest bits available in @bits
-    shift_bits = @bits_left - n
-    mask <<= shift_bits
-    # derive reading result
-    res = (@bits & mask) >> shift_bits
-    # clear top bits that we've just read => AND with 1s
-    @bits_left -= n
-    mask = (1 << @bits_left) - 1
+    mask = (1 << @bits_left) - 1 # `@bits_left` is in range 0..7
     @bits &= mask
 
     res
   end
 
+  # Unused since Kaitai Struct Compiler v0.9+ - compatibility with
+  # older versions.
+  def read_bits_int(n)
+    read_bits_int_be(n)
+  end
+
+  def read_bits_int_le(n)
+    res = 0
+    bits_needed = n - @bits_left
+
+    if bits_needed > 0 then
+      # 1 bit  => 1 byte
+      # 8 bits => 1 byte
+      # 9 bits => 2 bytes
+      bytes_needed = ((bits_needed - 1) / 8) + 1 # `ceil(bits_needed / 8)`
+      buf = read_bytes(bytes_needed)
+      i = 0
+      buf.each_byte { |byte|
+        res |= byte << (i * 8)
+        i += 1
+      }
+
+      new_bits = res >> bits_needed
+      res = res << @bits_left | @bits
+      @bits = new_bits
+    else
+      res = @bits
+      @bits >>= n
+    end
+
+    @bits_left = -bits_needed % 8
+
+    mask = (1 << n) - 1 # no problem with this in Ruby (arbitrary precision integers)
+    res &= mask
+    return res
+  end
+
   # @!endgroup
 
   # @!group Byte arrays
@@ -361,6 +406,9 @@ class Stream
   end
 
   ##
+  # Unused since Kaitai Struct Compiler v0.9+ - compatibility with
+  # older versions.
+  #
   # Reads next len bytes from the stream and ensures that they match
   # expected fixed byte array. If they differ, throws a
   # {UnexpectedDataError} runtime exception.
@@ -377,9 +425,10 @@ class Stream
 
   def self.bytes_strip_right(bytes, pad_byte)
     new_len = bytes.length
-    while bytes.getbyte(new_len - 1) == pad_byte
+    while new_len > 0 and bytes.getbyte(new_len - 1) == pad_byte
       new_len -= 1
     end
+
     bytes[0, new_len]
   end
 
@@ -485,8 +534,124 @@ class Stream
     (x & ~mask) - (x & mask)
   end
 
-  def self.format_hex(arr)
-    arr.unpack('H*')[0].gsub(/(..)/, '\1 ').chop
+  def self.format_hex(bytes)
+    bytes.unpack('H*')[0].gsub(/(..)/, '\1 ').chop
+  end
+
+  ###
+  # Guess if the given args are most likely byte arrays.
+  # <p>
+  # There's no way to know for sure, but {@code Encoding::ASCII_8BIT} is a special encoding that is
+  # usually used for a byte array(/string), not a character string. For those reasons, that encoding
+  # is NOT planned to be allowed for human readable texts by KS in general as well.
+  # </p>
+  # @param args [...] Something to check.
+  # @see <a href="https://ruby-doc.org/core-3.0.0/Encoding.html">Encoding</a>
+  # @see <a href="https://github.com/kaitai-io/kaitai_struct/issues/116">List of supported encodings</a>
+  #
+  def self.is_byte_array?(*args)
+    args.all? { |arg| arg.is_a?(String) and (arg.encoding == Encoding::ASCII_8BIT) }
+  end
+
+  def self.inspect_values(*args)
+    reprs = args.map { |arg|
+      if Stream.is_byte_array?(arg)
+        "[#{Stream.format_hex(arg)}]"
+      else
+        arg.inspect
+      end
+    }
+    reprs.length == 1 ? reprs[0] : reprs
+  end
+end
+
+##
+# Common ancestor for all error originating from Kaitai Struct usage.
+# Stores KSY source path, pointing to an element supposedly guilty of
+# an error.
+class KaitaiStructError < Exception
+  def initialize(msg, src_path)
+    super("#{src_path}: #{msg}")
+    @src_path = src_path
+  end
+end
+
+##
+# Error that occurs when default endianness should be decided with
+# a switch, but nothing matches (although using endianness expression
+# implies that there should be some positive result).
+class UndecidedEndiannessError < KaitaiStructError
+  def initialize(src_path)
+    super("unable to decide on endianness for a type", src_path)
+  end
+end
+
+##
+# Common ancestor for all validation failures. Stores pointer to
+# KaitaiStream IO object which was involved in an error.
+class ValidationFailedError < KaitaiStructError
+  def initialize(msg, io, src_path)
+    super("at pos #{io.pos}: validation failed: #{msg}", src_path)
+    @io = io
+  end
+end
+
+##
+# Signals validation failure: we required "actual" value to be equal to
+# "expected", but it turned out that it's not.
+class ValidationNotEqualError < ValidationFailedError
+  def initialize(expected, actual, io, src_path)
+    expected_repr, actual_repr = Stream.inspect_values(expected, actual)
+    super("not equal, expected #{expected_repr}, but got #{actual_repr}", io, src_path)
+
+    @expected = expected
+    @actual = actual
+  end
+end
+
+##
+# Signals validation failure: we required "actual" value to be greater
+# than or equal to "min", but it turned out that it's not.
+class ValidationLessThanError < ValidationFailedError
+  def initialize(min, actual, io, src_path)
+    min_repr, actual_repr = Stream.inspect_values(min, actual)
+    super("not in range, min #{min_repr}, but got #{actual_repr}", io, src_path)
+    @min = min
+    @actual = actual
+  end
+end
+
+##
+# Signals validation failure: we required "actual" value to be less
+# than or equal to "max", but it turned out that it's not.
+class ValidationGreaterThanError < ValidationFailedError
+  def initialize(max, actual, io, src_path)
+    max_repr, actual_repr = Stream.inspect_values(max, actual)
+    super("not in range, max #{max_repr}, but got #{actual_repr}", io, src_path)
+    @max = max
+    @actual = actual
+  end
+end
+
+##
+# Signals validation failure: we required "actual" value to be any of
+# the given list, but it turned out that it's not.
+class ValidationNotAnyOfError < ValidationFailedError
+  def initialize(actual, io, src_path)
+    actual_repr = Stream.inspect_values(actual)
+    super("not any of the list, got #{actual_repr}", io, src_path)
+    @actual = actual
+  end
+end
+
+##
+# Signals validation failure: we required "actual" value to match
+# the expression, but it turned out that it doesn't.
+class ValidationExprError < ValidationFailedError
+  def initialize(actual, io, src_path)
+    actual_repr = Stream.inspect_values(actual)
+    super("not matching the expression, got #{actual_repr}", io, src_path)
+    @actual = actual
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kaitai-struct
 version: !ruby/object:Gem::Version
-  version: '0.7'
+  version: '0.10'
 platform: ruby
 authors:
 - Mikhail Yakshin
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2017-03-22 00:00:00.000000000 Z
+date: 2022-07-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.
@@ -21,15 +21,17 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
+- LICENSE
 - README.md
-- kaitai-struct.gemspec
 - lib/kaitai/struct/struct.rb
 homepage: http://kaitai.io
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  bug_tracker_uri: https://github.com/kaitai-io/kaitai_struct_ruby_runtime/issues
+  homepage_uri: http://kaitai.io
+  source_code_uri: https://github.com/kaitai-io/kaitai_struct_ruby_runtime
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -44,9 +46,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.2
-signing_key: 
+rubygems_version: 3.3.17
+signing_key:
 specification_version: 4
 summary: 'Kaitai Struct: runtime library for Ruby'
 test_files: []

data/.gitignore

@@ -1 +0,0 @@
-*.gem

data/kaitai-struct.gemspec

@@ -1,31 +0,0 @@
-# -*- encoding: utf-8 -*-
-
-require File.expand_path("../lib/kaitai/struct/struct", __FILE__)
-require 'date'
-
-Gem::Specification.new { |s|
-  s.name = 'kaitai-struct'
-  s.version = Kaitai::Struct::VERSION
-  s.date = Date.today.to_s
-
-  s.authors = ['Mikhail Yakshin']
-  s.email = 'greycat@kaitai.io'
-
-  s.homepage = 'http://kaitai.io'
-  s.summary = 'Kaitai Struct: runtime library for Ruby'
-  s.license = 'MIT'
-  s.description = <<-EOF
-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.
-
-The main idea is that a particular format is described in Kaitai Struct language (.ksy file) and then can be compiled with ksc into source files in one of the supported programming languages. These modules will include a generated code for a parser that can read described data structure from a file / stream and give access to it in a nice, easy-to-comprehend API.
-
-This package provides small runtime library used by code generated by Kaitai Struct compiler.
-EOF
-
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.require_paths = ['lib']
-
-  s.files = `git ls-files`.split("\n")
-  s.executables = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  s.test_files = s.files.grep(%r{^(test|spec|features)/})
-}