buffer_cursor 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f0248ae74ccce99afd9a02ea3260385a5091fcf4
+  data.tar.gz: ac5726f7ab26d3fcfdad14ddabc0dbaa5aaa0c04
+SHA512:
+  metadata.gz: 24f0e47f8b8c4f9d8e054caa5bb50e253ddbbcd8f1291a73ab72719bacae64728724f9f9b46f1a129e95daa9c79c60d9d964853e38916b381fb1b31e5418d9fb
+  data.tar.gz: 1e27b54e1776f8ab1f84fbbc08484703e180ed44d54c56be5895d99fb3cc3e90b4c0af8106d677c053097f32bf72e6bcfbdc19c7d1396ebd80f2323abc0c9473

data/AUTHORS.md

@@ -0,0 +1,7 @@
+# Primary Authors #
+
+The primary authors of `buffer_cursor` have been:
+
+* Jeremy Cole \<jeremy@jcole.us\>
+* Davi Arnaut \<davi.arnaut@gmail.com\>
+

data/LICENSE

@@ -0,0 +1,29 @@
+This software is licensed under the Revised (3-clause) BSD license as follows:
+
+Copyright (c) 2013, Twitter, Inc.
+Copyright (c) 2013, Jeremy Cole <jeremy@jcole.us>
+Copyright (c) 2013, Davi Arnaut <davi.arnaut@gmail.com>
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the <organization> nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,6 @@
+# A cursor for byte buffers #
+
+The purpose of this library is to allow easy traversal of buffers of raw data from external sources, such as binary file formats. Often it is necessary to traverse these buffers field-by-field, decoding each field as you go, and in some cases making decisions about the next fields based on the already-encountered ones.
+
+This library was originally developed to read InnoDB's on-disk file format data structures in [innodb_ruby](https://github.com/jeremycole/innodb_ruby) and due to its usefulness there, was subsequently extracted into its own package for use in other libraries and programs. In the absence of other complete examples it may be useful to look at BufferCursor's usage in `innodb_ruby` as an example.
+

data/TODO.md

@@ -0,0 +1,5 @@
+# TODO #
+
+[ ] Tracing on a per-instance basis.
+[ ] Redirection of trace output to another file than stdout.
+[ ] Naming of each cursor instance, included in trace output.

data/lib/buffer_cursor.rb

