memory_io 0.2.0 → 1.0.0

data/lib/memory_io/types/basic/number.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'memory_io/context'
+require 'memory_io/error'
 require 'memory_io/types/type'
 
 module MemoryIO
@@ -8,64 +10,144 @@ module MemoryIO
     module Basic
       # Register numbers to {Types}.
       #
-      # All types registered by this class are assumed as *little endian*.
+      # The byte order is taken from the {MemoryIO::Context} of the stream being
+      # read, so the same type reads correctly from memory of either byte order.
       #
-      # This class registered (un)signed {8, 16, 32, 64)-bit integers and IEEE-754 floating numbers.
+      # This class registered (un)signed (8, 16, 32, 64)-bit integers and IEEE-754 floating numbers.
       class Number
+        # Indicators of the integer widths, by size in bytes.
+        # A single byte has no byte order to indicate.
+        INTEGER_INDICATORS = { 1 => 'C', 2 => 'S', 4 => 'L', 8 => 'Q' }.freeze
+
+        # Indicators of the real widths, by size in bytes and then byte order.
+        #
+        # @example
+        #   # 'e' and 'E' are IEEE-754 single and double precision, little endian.
+        REAL_INDICATORS = { 4 => { little: 'e', big: 'g' }, 8 => { little: 'E', big: 'G' } }.freeze
+
+        # Appended to an integer indicator to fix its byte order.
+        ENDIAN_INDICATORS = { little: '<', big: '>' }.freeze
+
         # @param [Integer] bytes
         #   Bytes.
         # @param [Boolean] signed
         #   Signed or unsigned.
-        # @param [String] pack_str
-        #   The indicator to be passed to +Array#pack+ and +String#unpack+.
-        def initialize(bytes, signed, pack_str)
+        # @param [Boolean] real
+        #   Whether this type holds a real number rather than an integer.
+        def initialize(bytes, signed, real: false)
           @bytes = bytes
           @signed = signed
-          @pack_str = pack_str
+          @real = real
+          @range = value_range unless real
+          @indicators = ENDIAN_INDICATORS.keys.to_h { |e| [e, indicator(e)] }
         end
 
         # @return [Integer]
+        #
+        # @raise [EOFError]
+        #   Fewer than +bytes+ bytes remain in +stream+.
         def read(stream)
-          unpack(stream.read(@bytes))
+          endian = MemoryIO::Context.of(stream).endian
+          unpack(MemoryIO::Util.read_exactly(stream, @bytes), endian)
         end
 
         # @param [Integer] val
+        #
+        # @raise [MemoryIO::ValueOutOfRangeError]
+        #   +val+ doesn't fit in this type, which would otherwise be written truncated.
         def write(stream, val)
-          stream.write(pack(val))
+          endian = MemoryIO::Context.of(stream).endian
+          raise MemoryIO::ValueOutOfRangeError, out_of_range_message(val) if out_of_range?(val, endian)
+
+          stream.write(pack(val, endian))
         end
 
         private
 
