binary_parser 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2d5b2692b4a9c6b2bb5be201074f80779039f881
+  data.tar.gz: 0e6c1da7ab3aa2ca1f8e79150c34262ec08a4772
+SHA512:
+  metadata.gz: 1c59d35586e0f044ebdef155ef191169a4cf3dd65ba2743d9c19974759aefd55e27d93bb1121443a81c350617b7b75ca17cc9b6d9e05de522f4e9e300f650e7b
+  data.tar.gz: def0d9f155a7af845d78ce08b87555acca72c11e1f63ae41b716c0fcbc94536e8d66148d1946d2be9e174ec648b0948ebe67df2216be9199d0c9d2a727aa9259

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in binary_parser.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 rokugats(u)
+
+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.

data/README.md

@@ -0,0 +1,239 @@
+Ruby-Binary-Parser
+===================
+Ruby-Binary-Parser is Ruby Gem library providing DSL for parsing binary-data, such as Image files, Video files, etc.
+Without operating bytes and bits complicatedly, you can parse and read binary-data *generically* and *abstractly*.
+
+
+Description
+-----------
+This library can parse all kind of binary-data structures including non-fixed length of structures and nested structures.
+For generic parsing, loop and condition(if) statement to define structures is provided in this library.
+Of course, values of neighbor binary-data can be used as the other binary-data's specification of length.
+
+Furthermore, this library handles all binary-data under the lazy evaluation.
+So you can read required parts of a binary-data very quickly even if whole of the binary-data is too big, 
+
+
+Notice
+------
+Currently, this library supports only READ of binary-data.
+So you cannot WRITE binary-data directly with this library.
+
+
+Usage
+-----
+Look at following examples to quickly understand how to use this library.
+
+### Install ###
+    $ gem install binary_parser
+
+
+### Example 1  ###
+Consider the following (temporary) binary structures which describe Image data.
+
+<table style="margin-left:auto;margin-right:auto;">
+  <tr><td colspan=4 style="text-align:center;">MyImage (non-fixed length)</td></tr>
+  <tr style="background-color:lightsteelblue;">
+	  <td style="width:150px;">Data Name</td>
+		<td style="width:80px;">Type</td>
+	  <td style="width:100px;">Bit Length</td>
+		<td style="width:200px;">Number Of Replications</td>
+	</tr>
+  <tr>
+	  <td>height</td>
+		<td>UInt</td>
+	  <td>8</td>
+		<td>1</td>
+	</tr>
+  <tr>
+	  <td>width</td>
+		<td>UInt</td>
+	  <td>8</td>
+		<td>1</td>
+	</tr>
+  <tr>
+	  <td>RGB color bit-map</td>
+		<td>UInt</td>
+	  <td>8 * 3</td>
+		<td>'height' * 'width'</td>
+	</tr>
+  <tr>
+	  <td>has date?</td>
+		<td>Flag</td>
+	  <td>1</td>
+		<td>1</td>
+	</tr>
+  <tr>
+	  <td>date</td>
+		<td>MyDate</td>
+	  <td>31</td>
+		<td>'has date?' is 1 => 1<br>else => 0</td>
+	</tr>
+</table>
+
+
+<table style="margin-left:auto;margin-right:auto;">
+  <tr><td colspan=4 style="text-align:center;">MyDate (31 bit)</td></tr>
+  <tr style="background-color:lightsteelblue;">
+	  <td style="width:150px;">Data Name</td>
+		<td style="width:80px;">Type</td>
+	  <td style="width:100px;">Bit Length</td>
+		<td style="width:200px;">Number Of Replications</td>
+	</tr>
+  <tr>
+	  <td>year</td>
+		<td>UInt</td>
+	  <td>13</td>
+		<td>1</td>
+	</tr>
+  <tr>
+	  <td>month</td>
+		<td>UInt</td>
+	  <td>9</td>
+		<td>1</td>
+	</tr>
+  <tr>
+	  <td>day</td>
+		<td>UInt</td>
+	  <td>9</td>
+		<td>1</td>
+	</tr>
+</table>
+
+You can define MyImage structure in ruby program as following code.
+
+
+    require 'binary_parser'
+
+    class MyDate < BinaryParser::TemplateBase
+      require 'date'
+
+      Def do
+        data :year,  UInt, 13
+        data :month, UInt, 9
+        data :day,   UInt, 9
+      end
+
+      def to_date
+        return Date.new(year.to_i, month.to_i, day.to_i)
+      end
+    end
+
+    class MyImage < BinaryParser::TemplateBase
+      Def do
+        data :height, UInt, 8
+        data :width,  UInt, 8
+
+        TIMES var(:height), :i do
+          TIMES var(:width), :j do
+            data :R, UInt, 8
+            data :G, UInt, 8
+            data :B, UInt, 8
+          end
+        end
+
+        data :has_date, Flag, 1
+        IF cond(:has_date){|v| v.flagged?} do
+          data :date, MyDate, 31
+        end
+      end
+    end
+
+
+And then you can parse and read binay-data of MyImage as follows.
+
+    File.open('my_image.bin', 'rb') do |f|
+      image = MyImage.new(f.read)
+      print "Image size: #{image.height.to_i}x#{image.width.to_i}\n"
+      ul = image.i[0].j[0]
+      print "RGB color at the first is (#{ul.R.to_i}, #{ul.G.to_i}, #{ul.B.to_i})\n"
+      print "Image date: #{image.date.to_date}\n"
+    end
+
+
+If 'my_image.bin' is binary-data-file of [0x02, 0x02, 0xe7,0x39,0x62, 0x00,0x00,0x00, 0xe7,0x39,0x62, 0x00,0x00,0x00, 0x9f, 0x78, 0x08, 0x03], 
+you can get output as follows.
+
+    Image size: 2x2
+    RGB color at the first is (231, 57, 98)
+    Image date: 2014-04-03
+
+
+For your information, you can dump all binary-data's information as follows.
+
+    File.open('my_image.bin', 'rb') do |f|
+      image = MyImage.new(f.read)
+      image.show(true)
+    end
+
+
+### Example 2  ###
+You can also define other structures as follows.
+
+    class DefExample < BinaryParser::TemplateBase
+      Def do
+        data :loop_byte_length, UInt, 8
+
+        # Loop until 'loop_byte_length' * 8 bits are parsed.
+        SPEND var(:loop_byte_length) * 8, :list do
+          data :length, UInt,   8
+          # Specifying length by neigbor value.
+          data :data,   Binary, var(:length) * 8
+        end
+
+        data :v1, UInt, 8
+        data :v2, UInt, 8
+
+        # Number of Condition variables is arbitary. 
+        IF cond(:v1, :v2){|v1, v2| v1.to_i == v2.to_i} do
+          # +, -, *, / is available for var. (Order of [Integer op Variable] is NG.)
+          data :v3, UInt, (var(:v1) + var(:v2)) * 8
+        end
+      end
+    end
+
+Check this definition by giving some binary-data and calling show method as follows. 
+
+    i = DefExample.new([0x05, 0x01, 0xff, 0x02, 0xff, 0xff, 0x01, 0x01, 0x01, 0x01].pack("C*"))
+    i.show(true)
+
+
+### Example 3  ###
+If you want to operate Stream-data, StreamTemplateBase class is useful. Define stream as follows.
+
+    class StreamExample < BinaryParser::StreamTemplateBase
+      # Stream which consists of every 4 byte binary-data.
+      Def(4) do
+        data :data1, UInt,   8
+        data :data2, Binary, 24
+      end
+    end
+
+And then, get structures from the stream as follows.
+
+    File.open('my_image.bin', 'rb') do |f|
+      stream = StreamExample.new(f)
+      packet = stream.get_next
+      puts "data1: #{packet.data1.to_i}, data2: #{packet.data2.to_s}"
+      stream.get_next.show(true)
+    end
+
+StreamTemplateBase has many useful method to choose structures from the stream.
+If you want to know detail of these methods, please read documentation or concerned source-files.
+
+
+Documentation
+--------------
+I'm sorry, but only RDoc (auto-generated documentation) is now available.
+For example, you can read RDoc on web browser by following operations.
+
+    $ gem install binary_parser
+    $ gem server
+    Server started at http://0.0.0.0:8808
+
+Access shown address by web browser.
+
+
+Versions
+--------
+1.0.0 April 6, 2014

