struct-fx 0.1.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,13 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+  gem "frozen-objects", ">= 0.2.0"
+  gem "bit-packer", ">= 0.1.0"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.2"
+  gem "riot", ">= 0.12.1"
+end

data/Gemfile.lock

@@ -0,0 +1,28 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    bit-packer (0.1.0)
+      lookup-hash (>= 0.2.0)
+    frozen-objects (0.2.0)
+    git (1.2.5)
+    hash-utils (0.11.0)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    lookup-hash (0.2.0)
+      hash-utils (>= 0.11.0)
+    rake (0.8.7)
+    riot (0.12.2)
+      rr
+    rr (1.0.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bit-packer (>= 0.1.0)
+  bundler (~> 1.0.0)
+  frozen-objects (>= 0.2.0)
+  jeweler (~> 1.5.2)
+  riot (>= 0.12.1)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Martin Kozák
+
+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,79 @@
+StructFx
+========
+
+**struct-fx** provides declarative pure Ruby equivalent of C++ structs.
+Declarations are simple:
+
+    gif = StructFx::new(data) do
+        string (:format) {3}
+        string (:version) {3}
+        uint16 :width
+        uint16 :height
+    end
+
+See whole real live example:
+
+    require "struct-fx"
+
+    # Read and analyze file
+    
+    File.open("./test.gif", "rb") do |io|
+        data = io.read(10)
+    end
+
+    gif = StructFx::new(data) do
+        string (:format) {3}
+        string (:version) {3}
+        uint16 :width
+        uint16 :height
+    end
+    
+    # Get results
+    
+    p gif.length        # declared struct length is really 10 bytes
+    
+    p gif.data.format   # "GIF"
+    p gif.data.version  # "89a"
+    p gif.data.width    # 32
+    p gif.data.height   # 32    # it's square :-)
+    
+    # Change the values
+    
+    gif.data.version = "87a"
+    gif.data.width = 128
+    gif.data.height = 128
+    
+    gif.data.to_s       # "GIF87a\x80\x00\x80\x00"
+    
+Supported data types are:
+    
+ * signed and unsigned `integers` (1 to 8 bytes),
+ * fixed-size `strings` (specified length),
+ * `floats` and `doubles` (4 and 8 bytes),
+ * single `chars` (1 byte),
+ * `packed bytes` and `flag arrays` (1 byte),
+ * skipped data blocks.
+ 
+More detailed documentation is available in `StructFx#declare` method 
+documentation and [documentation][2] of the [BitPacker][1] library.
+
+Contributing
+------------
+
+1. Fork it.
+2. Create a branch (`git checkout -b 20101220-my-change`).
+3. Commit your changes (`git commit -am "Added something"`).
+4. Push to the branch (`git push origin 20101220-my-change`).
+5. Create an [Issue][3] with a link to your branch.
+6. Enjoy a refreshing Diet Coke and wait.
+
+Copyright
+---------
+
+Copyright © 2011 [Martin Kozák][4]. See `LICENSE.txt` for
+further details.
+
+[1]: http://github.com/martinkozak/bit-packer
+[2]: http://rubydoc.info/gems/bit-packer/0.1.0/frames
+[3]: http://github.com/martinkozak/struct-fx/issues
+[4]: http://www.martinkozak.net/

data/Rakefile

@@ -0,0 +1,37 @@
+# encoding: utf-8
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "struct-fx"
+  gem.homepage = "http://github.com/martinkozak/struct-fx"
+  gem.license = "MIT"
+  gem.summary = 'Declarative pure Ruby equivalent of C/C++ structs.'
+  gem.email = "martinkozak@martinkozak.net"
+  gem.authors = ["Martin Kozák"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "hash-utils #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/struct-fx.rb

@@ -0,0 +1,328 @@
+#!/usr/bin/ruby
+# encoding: utf-8
+# (c) 2011 Martin Kozák (martinkozak@martinkozak.net)
+
+require "frozen-objects"
+require "bit-packer"
+
+##
+# StructFx builder and analyzer.
+#
+
+class StructFx
+    
+    ##
+    # Holds resultant data structure.
+    #
+    
+    @struct
+
+    ##
+    # Holds type stack.
+    #
+    
+    @stack
+    
+    ##
+    # Holds data.
+    #
+    
+    @data
+    
+    ##
+    # Holds raw data.
+    # @return [String] raw (original) string data
+    #
+    
+    attr_reader :raw
+    @raw
+    
+    ##
+    # Holds stack in compiled form.
+    #
+
+    @compiled
+    
+    ##
+    # Holds types metainformations map.
+    #
+    
+    TYPES = Frozen << {
+        :int8 => ["c", 1],
+        :int16 => ["s", 2],
+        :int32 => ["l", 4],
+        :int64 => ["q", 8],
+        :uint8 => ["C", 1],
+        :uint16 => ["S", 2],
+        :uint32 => ["L", 4],
+        :uint64 => ["Q", 8],
+        :float => ["f", 4],
+        :double => ["d", 8],
+        :char => ["a", 1],
+        :string => ["Z", 1],
+        :byte => ["C", 1],
+        :skip => ["a", 1],
+    }
+    
+    ##
+    # Holds compiled form structure.
+    #
+    
+    Compiled = Struct::new(
+        :enabled, :processors, :packing, :unpacking, :lengths, :length
+    )
+    
+    ##
+    # Constructor.
+    #
+    # @param [String] data raw string for unpack
+    # @param [Proc] block block with declaration
+    # @see #declare
+    #
+    
+    def initialize(data = nil, &block)
+        @stack = [ ]
+        self.declare(&block)
+        
+        if not data.nil?
+            self << data
+        end
+    end
+    
+    ##
+    # Receives declaration.
+    # 
+    # Adds declaration of bit array items. Can be call multiple times.
+    # New delcarations are joind to end of the array.
+    #
+    # @example
+    #   struct = StructFx::new("abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGHIJKLMOPQRSTUVWXYZ") do
+    #       int8 :n_int8
+    #       int16 :n_int16
+    #       int32 :n_int32
+    #       int64 :n_int64
+    #       uint8 :n_uint8
+    #       uint16 :n_uint16
+    #       uint32 :n_uint32
+    #       uint64 :n_uint64
+    #       skip {2}
+    #       float :n_float
+    #       double :n_double
+    #       char :n_char
+    #       string (:n_string) {3}
+    #       byte :n_flags do  # byte is usually length 8 bits
+    #           number (:n_number) {7}
+    #           boolean :n_boolean
+    #       end
+    #   end
+    #
+    # @param [Proc] block block with declaration
+    # @see TYPES
+    #
+
+    def declare(&block)
+        self.instance_eval(&block)
+    end
+
+    ##
+    # Handles missing methods as declarations.
+    #
+    # @param [Symbol] name data type of the entry
+    # @param [Array] args first argument is expected to be name
+    # @param [Proc] block block which returns length of the entry in bits
+    # @return [Integer] new length of the packed data
+    # @see #declare
+    #
+    
+    def method_missing(name, *args, &block)
+        if self.class::TYPES.include? name
+            self.add(args.shift, name, nil, block)
+        else
+            raise Exception::new("Invalid type/method specified: '" << name.to_s << "'")
+        end
+    end
+    
+    ##
+    # Returns compiled form.
+    # @return [Class] compiled form struct
+    #
+    
+    def compiled
+        if @compiled.nil?
+            @compiled = self.class::Compiled::new([], [], "", "", [], 0)
+            types = self.class::TYPES
+            
+            @stack.each do |name, type, args, block|
+                type_meta = types[type]
+                length = block.nil? ? 1 : block.call()
+                pack_char = type_meta[0] + length.to_s
+                total_length = type_meta[1] * length
+                
+                @compiled.enabled << (not name.nil?)
+                @compiled.processors << args
+                @compiled.packing << pack_char
+                @compiled.unpacking << pack_char
+                @compiled.lengths << total_length
+                @compiled.length += total_length
+            end
+            
+        end
+        
+        @compiled.enabled.freeze
+        @compiled.processors.freeze
+        @compiled.packing.freeze
+        @compiled.unpacking.freeze
+        @compiled.lengths.freeze
+
+        return @compiled.freeze
+    end
+    
+    ##
+    # Adds byte BitPacker declaration.
+    #
+    # @param [Symbol] name name of the entry
+    # @param [Proc] block declaration
+    # @see
+    #
+    
+    def byte(name, &block)
+        callback = Proc::new do |value|
+            BitPacker::new(value, &block)
+        end
+        
+        self.add(name, :byte, callback)
+    end
+    
+    ##
+    # Adds skipping declaration.
+    # @param [Proc] block with length
+    #
+    
+    def skip(&block)
+        self.add(nil, :skip, nil, block)
+    end
+    
+    ##
+    # Fills by input data.
+    # @param [Integer] value raw integer data for unpack
+    #
+    
+    def <<(value)
+        if value.bytesize < self.compiled.length
+            raise Exception::new("Data are shorter than declaration.")
+        end
+        
+        @raw = value.to_s
+        @data = nil
+    end
+    
+    ##
+    # Adds declaration.
+    #
+    # @param [Symbol] name name of the entry
+    # @param [Symbol] type type of the entry
+    # @param [Proc] callback postprocessing callback
+    # @param [Proc] block length declaration block
+    # 
+
+    def add(name, type, callback = nil, block = nil)
+        @stack << [name, type, callback, block]
+        @struct = nil
+        @compiled = nil
+    end
+    
+    ##
+    # Returns structure analyze.
+    # @return [Class] struct with the packed data
+    #
+    
+    def data
+        if @data.nil?
+            values = [ ]
+            compiled = self.compiled
+            extracted = @raw.unpack(compiled.unpacking)
+
+            compiled.enabled.each_index do |i|
+            
+                # Skips skipped items
+                if not compiled.enabled[i]
+                    next
+                end
+                
+                # Calls postprocessing if required
+                callback = compiled.processors[i]
+                if callback.nil?
+                    values << extracted[i]
+                else
+                    values << callback.call(extracted[i])
+                end
+                
+            end
+
+            @data = __struct::new(*values)
+        end
+        
+        return @data
+    end
+    
+    ##
+    # Returns total length of the struct in bytes.
+    # @return [Integer] total length of the declaration
+    #
+    
+    def length
+        self.compiled.length
+    end
+    
+    ##
+    # Converts to string.
+    # @return [String] resultant string according to current data state
+    #
+    
+    def to_s
+        entries = self.data.entries
+        compiled = self.compiled
+        
+        values = [ ]
+        length = 0
+        delta = 0
+        
+        compiled.enabled.each_index do |i|
+        
+            # Pastes skipped data from RAW
+            if not compiled.enabled[i]
+                from = length
+                to = (length + compiled.lengths[i])
+                values << @raw[from...to]
+                delta += 1
+            
+            # In otherwise, take value from analyzed data
+            else
+                values << entries[i - delta]    # current item minus count of non-entry (skipped) items
+            end
+        
+            length += self.compiled.lengths[i]
+        end
+
+        values.pack(self.compiled.packing)
+    end
+    
+    
+    protected 
+      
+    ##
+    # Returns data struct.
+    #
+
+    def __struct
+        if @struct.nil?
+            members = @stack.map { |i| i[0] }
+            members.compact!
+
+            @struct = Struct::new(*members)
+        end
+        
+        return @struct
+    end
+
+end

data/struct-fx.gemspec

@@ -0,0 +1,61 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{struct-fx}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Martin Kozák"]
+  s.date = %q{2011-03-02}
+  s.email = %q{martinkozak@martinkozak.net}
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md"
+  ]
+  s.files = [
+    ".document",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.md",
+    "Rakefile",
+    "VERSION",
+    "lib/struct-fx.rb",
+    "struct-fx.gemspec",
+    "test",
+    "test.gif"
+  ]
+  s.homepage = %q{http://github.com/martinkozak/struct-fx}
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.6.0}
+  s.summary = %q{Declarative pure Ruby equivalent of C/C++ structs.}
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<frozen-objects>, [">= 0.2.0"])
+      s.add_runtime_dependency(%q<bit-packer>, [">= 0.1.0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_development_dependency(%q<riot>, [">= 0.12.1"])
+    else
+      s.add_dependency(%q<frozen-objects>, [">= 0.2.0"])
+      s.add_dependency(%q<bit-packer>, [">= 0.1.0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_dependency(%q<riot>, [">= 0.12.1"])
+    end
+  else
+    s.add_dependency(%q<frozen-objects>, [">= 0.2.0"])
+    s.add_dependency(%q<bit-packer>, [">= 0.1.0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+    s.add_dependency(%q<riot>, [">= 0.12.1"])
+  end
+end
+

data/test

@@ -0,0 +1,103 @@
+#!/usr/bin/ruby
+# encoding: utf-8
+# (c) 2011 Martin Kozák (martinkozak@martinkozak.net)
+
+$:.push("./lib")
+require "struct-fx"
+require "riot"
+
+context "StructFx (development)" do
+    setup do 
+        StructFx::new("abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGHIJKLMOPQRSTUVWXYZ") do
+            int8 :n_int8
+            int16 :n_int16
+            int32 :n_int32
+            int64 :n_int64
+            uint8 :n_uint8
+            uint16 :n_uint16
+            uint32 :n_uint32
+            uint64 :n_uint64
+            skip {2}
+            float :n_float
+            double :n_double
+            char :n_char
+            string (:n_string) {3}
+            byte :n_flags do
+                number (:n_number) {7}
+                boolean :n_boolean
+            end
+        end
+    end
+    
+    asserts("correct unpacking") do
+        result = true
+        
+        result &= (topic.data.n_int8 == 97)
+        result &= (topic.data.n_int16 == 25442)
+        result &= (topic.data.n_int32 == 1734763876)
+        result &= (topic.data.n_int64 == 8029475498074204520)
+        result &= (topic.data.n_uint8 == 112)
+        result &= (topic.data.n_uint16 == 29297)
+        result &= (topic.data.n_uint32 == 1987409011)
+        result &= (topic.data.n_uint64 == 3689065129052829815)
+        result &= (topic.data.n_float == 0.00017568175098858774)
+        result &= (topic.data.n_double == 1.5839800103804824e+40)
+        result &= (topic.data.n_char == ?I)
+        result &= (topic.data.n_string == "JKL")
+        
+        result &= (topic.data.n_flags.data.n_number == 38)
+        result &= (topic.data.n_flags.data.n_boolean == true)
+    end
+    
+    asserts("correct packing") do
+        topic.to_s == "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGHIJKLM"
+    end
+    
+    asserts("correct length") do
+        topic.length == 49
+    end
+    
+    asserts("length failure") do
+        begin
+            StructFx::new("a") do
+                int16 :n_int16
+            end
+        rescue Exception => e
+            e.message == "Data are shorter than declaration."
+        end
+    end
+end
+
+context "StructFx (real-life)" do
+    setup do
+        data = nil
+        File.open("./test.gif", "rb") do |io|
+            data = io.read(10)
+        end
+
+        gif = StructFx::new(data) do
+            string (:gif) {3}
+            string (:version) {3}
+            uint16 :width
+            uint16 :height
+        end   
+    end
+    
+    asserts("GIF header unpacking") do
+        result = true
+        
+        result &= (topic.data.gif == "GIF")
+        result &= (topic.data.version == "89a")
+        result &= (topic.data.width == 32)
+        result &= (topic.data.height == 32)
+    end
+    
+    asserts("GIF header packing") do
+        topic.data.width = 128
+        topic.data.height = 128
+        topic.data.version = "87a"
+        
+        topic.to_s.force_encoding("ASCII") == "GIF87a\x80\x00\x80\x00".force_encoding("ASCII")
+    end
+
+end

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification 
+name: struct-fx
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.0
+platform: ruby
+authors: 
+- "Martin Koz\xC3\xA1k"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-03-02 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: frozen-objects
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: bit-packer
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: jeweler
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.5.2
+  type: :development
+  prerelease: false
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: riot
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.12.1
+  type: :development
+  prerelease: false
+  version_requirements: *id005
+description: 
+email: martinkozak@martinkozak.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- README.md
+files: 
+- .document
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- VERSION
+- lib/struct-fx.rb
+- struct-fx.gemspec
+- test
+- test.gif
+has_rdoc: true
+homepage: http://github.com/martinkozak/struct-fx
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 2568357356524022812
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.0
+signing_key: 
+specification_version: 3
+summary: Declarative pure Ruby equivalent of C/C++ structs.
+test_files: []
+