-        def unpack(str)
-          val = str.unpack(@pack_str).first
-          val -= (2**(@bytes * 8)) if @signed && val >= (2**(@bytes * 8 - 1))
+        # Anything that isn't a number of the matching kind is left for
+        # +Array#pack+ to reject.
+        #
+        # @return [Boolean]
+        def out_of_range?(val, endian)
+          if @range
+            val.is_a?(Integer) && !@range.cover?(val)
+          else
+            val.is_a?(Numeric) && overflows?(val, endian)
+          end
+        end
+
+        # A finite value that packs to an infinity has exceeded what the type
+        # can represent. Losing precision is inherent to the type and allowed,
+        # as is writing an infinity that was asked for.
+        #
+        # @return [Boolean]
+        def overflows?(val, endian)
+          val.infinite?.nil? && pack(val, endian).unpack1(@indicators[endian]).infinite?
+        end
+
+        # @return [Range]
+        def value_range
+          bits = @bytes * 8
+          @signed ? (-(2**(bits - 1))..((2**(bits - 1)) - 1)) : (0..((2**bits) - 1))
+        end
+
+        # @return [String]
+        def out_of_range_message(val)
+          return format('%s exceeds the range of %d-bit floating number', val, @bytes * 8) unless @range
+
+          format('%s is out of range for %d-bit %s integer (%s..%s)',
+                 hex(val), @bytes * 8, @signed ? 'signed' : 'unsigned',
+                 hex(@range.first), hex(@range.last))
+        end
+
+        # +format+'s '%#x' renders a negative number in two's complement notation.
+        #
+        # @return [String]
+        #
+        # @example
+        #   hex(-128)
+        #   #=> '-0x80'
+        def hex(val)
+          format('%s0x%x', val.negative? ? '-' : '', val.abs)
+        end
+
+        # @return [String]
+        #   The +Array#pack+ indicator of this type in +endian+ byte order.
+        def indicator(endian)
+          return REAL_INDICATORS[@bytes][endian] if @real
+          return INTEGER_INDICATORS[@bytes] if @bytes == 1
+
+          INTEGER_INDICATORS[@bytes] + ENDIAN_INDICATORS[endian]
+        end
+
+        def unpack(str, endian)
+          val = str.unpack1(@indicators[endian])
+          # a real is already signed by its representation
+          return val if @real
+
+          val -= (2**(@bytes * 8)) if @signed && val >= (2**((@bytes * 8) - 1))
           val
         end
 
-        def pack(val)
-          [val].pack(@pack_str)
+        def pack(val, endian)
+          [val].pack(@indicators[endian])
         end
 
         # Register (un)signed n-bits integers.