data/Rakefile

@@ -0,0 +1,11 @@
+# -*- mode: ruby -*-
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+task :default => [:test]
+
+Rake::TestTask.new do |test|
+  test.test_files = Dir["unit_test/**/test_*.rb"]
+  test.verbose = true
+end
+

data/binary_parser.gemspec

@@ -0,0 +1,33 @@
+# -*- mode: ruby; coding: utf-8 -*-
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'binary_parser/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "binary_parser"
+  spec.version       = BinaryParser::VERSION
+  spec.authors       = ["rokugats(u)"]
+  spec.email         = ["sasasawada@gmail.com"]
+  spec.summary       = "An elegant DSL library for parsing binary-data."
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+
+  spec.description = <<-END
+This library can parse all kind of binary-data structures including non-fixed length of structures and nested structures.
+For generic parsing, loop and condition(if) statement to define structures is provided in this library.
+Of course, values of neighbor binary-data can be used as the other binary-data's specification of length.
+
+Furthermore, this library handles all binary-data under the lazy evaluation.
+So you can read required parts of a binary-data very quickly even if whole of the binary-data is too big, 
+END
+
+end

data/lib/binary_parser.rb

@@ -0,0 +1,50 @@
+require "binary_parser/version"
+
+module BinaryParser
+
+  LIBRARY_ROOT_PATH = File.dirname(File.expand_path(File.dirname(__FILE__)))
+
+  # load general class file
+  GENERAL_CLASS_DIR = '/lib/general_class/'
+  GENERAL_CLASS_FILES =
+    ['abstract_binary',
+     'expression.rb',
+     'bit_position.rb',
+     'condition.rb'
+    ]
+
+  GENERAL_CLASS_FILES.each do |path|
+    require LIBRARY_ROOT_PATH + GENERAL_CLASS_DIR  + path
+  end
+
+
+  # load built-in template file
+  class TemplateBase; end
+  BUILT_IN_TEMPLATE_DIR = '/lib/built_in_template/'
+  BUILT_IN_TEMPLATE_FILES =
+    ['uint.rb',
+     'flag.rb',
+     'binary.rb'
+    ]
+
+  BUILT_IN_TEMPLATE_FILES.each do |path|
+    require LIBRARY_ROOT_PATH + BUILT_IN_TEMPLATE_DIR  + path
+  end
+  
+
+  # load library main file
+  LIB_DIR = '/lib/'
+  LIB_FILES =
+    ['loop_list.rb',
+     'scope.rb',
+     'structure_definition.rb',
+     'template_base.rb',
+     'stream_template_base.rb',
+     'nameless_template.rb',
+     'error.rb'
+    ]
+
+  LIB_FILES.each do |path|
+    require LIBRARY_ROOT_PATH + LIB_DIR  + path
+  end
+end

