memory_io 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 23fd90a4ba0906c5264a4149f8992c1ca22ed251
-  data.tar.gz: d6414406dac7f68362f6d1aafb0d31966f8e21b0
+  metadata.gz: 03e970969f587b0c3baa79df39eb2599c63ab845
+  data.tar.gz: cd31136f30b5a11859bd84f8b1218cab749cabb1
 SHA512:
-  metadata.gz: cc05ccbf5888b182138ff6112f8979e48875a8f3ab68730bf72e3cb5391e9205c32d7494e2d792196eda735eeac7e851e45fadcd54cdf51b9624d779b85e6492
-  data.tar.gz: b7ee99af0626e2486f8fab0da2b3c2bef47d877396a796118fc8ae8b4bfa456df609b0703d4da400b5a147e66a041ae557d69df2212b181f9d073353cf0e4bf6
+  metadata.gz: 598e6d01cbe4e1bb779785ccdd677bd8cff45253cf1ea46e55b546e566d4c81eb9fe0771ebb8207cb6f4d257784e9585cd9d99b7f85108bd9ab1eed9f937c68e
+  data.tar.gz: 9b1adc88d6f34e155af0b7cafd7aa2c02a8ca1afa13de5f861d6e0bd073b61f313b1de630a15cd869c6b8974d8e882915667df867b1427dd0ea02c72f37063c5

data/README.md