@@ -0,0 +1,301 @@
+# -*- encoding : utf-8 -*-
+
+require "bindata"
+
+# A cursor to walk through data structures to read fields. The cursor can move
+# forwards, backwards, is seekable, and supports peeking without moving the
+# cursor. The BinData module is used for interpreting bytes as desired.
+class BufferCursor
+  VERSION = "0.9.0"
+
+  # An entry in a stack of cursors. The cursor position, direction, and
+  # name array are each attributes of the current cursor stack and are
+  # manipulated together.
+  class StackEntry
+    attr_accessor :cursor
+    attr_accessor :position
+    attr_accessor :direction
+    attr_accessor :name
+
+    def initialize(cursor, position=0, direction=:forward, name=nil)
+      @cursor = cursor
+      @position = position
+      @direction = direction
+      @name = name || []
+    end
+
+    def dup
+      StackEntry.new(cursor, position, direction, name.dup)
+    end
+  end
+
+  @@global_tracing = false
+
+  # Enable tracing for all BufferCursor objects globally.
+  def self.trace!(arg=true)
+    @@global_tracing = arg
+  end
+
+  # Initialize a cursor within a buffer at the given position.
+  def initialize(buffer, position)
+    @buffer = buffer
+    @stack = [ StackEntry.new(self, position) ]
+
+    trace false
+    trace_with :print_trace
+    trace_to STDOUT
+  end
+
+  def trace(arg=true)
+    @instance_tracing = arg
+    self
+  end
+
+  # Print a trace output for this cursor. The method is passed a cursor object,
+  # position, raw byte buffer, and array of names.
+  def print_trace(cursor, position, bytes, name)
+    slice_size = 16
+    bytes.each_slice(slice_size).each_with_index do |slice_bytes, slice_count|
+      @trace_io.puts "%06i %s %-32s  %s" % [
+        position + (slice_count * slice_size),
+        direction == :backward ? "←" : "→",
+        slice_bytes.map { |n| "%02x" % n }.join,
+        slice_count == 0 ? name.join(".") : "↵",
+      ]
+    end
+  end
+
+  def trace_to(file)
+    @trace_io = file
+    self
+  end
+
+  # Set a Proc or method on self to trace with.
+  def trace_with(arg=nil)
+    if arg.nil?
+      @trace_proc = nil
+    elsif arg.class == Proc
+      @trace_proc = arg
+    elsif arg.class == Symbol
+      @trace_proc = lambda { |cursor, position, bytes, name| self.send(arg, cursor, position, bytes, name) }
+    else
+      raise "Don't know how to trace with #{arg}"
+    end
+    self
+  end
+
+  def tracing_enabled?
+    (@@global_tracing or @instance_tracing) && @trace_proc
+  end
+
+  # Generate a trace record from the current cursor.
+  def record_trace(position, bytes, name)
+    @trace_proc.call(self, position, bytes, name) if tracing_enabled?
+  end
+
+  # The current cursor object; the top of the stack.
+  def current
+    @stack.last
+  end
+
+  # Set the field name.
+  def name(name_arg=nil)
+    if name_arg.nil?
+      return current.name
+    end
+
+    unless block_given?
+      raise "No block given"
+    end
+
+    current.name.push name_arg
+    ret = yield(self)
+    current.name.pop
+    ret
+  end
+
+  # Return the direction of the current cursor.
+  def direction(direction_arg=nil)
+    if direction_arg.nil?
+      return current.direction
+    end
+
+    current.direction = direction_arg
+    self
+  end
+
+  # Set the direction of the cursor to "forward".
+  def forward
+    direction(:forward)
+  end
+
+  # Set the direction of the cursor to "backward".
+  def backward
+    direction(:backward)
+  end
+
+  # Return the position of the current cursor.
+  def position
+    current.position
+  end
+
+  # Move the current cursor to a new absolute position.
+  def seek(position)
+    current.position = position if position
+    self
+  end
+
+  # Adjust the current cursor to a new relative position.
+  def adjust(relative_position)
+    current.position += relative_position
+    self
+  end
+
+  # Save the current cursor position and start a new (nested, stacked) cursor.
+  def push(position=nil)
+    @stack.push current.dup
+    seek(position)
+    self
+  end
+
+  # Restore the last cursor position.
+  def pop
+    raise "No cursors to pop" unless @stack.size > 1
+    @stack.pop
+    self
+  end
+
+  # Execute a block and restore the cursor to the previous position after
+  # the block returns. Return the block's return value after restoring the
+  # cursor. Optionally seek to provided position before executing block.
+  def peek(position=nil)
+    raise "No block given" unless block_given?
+    push(position)
+    result = yield(self)
+    pop
+    result
+  end
+
+  # Read a number of bytes forwards or backwards from the current cursor
+  # position and adjust the cursor position by that amount.
+  def read_and_advance(length)
+    data = nil
+    cursor_start = current.position
+    case current.direction
+    when :forward
+      data = @buffer.slice(current.position, length)
+      adjust(length)
+    when :backward
+      adjust(-length)
+      data = @buffer.slice(current.position, length)
+    end
+
+    record_trace(cursor_start, data.bytes, current.name)
+    data
+  end
+
+  # Return raw bytes.
+  def get_bytes(length)
+    read_and_advance(length)
+  end
+
+  # Iterate through length bytes returning each as an unsigned 8-bit integer.
+  def each_byte_as_uint8(length)
+    unless block_given?
+      return enum_for(:each_byte_as_uint8, length)
+    end
+
+    read_and_advance(length).bytes.each do |byte|
+      yield byte
+    end
+
+    nil
+  end
+
+  # Return raw bytes as hex.
+  def get_hex(length)
+    read_and_advance(length).bytes.map { |c| "%02x" % c }.join
+  end
+
+  # Read an unsigned 8-bit integer.
+  def get_uint8(position=nil)
+    seek(position)
+    data = read_and_advance(1)
+    BinData::Uint8.read(data)
+  end
+
+  # Read a big-endian unsigned 16-bit integer.
+  def get_uint16(position=nil)
+    seek(position)
+    data = read_and_advance(2)
+    BinData::Uint16be.read(data)
+  end
+
+  # Read a big-endian signed 16-bit integer.
+  def get_sint16(position=nil)
+    seek(position)
+    data = read_and_advance(2)
+    BinData::Int16be.read(data)
+  end
+
+  # Read a big-endian unsigned 24-bit integer.
+  def get_uint24(position=nil)
+    seek(position)
+    data = read_and_advance(3)
+    BinData::Uint24be.read(data)
+  end
+
+  # Read a big-endian unsigned 32-bit integer.
+  def get_uint32(position=nil)
+    seek(position)
+    data = read_and_advance(4)
+    BinData::Uint32be.read(data)
+  end
+
+  # Read a big-endian unsigned 48-bit integer.
+  def get_uint48(position=nil)
+    seek(position)
+    data = read_and_advance(6)
+    BinData::Uint48be.read(data)
+  end
+
+  # Read a big-endian unsigned 64-bit integer.
+  def get_uint64(position=nil)
+    seek(position)
+    data = read_and_advance(8)
+    BinData::Uint64be.read(data)
+  end
+
+  # Read a big-endian unsigned integer given its size in bytes.
+  def get_uint_by_size(size)
+    case size
+    when 1
+      get_uint8
+    when 2
+      get_uint16
+    when 3
+      get_uint24
+    when 4
+      get_uint32
+    when 6
+      get_uint48
+    when 8
+      get_uint64
+    else
+      raise "Integer size #{size} not implemented"
+    end
+  end
+
+  # Read an array of count unsigned integers given their size in bytes.
+  def get_uint_array_by_size(size, count)
+    (0...count).to_a.inject([]) { |a, n| a << get_uint_by_size(size); a }
+  end
+
+  # Read an array of 1-bit integers.
+  def get_bit_array(num_bits)
+    size = (num_bits + 7) / 8
+    data = read_and_advance(size)
+    bit_array = BinData::Array.new(:type => :bit1, :initial_length => size * 8)
+    bit_array.read(data).to_ary
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: buffer_cursor
+version: !ruby/object:Gem::Version
+  version: 0.9.0
+platform: ruby
+authors:
+- Jeremy Cole
+- Davi Arnaut
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-02-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bindata
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 1.4.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 1.4.5
+description: Cursor for byte buffers
+email: jeremy@jcole.us
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- AUTHORS.md
+- README.md
+- TODO.md
+- lib/buffer_cursor.rb
+homepage: https://github.com/jeremycole/buffer_cursor
+licenses:
+- New BSD (3-clause)
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: Cursor for byte buffers
+test_files: []