data/lib/binary_parser/version.rb

@@ -0,0 +1,3 @@
+module BinaryParser
+  VERSION = "1.0.0"
+end

data/lib/built_in_template/binary.rb

@@ -0,0 +1,12 @@
+module BinaryParser
+  module BuiltInTemplate
+    class Binary < TemplateBase
+      def content_description
+        chars = to_chars
+        bytes = chars[0, 5].map{|i| sprintf("0x%02x", i)}.join(", ")
+        return "[" + bytes + (chars.length > 5 ? ", ..." : "") + "]"
+      end
+    end
+  end
+end
+

data/lib/built_in_template/flag.rb

@@ -0,0 +1,22 @@
+module BinaryParser
+  module BuiltInTemplate
+    class Flag < TemplateBase
+
+      def on?
+        return to_i[0] == 1
+      end
+
+      alias_method :flagged?, :on?
+
+      def off?
+        return !on?
+      end
+
+      alias_method :unflagged?, :off?
+
+      def content_description
+        on? ? "true" : "false"
+      end
+    end
+  end
+end

data/lib/built_in_template/uint.rb

@@ -0,0 +1,9 @@
+module BinaryParser
+  module BuiltInTemplate
+    class UInt < TemplateBase
+      def content_description
+        to_i.to_s
+      end
+    end
+  end
+end

data/lib/error.rb

@@ -0,0 +1,21 @@
+module BinaryParser
+
+  # User do Invalid Parsing Definition.
+  DefinitionError = Class.new(StandardError)
+
+  # User do Bad Manipulation.
+  BadManipulationError = Class.new(StandardError)
+
+  # Undefined Data is referenced.
+  UndefinedError = Class.new(StandardError)
+
+  # Invalid Binary Pattern is parsed.
+  ParsingError = Class.new(StandardError)
+
+  # Invalid Binary Manipulation is done.
+  BadBinaryManipulationError = Class.new(StandardError)
+
+  # Assertion Error.
+  # If this error occurs in regular use, probably this library(binary_parser) has Bugs.
+  ProgramAssertionError = Class.new(StandardError)
+end