@@ -5,10 +5,74 @@
 [![Inline docs](https://inch-ci.org/github/david942j/memory_io.svg?branch=master)](https://inch-ci.org/github/david942j/memory_io)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](http://choosealicense.com/licenses/mit/)
 
-# Memory IO
+# MemoryIO
 
 Read/Write complicated structures in memory easily.
 
+## Motivation
+
+I usually need to dump a structure, say `string` in C++, from memory for debugging.
+This is not hard if using gdb.
+However, gdb doesn't support writing Ruby scripts
+(unless you use [gdb-ruby](https://github.com/david942j/gdb-ruby), which has dependency of **MemoryIO**).
+So I create this repo and want to make the debug procedure much easier.
+
+This repo has two main targets:
+
+1. To communiate with memory easily.
+2. To collect all common structures for debugging/learning.
+
+## Why
+
+It's not hard to read/write a process's memory (simply open the file `/proc/$PID/mem`),
+but it still worth to wrap it.
+
+This repo also targets to collect all common structures, such as how to parse a C++/Rust/Python object from memory.
+Therefore, **Pull Requests of adding new structures** are welcome :D
+
+## Supported Platform
+
+- Linux
+- (TODO) Windows
+- (TODO) MacOS
+
+## Implemented Structures
+
+Following is the list of supported structures.
+Each type has a full-name and an alias. For example,
+
+```ruby
+require 'memory_io'
+
+process = MemoryIO.attach(`pidof victim`.to_i)
+# read a 64-bit unsigned integer
+process.read(0x601000, 1, as: 'basic/u64')
+# is equivalent to
+process.read(0x601000, 1, as: :u64)
+```
+
+Goto [the online document](http://www.rubydoc.info/github/david942j/memory_io/master/MemoryIO/Types) for more details
+of each type.
+
+### BASIC
+- `basic/u8`: An unsigned 8-bit integer. Also known as: `:u8`
+- `basic/u16`: An unsigned 16-bit integer. Also known as: `:u16`
+- `basic/u32`: An unsigned 32-bit integer. Also known as: `:u32`
+- `basic/u64`: An unsigned 64-bit integer. Also known as: `:u64`
+- `basic/s8`: A signed 8-bit integer. Also known as: `:s8`
+- `basic/s16`: A signed 16-bit integer. Also known as: `:s16`
+- `basic/s32`: A signed 32-bit integer. Also known as: `:s32`
+- `basic/s64`: A signed 64-bit integer. Also known as: `:s64`
+- `basic/float`: IEEE-754 32-bit floating number. Also known as: `:float`
+- `basic/double`: IEEE-754 64-bit floating number. Also known as: `:double`
+
+### CLANG
+- `clang/c_str`: A null-terminated string. Also known as: `:c_str`
+
+### CPP
+- `cpp/string`: The `std::string` class in C++11. Also known as: `:string`
+
+
 ## Installation
 
 Available on RubyGems.org!
@@ -20,7 +84,7 @@ $ gem install memory_io
 ## Usage
 
 ### Read Process's Memory
-```
+```ruby
 require 'memory_io'
 
 process = MemoryIO.attach(`pidof victim`.to_i)
@@ -37,3 +101,74 @@ process.read('heap+0x10', 4, as: :u8).map { |c| '0x%x' % c }
 process.read('libc', 4)
 #=> "\x7fELF"
 ```
+
+### Write Process's Memory
+```ruby
+require 'memory_io'
+
+process = MemoryIO.attach('self') # Hack! Write memory of this process directly!
+string = 'A' * 16
+pos = string.object_id * 2 + 16
+process.read(pos, 16)
+#=> 'AAAAAAAAAAAAAAAA'
+
+process.write(pos, 'memory_changed!!')
+string
+#=> 'memory_changed!!'
+```
+
+### Customize Read
+```ruby
+require 'memory_io'
+process = MemoryIO.attach(`pidof victim`.to_i)
+
+# An example that read a chunk of pt-malloc.
+read_chunk = lambda do |stream|
+  _prev_size = stream.read(8)
+  size = (stream.read(8).unpack('Q').first & -16) - 8
+  [size, stream.read(size)]
+end
+process.read('heap', 1, as: read_chunk)
+#=> [24, "\xef\xbe\xad\xde\x00\x00...\x00"]
+```
+
+### Define Own Structure
+```ruby
+require 'memory_io'
+process = MemoryIO.attach(`pidof victim`.to_i)
+
+class MyType < MemoryIO::Types::Type
+  def self.read(stream)
+    self.new(stream.read(1))
+  end
+
+  # Define this if you need to 'write' to memory
+  def self.write(stream, my_type)
+    stream.write(my_type.val)
+  end
+
+  attr_accessor :val
+  def initialize(val)
+    @val = val
+  end
+end
+
+# Use snake-case symbol.
+process.read('libc', 4, as: :my_type)
+#=> [#<MyType @val="\x7F">,
+# #<MyType @val="E">,
+# #<MyType @val="L">,
+# #<MyType @val="F">]
+
+process.write('libc', MyType.new('MEOW'), as: :my_type)
+
+# See if memory changed
+process.read('libc', 4)
+#=> 'MEOW'
+```
+
+## Developing
+
+### To Add a New Structure
+
+TBA

data/lib/memory_io/io.rb

@@ -1,13 +1,15 @@
+# encoding: ascii-8bit
+
 require 'memory_io/types/types'
 
 module MemoryIO
   # Main class to use {MemoryIO}.
   class IO
-    attr_reader :stream # @return [#pos=, #read, #write]
+    attr_reader :stream # @return [#pos, #pos=, #read, #write]
 
     # Instantiate an {IO} object.
     #
-    # @param [#pos=, #read, #write] stream
+    # @param [#pos, #pos=, #read, #write] stream
     #   The file-like object to be read/written.
     #   +file+ can be unwritable if you will not invoke any write-related method.
     #
@@ -27,7 +29,7 @@ module MemoryIO
     # @param [Integer?] from
     #   Invoke +stream.pos = from+ before starting to read.
     #   +nil+ for not changing current position of stream.
-    # @param [nil, Symbol, MemoryIO::Types, Proc] as
+    # @param [nil, Symbol, Proc] as
     #   Decide the type/structure when reading.
     #   See {MemoryIO::Types} for all supported types.
     #
@@ -58,7 +60,7 @@ module MemoryIO
     #
     # @example
     #   stream = StringIO.new('A' * 8 + 'B' * 8)
-    #   io = MemoryIO.new(stream)
+    #   io = MemoryIO::IO.new(stream)
     #   io.read(9)
     #   #=> "AAAAAAAAB"
     #   io.read(100)
@@ -74,7 +76,7 @@ module MemoryIO
     #   #=> [16962]
     # @example
     #   stream = StringIO.new("\xef\xbe\xad\xde")
-    #   io = MemoryIO.new(stream)
+    #   io = MemoryIO::IO.new(stream)
     #   io.read(1, as: :u32)
     #   #=> 3735928559
     #   io.rewind
@@ -82,19 +84,21 @@ module MemoryIO
     #   #=> -559038737
     # @example
     #   stream = StringIO.new("123\x0045678\x00")
-    #   io = MemoryIO.new(stream)
+    #   io = MemoryIO::IO.new(stream)
     #   io.read(2, as: :c_str)
     #   #=> ["123", "45678"]
     # @example
     #   # pass lambda to `as`
     #   stream = StringIO.new("\x03123\x044567")
-    #   io = MemoryIO.new(stream)
+    #   io = MemoryIO::IO.new(stream)
     #   io.read(2, as: lambda { |stream| stream.read(stream.read(1).ord) })
     #   #=> ["123", "4567"]
     #
     # @note
     #   This method's arguments and return value are different with +::IO#read+.
     #   Check documents and examples.
+    #
+    # @see Types
     def read(num_elements, from: nil, as: nil, force_array: false)
       stream.pos = from if from
       return stream.read(num_elements) if as.nil?
@@ -105,6 +109,64 @@ module MemoryIO
       ret
     end
 
+    # Write to stream.
+    #
+    # @param [Object, Array<Object>] objects
+    #   Objects to be written.
+    #
+    # @param [Integer] from
+    #   The position to start to write.
+    #
+    # @param [nil, Symbol, Proc] as
+    #   Decide the method to process writing procedure.
+    #   See {MemoryIO::Types} for all supported types.
+    #
+    #   A +Proc+ is allowed, which should accept +stream+ and one object as arguments.
+    #
+    #   If +objects+ is a descendent instance of {Types::Type} and +as+ is +nil,
+    #   +objects.class+ will be used for +as+.
+    #   Otherwise, when +as = nil+, this method will simply call +stream.write(objects)+.
+    #
+    # @return [void]
+    #
+    # @example
+    #   stream = StringIO.new
+    #   io = MemoryIO::IO.new(stream)
+    #   io.write('abcd')
+    #   stream.string
+    #   #=> "abcd"
+    #
+    #   io.write([1, 2, 3, 4], from: 2, as: :u16)
+    #   stream.string
+    #   #=> "ab\x01\x00\x02\x00\x03\x00\x04\x00"
+    #
+    #   io.write(['A', 'BB', 'CCC'], from: 0, as: :c_str)
+    #   stream.string
+    #   #=> "A\x00BB\x00CCC\x00\x00"
+    # @example
+    #   stream = StringIO.new
+    #   io = MemoryIO::IO.new(stream)
+    #   io.write(%w[123 4567], as: ->(s, str) { s.write(str.size.chr + str) })
+    #   stream.string
+    #   #=> "\x03123\x044567"
+    #
+    # @example
+    #   stream = StringIO.new
+    #   io = MemoryIO::IO.new(stream)
+    #   cpp_string = CPP::String.new('A' * 4, 15, 16)
+    #   # equivalent to io.write(cpp_string, as: :'cpp/string')
+    #   io.write(cpp_string)
+    #   stream.string
+    #   #=> "\x10\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00AAAA\x00"
+    # @see Types
+    def write(objects, from: nil, as: nil)
+      stream.pos = from if from
+      as ||= objects.class if objects.class.ancestors.include?(MemoryIO::Types::Type)
+      return stream.write(objects) if as.nil?
+      conv = to_proc(as, :write)
+      Array(objects).map { |o| conv.call(stream, o) }
+    end
+
     # Set +stream+ to the beginning.
     # i.e. invoke +stream.pos = 0+.
     #
@@ -115,8 +177,10 @@ module MemoryIO
 
     private
 
+    # @api private
     def to_proc(as, rw)
-      ret = as.respond_to?(:call) ? as : MemoryIO::Types.get_proc(as, rw)
+      ret = as.respond_to?(rw) ? as.method(rw) : as
+      ret = ret.respond_to?(:call) ? ret : MemoryIO::Types.get_proc(ret, rw)
       raise ArgumentError, <<-EOERR.strip unless ret.respond_to?(:call)
 Invalid argument `as`: #{as.inspect}. It should be either a Proc or a supported type of MemoryIO::Types.
       EOERR

data/lib/memory_io/process.rb

@@ -76,7 +76,7 @@ $ echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
     #
     # This method has *almost* same arguements and return types as {IO#read}.
     # The only difference is this method needs parameter +addr+ (which
-    # will be passed to paramter +from+ in {IO#reada}).
+    # will be passed to paramter +from+ in {IO#read}).
     #
     # @param [Integer, String] addr
     #   The address start to read.
@@ -104,10 +104,38 @@ $ echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
     #   #=> "\x7fELF"
     # @see IO#read
     def read(addr, num_elements, **options)
-      addr = MemoryIO::Util.safe_eval(addr, bases)
-      File.open(@mem, 'rb') do |f|
-        MemoryIO::IO.new(f).read(num_elements, from: addr, **options)
-      end
+      mem_io(:read) { |io| io.read(num_elements, from: MemoryIO::Util.safe_eval(addr, bases), **options) }
+    end
+
+    # Write objects at +addr+.
+    #
+    # This method has *almost* same arguments as {IO#write}.
+    #
+    # @param [Integer, String] addr
+    #   The address to start to write.
+    #   See examples.
+    # @param [Object, Array<Object>] objects
+    #   Objects to write.
+    #   If +objects+ is an array, the write procedure will be invoked +objects.size+ times.
+    #
+    # @return [void]
+    #
+    # @example
+    #   process = MemoryIO.attach('self')
+    #   s = 'A' * 16
+    #   process.write(s.object_id * 2 + 16, 'BBBBCCCC')
+    #   s
+    #   #=> 'BBBBCCCCAAAAAAAA'
+    # @see IO#write
+    def write(addr, objects, **options)
+      mem_io(:write) { |io| io.write(objects, from: MemoryIO::Util.safe_eval(addr, bases), **options) }
+    end
+
+    private
+
+    def mem_io(perm)
+      flags = perm == :write ? 'wb' : 'rb'
+      File.open(@mem, flags) { |f| yield MemoryIO::IO.new(f) }
     end
   end
 end

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

@@ -0,0 +1,72 @@
+require 'memory_io/types/type'
+
+module MemoryIO
+  module Types
+    # Define native types such as integers and floating numbers.
+    module Basic
+      # Register numbers to {Types}.
+      #
+      # All types registerd by this class are assumed as *little endian*.
+      #
+      # This class registered (un)signed {8, 16, 32, 64)-bit integers and IEEE-754 floating numbers.
+      class Number
+        # @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)
+          @bytes = bytes
+          @signed = signed
+          @pack_str = pack_str
+        end
+
+        # @return [Integer]
+        def read(stream)
+          unpack(stream.read(@bytes))
+        end
+
+        # @param [Integer] val
+        def write(stream, val)
+          stream.write(pack(val))
+        end
+
+        private
+
+        def unpack(str)
+          val = str.unpack(@pack_str).first
+          val -= (2**(@bytes * 8)) if @signed && val >= (2**(@bytes * 8 - 1))
+          val
+        end
+
+        def pack(val)
+          [val].pack(@pack_str)
+        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),
+                        alias: [:"basic/s#{t}", :"s#{t}"],
+                        doc: "A signed #{t}-bit integer.")
+          Type.register(Number.new(t / 8, false, c),
+                        alias: [:"basic/u#{t}", :"u#{t}"],
+                        doc: "An unsigned #{t}-bit integer.")
+        end
+
+        # Register floating numbers.
+        Type.register(Number.new(4, false, 'F'),
+                      alias: %i[basic/float float],
+                      doc: 'IEEE-754 32-bit floating number.')
+        Type.register(Number.new(8, false, 'D'),
+                      alias: %i[basic/double double],
+                      doc: 'IEEE-754 64-bit floating number.')
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# encoding: ascii-8bit
+
+require 'memory_io/types/type'
+
+module MemoryIO
+  module Types
+    # @api private
+    #
+    # Define structures used in C language.
+    module Clang
+      # A null-terminated string.
+      class CStr < Types::Type
+        # @api private
+        #
+        # @return [String]
+        #   String without null byte.
+        def self.read(stream)
+          ret = ''
+          loop do
+            c = stream.read(1)
+            break if c.nil? || c == '' || c == "\x00"
+            ret << c
+          end
+          ret
+        end
+
+        # @api private
+        #
+        # @param [String] val
+        #   A null byte would be appended if +val+ not ends with null byte.
+        def self.write(stream, val)
+          val = val.to_s
+          val << "\x00" unless val.end_with?("\x00")
+          stream.write(val)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,120 @@
+require 'memory_io/types/type'
+
+module MemoryIO
+  module Types
+    # Structures in C++.
+    module CPP
+      # The `std::string` class in C++11.
+      #
+      # The std::string class can be seen as:
+      #   class string {
+      #     void* _M_dataplus;
+      #     size_t string_length;
+      #     union {
+      #       char local_buf[15 + 1];
+      #       size_t allocated_capacity;
+      #     }
+      #   };
+      class String < MemoryIO::Types::Type
+        # 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]
+
+        # Instantiate a {CPP::String} object.
+        #
+        # @param [::String] data
+        # @param [Integer] capacity
+        # @param [Integer] dataplus
+        #   A pointer.
+        def initialize(data, capacity, dataplus)
+          @data = data
+          @capacity = capacity
+          @dataplus = dataplus
+        end
+
+        # String length.
+        #
+        # @return [Integer]
+        def length
+          @data.size
+        end
+        alias size length
+
+        # Set data content.
+        #
+        # @param [String] str
+        def data=(str)
+          @data = str
+          warn("Length of str (#{str.size}) is larger than capacity (#{capacity})") if str.size > 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>",
+                 self.class.name,
+                 data.inspect,
+                 capacity,
+                 dataplus)
+        end
+
+        class << self
+          # @param [#pos, #pos=, #read] stream
+          #
+          # @return [CPP::String]
+          #
+          # @example
+          #   # echo '#include <string>\n#include <cstdio>\nint main() {' > a.cpp && \
+          #   # echo 'std::string a="abcd"; printf("%p\\n", &a);' >> a.cpp && \
+          #   # echo 'scanf("%*c"); return 0;}' >> a.cpp && \
+          #   # g++ -std=c++11 a.cpp -o a
+          #   Open3.popen2('stdbuf -o0 ./a') do |_i, o, t|
+          #     process = MemoryIO.attach(t.pid)
+          #     addr = o.gets.to_i(16)
+          #     process.read(addr, 1, as: :string) # or `as: :'cpp/string'`
+          #     #=> #<MemoryIO::Types::CPP::String @data="abcd", @capacity=15, @dataplus=0x00007ffe539ca250>
+          #   end
+          def read(stream)
+            dataplus = read_size_t(stream)
+            length = read_size_t(stream)
+            union = stream.read(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) }
+            else
+              capacity = LOCAL_CAPACITY
+              data = union[0, length]
+            end
+            new(data, capacity, dataplus)
+          end
+
+          # Write a {CPP::String} object to stream.
+          #
+          # @param [#pos, #pos=, #write] stream
+          # @param [CPP::String] obj
+          #
+          # @return [void]
+          def write(stream, obj)
+            write_size_t(stream, obj.dataplus)
+            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") }
+              write_size_t(stream, obj.capacity)
+            else
+              stream.write(obj.data + "\x00")
+            end
+            stream.pos = pos + LOCAL_CAPACITY + 1
+          end
+        end
+      end
+    end
+  end
+end

data/lib/memory_io/types/record.rb

@@ -0,0 +1,68 @@
+module MemoryIO
+  module Types
+    # @api private
+    #
+    # Class that handles a registered object in {Types::Type.find}.
+    # For example, this class will parse inline-docs to generate README.md.
+    class Record
+      # @return [Object]
+      #   Whatever.
+      attr_reader :obj
+
+      # @return [Array<Symbol>]
+      #   All symbols that can find this record in {Type.find}.
+      attr_reader :keys
+
+      # Instantiate a {Record} object.
+      #
+      # @param [Object] object
+      # @param [Array<Symbol>] keys
+      #
+      # @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.
+      def initialize(object, keys, option = {})
+        @obj = object
+        @keys = keys
+        @force_doc = option[:doc]
+        @caller = option[:caller]
+      end
+
+      # Get the doc string.
+      #
+      # @return [String]
+      #   If option +doc+ had been passed in {#initialize}, this method simply returns it.
+      #   Otherwise, parse the file for inline-docs.
+      #   If neither +doc+ nor +caller+ had been passed to {#initialize}, an empty string is returned.
+      def doc
+        return @force_doc if @force_doc
+        return '' unless @caller
+        parse_file_doc(@caller.absolute_path, @caller.lineno)
+      end
+
+      private
+
+      # @return [String]
+      def parse_file_doc(file, lineno)
+        return '' unless ::File.file?(file)
+        strings = []
+        lines = ::IO.binread(file).split("\n")
+        (lineno - 1).downto(1) do |no|
+          str = lines[no - 1]
+          break if str.nil?
+          str.strip!
+          break unless str.start_with?('#')
+          strings.unshift(str[2..-1] || '')
+        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"
+      end
+    end
+  end
+end

data/lib/memory_io/types/type.rb

@@ -1,35 +1,166 @@
+require 'ostruct'
+
+require 'memory_io/types/record'
+require 'memory_io/util'
+
 module MemoryIO
   module Types
     # The base class, all descendents of this class would be consider as a valid 'type'.
     class Type
+      # The size of +size_t+. i.e. +sizeof(size_t)+.
+      SIZE_T = 8
+
       class << self
+        # Read {Type::SIZE_T} bytes and cast to a little endian unsigned integer.
+        #
+        # @param [#read] stream
+        #   Stream to read.
+        #
+        # @return [Integer]
+        #   Result.
+        #
+        # @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))
+        end
+
+        # Pack +val+ into {Type::SIZE_T} bytes and write to +stream+.
+        #
+        # @param [#write] stream
+        #   Stream to write.
+        # @param [Integer] val
+        #   Value to be written.
+        #
+        # @return [void]
+        #
+        # @example
+        #   s = StringIO.new
+        #   Type.write_size_t(s, 0x123)
+        #   s.string
+        #   #=> "\x23\x01\x00\x00\x00\x00\x00\x00"
+        def write_size_t(stream, val)
+          stream.write(MemoryIO::Util.pack(val, SIZE_T))
+        end
+
+        # Yield a block and resume the position of stream.
+        #
+        # @param [#pos, #pos=] stream
+        #   Stream.
+        # @param [Integer] pos
+        #   Move +stream+'s position to +pos+ before invoke the block.
+        #
+        # @yieldparam [#pos, #pos=] stream
+        #   Same as parameter +stream+.
+        # @yieldreturn [Object]
+        #   The returned object will be returned by this method.
+        #
+        # @return [Object]
+        #   Returns the object returned by block.
+        #
+        # @example
+        #   s = StringIO.new('1234')
+        #   Type.keep_pos(s, pos: 2) { |s| s.read(2) }
+        #   #=> '34'
+        #   s.pos
+        #   #=> 0
+        def keep_pos(stream, pos: nil)
+          org = stream.pos
+          stream.pos = pos if pos
+          ret = yield stream
+          stream.pos = org
+          ret
+        end
+
+        # @api private
+        #
         # Find the subclass of {Type} by symbol.
         #
         # @param [Symbol] symbol
-        #   Symbol to be find.
+        #   Symbol that has been registered in {.register}.
         #
-        # @return [#read, #write]
+        # @return [{Symbol => Object}]
         #   The object that registered in {.register}.
+        #
+        # @see .register
         def find(symbol)
           @map[symbol]
         end
 
-        # @api private
+        # Register a new type.
         #
-        # @param [Symbol] symbol
-        #   Symbol name that used for searching.
-        # @param [#read, #write] klass
-        #   Normally, +klass+ is a descendent of {Type}.
+        # @param [#read, #write] object
+        #   Normally, +object+ is a descendent class of {Type}.
         #
-        # @return [void]
-        def register(symbol, klass)
-          @map ||= {}
-          @map[symbol] = klass
+        # @option [Symbol, Array<Symbol>] alias
+        #   Custom symbol name(s) that can be used in {.find}.
+        # @option [String] doc
+        #   Doc string that will be shown in README.md.
+        #
+        # @return [Array<Symbol>]
+        #   Array of symbols that can be used for finding the registered object.
+        #
+        # @example
+        #   Type.register(MemoryIO::Types::Clang::CStr, alias: :meow)
+        #   #=> [:'clang/c_str', :c_str, :meow]
+        #
+        #   Type.register(ModuleOne::CStr, alias: :my_class)
+        #   #=> [:'module_one/c_str', :my_class]
+        #
+        #   Type.register(AnotherClass, alias: :my_class)
+        #   # An error will be raised because the 'alias' has been registered.
+        #
+        #   Type.register(AnotherClass, alias: [:my_class, my_class2])
+        #   #=> [:another_class, :my_class2]
+        #
+        # @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.
+        #
+        # @see .find
+        def register(object, option = {})
+          @map ||= OpenStruct.new
+          aliases = Array(option[:alias])
+          reg_fail = ArgumentError.new(<<-EOS.strip)
+Register '#{object.inspect}' fails because another object with same name has been registered.
+Specify an alias such as `register(MyClass, alias: :custom_alias_name)`.
+          EOS
+          raise reg_fail if aliases.any? && aliases.all? { |ali| @map[ali] }
+          keys = get_keys(object).concat(aliases).uniq.reject { |k| @map[k] }
+          raise reg_fail if keys.empty?
+          rec = MemoryIO::Types::Record.new(object, keys, option)
+          keys.each { |k| @map[k] = rec }
         end
 
-        # TO record descendants.
+        # @abstract
+        def read(_stream) raise NotImplementedError
+        end
+
+        # @abstract
+        def write(_stream, _obj) raise NotImplementedError
+        end
+
+        private
+
+        # @api private
+        #
+        # To record descendants.
         def inherited(klass)
-          register(MemoryIO::Util.underscore(klass.name).to_sym, klass)
+          register(klass, caller: caller_locations(1, 1).first)
+        end
+
+        # @param [Class] klass
+        #
+        # @return [Array<Symbol>]
+        def get_keys(klass)
+          return [] unless klass.instance_of?(Class)
+          snake = MemoryIO::Util.underscore(klass.name)
+          snake.gsub!(%r[^memory_io/types/], '')
+          ret = [snake]
+          ret << ::File.basename(snake)
+          ret.map(&:to_sym).uniq
         end
       end
     end

data/lib/memory_io/types/types.rb

@@ -1,8 +1,7 @@
 require 'memory_io/types/type'
 require 'memory_io/util'
 
-require 'memory_io/types/c_str'
-require 'memory_io/types/number'
+Dir[File.join(__dir__, '**', '*.rb')].each { |f| require f }
 
 module MemoryIO
   # Module that includes multiple types.
@@ -15,24 +14,28 @@ module MemoryIO
     #
     # Returns the class whose name matches +name+.
     #
-    # This method would search all descendants of {Types::Type}.
+    # This method will search all descendants of {Types::Type}.
     #
     # @return [Symbol] name
     #   Class name to be searched.
     #
-    # @return [Class?]
-    #   The class.
+    # @return [#read, #write]
+    #   Any object that implemented method +read+ and +write+.
+    #   Usually returns a class inherit {Types::Type}.
     #
     # @example
-    #   Types.find(:u64)
-    #   #=> MemoryIO::Types::U64
-    #
     #   Types.find(:c_str)
     #   #=> MemoryIO::Types::CStr
+    #
+    #   Types.find(:u64)
+    #   #=> #<MemoryIO::Types::Number:0x000055ecc017a310 @bytes=8, @pack_str="Q", @signed=false>
     def find(name)
-      Types::Type.find(Util.underscore(name.to_s).to_sym)
+      obj = Types::Type.find(name)
+      return obj.obj if obj
     end
 
+    # @api private
+    #
     # Returns a callable object according to +name+.
     #
     # @param [Symbol] name

data/lib/memory_io/util.rb

@@ -8,7 +8,7 @@ module MemoryIO
 
     # Convert input into snake-case.
     #
-    # This method also removes strings before +'::'+ in +str+.
+    # This method also converts +'::'+ to +'/'+.
     #
     # @param [String] str
     #   String to be converted.
@@ -21,10 +21,10 @@ module MemoryIO
     #   #=> 'memory_io'
     #
     #   Util.underscore('MyModule::MyClass')
-    #   #=> 'my_class'
+    #   #=> 'my_module/my_class'
     def underscore(str)
       return '' if str.empty?
-      str = str.split('::').last
+      str = str.gsub('::', '/')
       str.gsub!(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
       str.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
       str.downcase!
@@ -77,6 +77,44 @@ module MemoryIO
       Dentaku::Calculator.new.store(vars).evaluate(str)
     end
 
+    # Unpack a string into an integer.
+    # Little endian is used.
+    #
+    # @param [String] str
+    #   String.
+    #
+    # @return [Integer]
+    #   Result.
+    #
+    # @example
+    #   Util.unpack("\xff")
+    #   #=> 255
+    #   Util.unpack("@\xE2\x01\x00")
+    #   #=> 123456
+    def unpack(str)
+      str.bytes.reverse.reduce(0) { |s, c| s * 256 + c }
+    end
+
+    # Pack an integer into +b+ bytes.
+    # Little endian is used.
+    #
+    # @param [Integer] val
+    #   The integer to pack.
+    #   If +val+ contains more than +b+ bytes,
+    #   only lower +b+ bytes in +val+ will be packed.
+    #
+    # @param [Integer] b
+    #
+    # @return [String]
+    #   Packing result with length +b+.
+    #
+    # @example
+    #   Util.pack(0x123, 4)
+    #   #=> "\x23\x01\x00\x00"
+    def pack(val, b)
+      Array.new(b) { |i| (val >> (i * 8)) & 0xff }.pack('C*')
+    end
+
     # Remove extension name (.so) and version in library name.
     #
     # @param [String] name

data/lib/memory_io/version.rb

@@ -1,4 +1,4 @@
 module MemoryIO
   # Current gem version.
-  VERSION = '0.0.0'.freeze
+  VERSION = '0.1.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: memory_io
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - david942j
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-01-02 00:00:00.000000000 Z
+date: 2018-01-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dentaku
@@ -125,8 +125,10 @@ files:
 - lib/memory_io.rb
 - lib/memory_io/io.rb
 - lib/memory_io/process.rb
-- lib/memory_io/types/c_str.rb
-- lib/memory_io/types/number.rb
+- lib/memory_io/types/basic/number.rb
+- lib/memory_io/types/clang/c_str.rb
+- lib/memory_io/types/cpp/string.rb
+- lib/memory_io/types/record.rb
 - lib/memory_io/types/type.rb
 - lib/memory_io/types/types.rb
 - lib/memory_io/util.rb

data/lib/memory_io/types/c_str.rb

@@ -1,34 +0,0 @@
-# encoding: ascii-8bit
-
-require 'memory_io/types/type'
-
-module MemoryIO
-  module Types
-    # Read a null-terminated string.
-    class CStr < Types::Type
-      # @api private
-      #
-      # @return [String]
-      #   String without null byte.
-      def self.read(stream)
-        ret = ''
-        loop do
-          c = stream.read(1)
-          break if c.nil? || c == '' || c == "\x00"
-          ret << c
-        end
-        ret
-      end
-
-      # @api private
-      #
-      # @param [String] val
-      #   A null byte would be appended if +val+ not ends with null byte.
-      def self.write(stream, val)
-        val = val.to_s
-        val << "\x00" unless val.end_with?("\x00")
-        stream.write(val)
-      end
-    end
-  end
-end

data/lib/memory_io/types/number.rb

@@ -1,60 +0,0 @@
-require 'memory_io/types/type'
-
-module MemoryIO
-  module Types
-    # @api private
-    # Register numbers to {Types}.
-    #
-    # All types registerd by this class are assumed as *little endian*.
-    class Number
-      # @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)
-        @bytes = bytes
-        @signed = signed
-        @pack_str = pack_str
-      end
-
-      # @return [Integer]
-      def read(stream)
-        unpack(stream.read(@bytes))
-      end
-
-      # @param [Integer] val
-      def write(stream, val)
-        stream.write(pack(val))
-      end
-
-      private
-
-      def unpack(str)
-        val = str.unpack(@pack_str).first
-        val -= (2**@bytes) if @signed && val >= (2**(@bytes - 1))
-        val
-      end
-
-      def pack(val)
-        [val].pack(@pack_str)
-      end
-
-      # Register (un)signed n-bites integers.
-      {
-        8 => 'C',
-        16 => 'S',
-        32 => 'I',
-        64 => 'Q'
-      }.each do |t, c|
-        Type.register("s#{t}".to_sym, Number.new(t, true, c))
-        Type.register("u#{t}".to_sym, Number.new(t, false, c))
-      end
-
-      # Register floating numbers.
-      Type.register(:float, Number.new(4, false, 'F'))
-      Type.register(:double, Number.new(8, false, 'D'))
-    end
-  end
-end