-        {
-          8 => 'C',
-          16 => 'S',
-          32 => 'I',
-          64 => 'Q'
-        }.each do |t, c|
-          Type.register(Number.new(t / 8, true, c),
+        [8, 16, 32, 64].each do |t|
+          Type.register(Number.new(t / 8, true),
                         alias: [:"basic/s#{t}", :"s#{t}"],
                         doc: "A signed #{t}-bit integer.")
-          Type.register(Number.new(t / 8, false, c),
+          Type.register(Number.new(t / 8, false),
                         alias: [:"basic/u#{t}", :"u#{t}"],
                         doc: "An unsigned #{t}-bit integer.")
         end
 
         # Register floating numbers.
-        Type.register(Number.new(4, false, 'F'),
+        Type.register(Number.new(4, true, real: true),
                       alias: %i[basic/float float],
                       doc: 'IEEE-754 32-bit floating number.')
-        Type.register(Number.new(8, false, 'D'),
+        Type.register(Number.new(8, true, real: true),
                       alias: %i[basic/double double],
                       doc: 'IEEE-754 64-bit floating number.')
       end

data/lib/memory_io/types/clang/c_str.rb

@@ -12,17 +12,31 @@ module MemoryIO
       # A null-terminated string.
       class CStr < Types::Type
 
+        # Number of bytes to fetch at a time while searching for the terminator.
+        CHUNK_SIZE = 1024
+
         # @api private
         #
+        # The terminator is searched for in blocks rather than byte by byte,
+        # and +stream+ is left just after it so the next read starts at the
+        # following string.
+        #
         # @return [String]
         #   String without null byte.
         def self.read(stream)
           ret = +''
           loop do
-            c = stream.read(1)
-            break if c.nil? || c == '' || c == "\x00"
+            chunk = stream.read(CHUNK_SIZE)
+            break if chunk.nil? || chunk.empty?
+
+            terminator = chunk.index("\x00")
+            if terminator
+              ret << chunk[0, terminator]
+              stream.pos -= chunk.size - terminator - 1
+              break
+            end
 
-            ret << c
+            ret << chunk
           end
           ret
         end

data/lib/memory_io/types/cpp/string.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
+require 'memory_io/context'
+require 'memory_io/logger'
 require 'memory_io/types/type'
+require 'memory_io/util'
 
 module MemoryIO
   module Types
@@ -22,9 +25,7 @@ module MemoryIO
         # std::string uses inlined-buffer if string length isn't larger than {LOCAL_CAPACITY}.
         LOCAL_CAPACITY = 15
 
-        attr_reader :data # @return [::String]
-        attr_reader :capacity # @return [Integer]
-        attr_reader :dataplus # @return [Integer]
+        attr_reader :data, :capacity, :dataplus # @return [::String] # @return [Integer] # @return [Integer]
 
         # Instantiate a {CPP::String} object.
         #
@@ -33,6 +34,7 @@ module MemoryIO
         # @param [Integer] dataplus
         #   A pointer.
         def initialize(data, capacity, dataplus)
+          super()
           @data = data
           @capacity = capacity
           @dataplus = dataplus
@@ -51,21 +53,20 @@ module MemoryIO
         # @param [String] str
         def data=(str)
           @data = str
-          warn("Length of str (#{str.size}) is larger than capacity (#{capacity})") if str.size > capacity
+          return unless str.size > capacity
+
+          MemoryIO.logger.warn("Length of str (#{str.size}) is larger than capacity (#{capacity})")
         end
 
         # Custom inspect view.
         #
         # @return [String]
-        #
-        # @todo
-        #   Let it be colorful in pry.
         def inspect
-          format("#<%s @data=%s, @capacity=%d, @dataplus=0x%0#{SIZE_T * 2}x>",
+          format('#<%s @data=%s, @capacity=%d, @dataplus=0x%s>',
                  self.class.name,
                  data.inspect,
                  capacity,
-                 dataplus)
+                 dataplus.to_s(16).rjust(SIZE_T * 2, '0'))
         end
 
         class << self
@@ -73,6 +74,11 @@ module MemoryIO
           #
           # @return [CPP::String]
           #
+          # @raise [EOFError]
+          #   The object is incomplete, or its characters cannot be read from
+          #   where it points. {MemoryIO::IO#read} answers with the objects it
+          #   read in full rather than one that is partly filled in.
+          #
           # @example
           #   # echo '#include <string>\n#include <cstdio>\nint main() {' > a.cpp && \
           #   # echo 'std::string a="abcd"; printf("%p\\n", &a);' >> a.cpp && \
@@ -87,10 +93,11 @@ module MemoryIO
           def read(stream)
             dataplus = read_size_t(stream)
             length = read_size_t(stream)
-            union = stream.read(LOCAL_CAPACITY + 1)
+            union = MemoryIO::Util.read_exactly(stream, LOCAL_CAPACITY + 1)
             if length > LOCAL_CAPACITY
-              capacity = MemoryIO::Util.unpack(union[0, Type::SIZE_T])
-              data = keep_pos(stream, pos: dataplus) { |s| s.read(length) }
+              context = MemoryIO::Context.of(stream)
+              capacity = MemoryIO::Util.unpack(union[0, context.pointer_size], context.endian)
+              data = keep_pos(stream, pos: dataplus) { |s| MemoryIO::Util.read_exactly(s, length) }
             else
               capacity = LOCAL_CAPACITY
               data = union[0, length]
@@ -109,10 +116,10 @@ module MemoryIO
             write_size_t(stream, obj.length)
             pos = stream.pos
             if obj.length > LOCAL_CAPACITY
-              keep_pos(stream, pos: obj.dataplus) { |s| s.write(obj.data + "\x00") }
+              keep_pos(stream, pos: obj.dataplus) { |s| s.write("#{obj.data}\u0000") }
               write_size_t(stream, obj.capacity)
             else
-              stream.write(obj.data + "\x00")
+              stream.write("#{obj.data}\u0000")
             end
             stream.pos = pos + LOCAL_CAPACITY + 1
           end

data/lib/memory_io/types/record.rb

@@ -19,12 +19,14 @@ module MemoryIO
       #
       # @param [Object] object
       # @param [Array<Symbol>] keys
+      # @param [Hash] option
+      #   Extra options.
       #
-      # @option [Thread::Backtrace::Location] caller
-      #   This option should present if and only if +object+ is a subclass of {Types::Type}.
-      # @option [String] doc
-      #   Docstring.
-      #   Automatically parse from caller location if this parameter isn't present.
+      # @option option [Thread::Backtrace::Location] :caller
+      #   This option should be present if and only if +object+ is a subclass of {Types::Type}.
+      # @option option [String] :doc
+      #   Doc-string.
+      #   Automatically parsed from caller location if this option isn't present.
       def initialize(object, keys, option = {})
         @obj = object
         @keys = keys
@@ -60,14 +62,14 @@ module MemoryIO
           str.strip!
           break unless str.start_with?('#')
 
-          strings.unshift(str[2..-1] || '')
+          strings.unshift(str[2..] || '')
         end
         trim_docstring(strings)
       end
 
       def trim_docstring(strings)
         strings = strings.drop_while { |s| s.start_with?('@') }.take_while { |s| !s.start_with?('@') }
-        strings.drop_while(&:empty?).reverse.drop_while(&:empty?).reverse.join("\n") + "\n"
+        "#{strings.drop_while(&:empty?).reverse.drop_while(&:empty?).reverse.join("\n")}\n"
       end
     end
   end

data/lib/memory_io/types/type.rb

@@ -1,19 +1,22 @@
 # frozen_string_literal: true
 
-require 'ostruct'
-
+require 'memory_io/context'
 require 'memory_io/types/record'
 require 'memory_io/util'
 
 module MemoryIO
   module Types
-    # The base class, all descendants of this class would be consider as a valid 'type'.
+    # The base class, all descendants of this class would be considered as a valid 'type'.
     class Type
-      # The size of +size_t+. i.e. +sizeof(size_t)+.
-      SIZE_T = 8
+      # The size of +size_t+ assumed when the stream says nothing more specific.
+      #
+      # @see MemoryIO::Context#pointer_size
+      SIZE_T = MemoryIO::Context::DEFAULT_POINTER_SIZE
 
       class << self
-        # Read {Type::SIZE_T} bytes and cast to a little endian unsigned integer.
+        # Read one +size_t+ and cast it to an unsigned integer.
+        #
+        # Its width and byte order are taken from the {MemoryIO::Context} of +stream+.
         #
         # @param [#read] stream
         #   Stream to read.
@@ -21,15 +24,21 @@ module MemoryIO
         # @return [Integer]
         #   Result.
         #
+        # @raise [EOFError]
+        #   Fewer bytes than a +size_t+ remain in +stream+.
+        #
         # @example
         #   s = StringIO.new("\xEF\xBE\xAD\xDExV4\x00")
         #   Type.read_size_t(s).to_s(16)
         #   #=> '345678deadbeef'
         def read_size_t(stream)
-          MemoryIO::Util.unpack(stream.read(SIZE_T))
+          context = MemoryIO::Context.of(stream)
+          MemoryIO::Util.unpack(MemoryIO::Util.read_exactly(stream, context.pointer_size), context.endian)
         end
 
-        # Pack +val+ into {Type::SIZE_T} bytes and write to +stream+.
+        # Pack +val+ into one +size_t+ and write it to +stream+.
+        #
+        # Its width and byte order are taken from the {MemoryIO::Context} of +stream+.
         #
         # @param [#write] stream
         #   Stream to write.
@@ -44,11 +53,16 @@ module MemoryIO
         #   s.string
         #   #=> "\x23\x01\x00\x00\x00\x00\x00\x00"
         def write_size_t(stream, val)
-          stream.write(MemoryIO::Util.pack(val, SIZE_T))
+          context = MemoryIO::Context.of(stream)
+          stream.write(MemoryIO::Util.pack(val, context.pointer_size, context.endian))
         end
 
         # Yield a block and resume the position of stream.
         #
+        # The position is resumed even if the block raises,
+        # so a failure while following an invalid pointer doesn't
+        # leave the stream at an unexpected position.
+        #
         # @param [#pos, #pos=] stream
         #   Stream.
         # @param [Integer] pos
@@ -71,9 +85,11 @@ module MemoryIO
         def keep_pos(stream, pos: nil)
           org = stream.pos
           stream.pos = pos if pos
-          ret = yield stream
-          stream.pos = org
-          ret
+          begin
+            yield stream
+          ensure
+            stream.pos = org
+          end
         end
 
         # @api private
@@ -83,8 +99,9 @@ module MemoryIO
         # @param [Symbol] symbol
         #   Symbol that has been registered in {.register}.
         #
-        # @return [{Symbol => Object}]
-        #   The object that registered in {.register}.
+        # @return [MemoryIO::Types::Record?]
+        #   The record that was registered in {.register},
+        #   or +nil+ if +symbol+ has never been registered.
         #
         # @see .register
         def find(symbol)
@@ -95,10 +112,12 @@ module MemoryIO
         #
         # @param [#read, #write] object
         #   Normally, +object+ is a descendant class of {Type}.
+        # @param [Hash] option
+        #   Extra options.
         #
-        # @option [Symbol, Array<Symbol>] alias
+        # @option option [Symbol, Array<Symbol>] :alias
         #   Custom symbol name(s) that can be used in {.find}.
-        # @option [String] doc
+        # @option option [String] :doc
         #   Doc string that will be shown in README.md.
         #
         # @return [Array<Symbol>]
@@ -119,11 +138,11 @@ module MemoryIO
         #
         # @note
         #   If all symbols in +alias+ have been registered, an ArgumentError will be raised.
-        #   However, if at least one of aliases hasn't been used, registration will success.
+        #   However, if at least one of aliases hasn't been used, registration will succeed.
         #
         # @see .find
         def register(object, option = {})
-          @map ||= OpenStruct.new
+          @map ||= {}
           aliases = Array(option[:alias])
           reg_fail = ArgumentError.new(<<-EOS.strip)
 Register '#{object.inspect}' fails because another object with same name has been registered.
@@ -152,6 +171,7 @@ Specify an alias such as `register(MyClass, alias: :custom_alias_name)`.
         #
         # To record descendants.
         def inherited(klass)
+          super
           register(klass, caller: caller_locations(1, 1).first)
         end
 

data/lib/memory_io/types/types.rb

@@ -3,7 +3,7 @@
 require 'memory_io/types/type'
 require 'memory_io/util'
 
-Dir.glob(File.join(__dir__, '**', '*.rb')).sort.each { |f| require f unless f == __FILE__ }
+Dir.glob(File.join(__dir__, '**', '*.rb')).each { |f| require f unless f == __FILE__ }
 
 module MemoryIO
   # Module that includes multiple types.
@@ -18,22 +18,22 @@ module MemoryIO
     #
     # This method will search all descendants of {Types::Type}.
     #
-    # @return [Symbol] name
+    # @param [Symbol] name
     #   Class name to be searched.
     #
     # @return [#read, #write]
     #   Any object that implemented method +read+ and +write+.
-    #   Usually returns a class inherit {Types::Type}.
+    #   Usually returns a class inherited from {Types::Type}.
     #
     # @example
     #   Types.find(:c_str)
-    #   #=> MemoryIO::Types::CStr
+    #   #=> MemoryIO::Types::Clang::CStr
     #
     #   Types.find(:u64)
     #   #=> #<MemoryIO::Types::Number:0x000055ecc017a310 @bytes=8, @pack_str="Q", @signed=false>
     def find(name)
       obj = Types::Type.find(name)
-      return obj.obj if obj
+      obj&.obj
     end
 
     # @api private
@@ -50,7 +50,7 @@ module MemoryIO
     #
     # @example
     #   Types.get_proc(:c_str, :write)
-    #   #=> #<Method: MemoryIO::Types::CStr.write>
+    #   #=> #<Method: MemoryIO::Types::Clang::CStr.write>
     #   Types.get_proc(:s32, :read)
     #   #=> #<Method: MemoryIO::Types::Number#read>
     def get_proc(name, rw)