packable 1.2.0

data/CHANGELOG.rdoc

@@ -0,0 +1,13 @@
+= Packable --- History
+
+== Version 1.2 - April 2nd, 2009
+Compatible with ruby 1.9.1.
+The 'jungle_survival_kit' is now in its own 'backports' gem.
+
+== Version 1.1 - December 17, 2008
+Fixed bug when packing objects implementing to_ary
+Added inheritance of shortcuts & filters to documentation
+
+== Version 1.0 - December 17, 2008
+
+=== Initial release.

data/LICENSE

@@ -0,0 +1,26 @@
+# packable library
+# Copyright (c) 2008, Marc-André Lafortune.
+# All rights reserved.
+# Licensed under the terms of the (modified) BSD License below:
+#
+# 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 author 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 AUTHOR ''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 THE AUTHOR 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.rdoc

@@ -0,0 +1,246 @@
+= Packable Library - Intro
+
+If you need to do read and write binary data, there is of course <tt>Array::pack</tt> and <tt>String::unpack</tt>.
+The packable library makes (un)packing nicer, smarter and more powerful.
+In case you are wondering why on earth someone would want to do serious (un)packing when YAML & XML are built-in:
+I wrote this library to read and write FLV files...
+
+== Feature summary:
+
+=== Explicit forms
+Strings, integers & floats have long forms instead of the cryptic letter notation. For example:
+    ["answer", 42].pack("C3n")
+can be written as:
+    ["answer", 42].pack({:bytes => 3}, {:bytes => 2, :endian => :big})
+This can look a bit too verbose, so let's introduce shortcuts right away:
+=== Shortcuts
+Most commonly used options have shortcuts and you can define your own. For example:
+    :unsigned_long  <===> {:bytes => 4, :signed => false, :endian => :big}
+=== IO
+IO classes (File & StringIO) can use (un)packing routines.
+For example:
+    signature, block_len, temperature = my_file >> [String, :bytes=>3] >> Integer >> :float
+The method +each+ also accepts packing options:
+    StringIO.new("\000\001\000\002\000\003").each(:short).to_a  ===>  [1,2,3]
+=== Custom classes
+It's easy to make you own classes (un)packable. All the previous goodies are thus available:
+		File.open("great_flick.flv") do |f|
+			head = f.read(FLV::Header)
+			f.each(FLV::Tag) do |tag|
+				# do something meaningful with each tag...
+			end
+		end
+
+=== Filters
+It's also easy to define special shortcuts that will call blocks to (un)pack any classe.
+As an example, this could be useful to add special packing features to String (without monkey patching String::pack).
+
+== Installation
+
+First, ensure that you're running at least RubyGems 1.2 (check <tt>gem --version</tt> if you're not sure -- to update: <tt>sudo gem update --system</tt>).
+
+Add GitHub to your gem sources (if you haven't already):
+
+  sudo gem sources -a http://gems.github.com
+
+Get the gem:
+
+  sudo gem install marcandre-packable
+  
+That's it! Simply <tt>require 'packable'</tt> in your code to use it.
+
+== Compatibility
+
+Designed to work with ruby 1.8 & 1.9.
+
+= Documentation
+
+== Packing and unpacking
+
+The library was designed to be backward compatible, so the usual packing and unpacking methods still work as before.
+All packable objects can also be packed directly (no need to use an array). For example:
+
+  42.pack("n")  ===>  "\000*"
+
+In a similar fashion, unpacking can done using class methods:
+
+  Integer.unpack("\000*", "n")  ===>  42
+
+== Formats
+
+Although the standard string formats can still be used, it is possible to pass a list of options (see example in feature summary).
+These are the options for core types:
+
+=== Integer
+[+bytes+]     Number of bytes (default is 4) to use.
+[+endian+]    Either <tt>:big</tt> (or :network, default) or <tt>:little</tt>.
+[+signed+]    Either +true+ (default) or +false+. This will make a difference only when unpacking.
+
+=== Float
+[+precision+] Either <tt>:single</tt> (default) or <tt>:double</tt>.
+[+endian+]    Either <tt>:big</tt> (or :network, default) or <tt>:little</tt>.
+
+=== String
+[+bytes+]     Total length (default is the full length)
+[+fill+]      The string to use for filling when packing a string shorter than the specified bytes option. Default is a space.
+
+=== Array
+[+repeat+]    This option can be used (when packing only) to repeat the current option. A value of <tt>:all</tt> will mean for all remaining elements of the array.
+
+When unpacking, it is necessary to specify the class in addition to any option, like so:
+
+  "AB".unpack(Integer, :bytes => 2, :endian => :big, :signed => false)  ===>  0x3132
+
+== Shortcuts and default values
+
+It's easy to add shortcuts for easier (un)packing:
+
+	String.packers.set :flv_signature, :bytes => 3, :fill => "FLV"
+
+  "x".pack(:flv_signature)  ===>  "xFL"
+
+Two shortcut names have special meanings: +default+ and +merge_all+. +default+ specifies the options to use when
+nothing is specified, while +merge_all+ will be merged with all options. For example:
+
+  String.packers do |p|
+    p.set :merge_all, :fill => "*"	# Unless explicitly specified, :fill will now be "*"
+    p.set :default, :bytes => 8     # If no option is given, this will act as default
+  end
+
+  "ab".pack  ===>  "ab******"
+  "ab".pack(:bytes=>4)  ===>  "ab**"
+  "ab".pack(:fill => "!")  ===>  "ab"     # Not "ab!!"
+
+A shortcut can refer to another shortcut, as so:
+
+  String.packers do |p|
+		p.set :creator, :bytes => 4
+		p.set :app_type, :creator
+	end
+  "hello".pack(:app_type)  ===>  "hell"
+
+The following shortcuts and defaults are built-in the library:
+
+=== Integer
+  :merge_all      =>   :bytes=>4, :signed=>true, :endian=>:big
+  :default        =>   :long
+  :long           =>   {}
+  :short          =>   :bytes=>2
+  :byte           =>   :bytes=>1
+  :unsigned_long  =>   :bytes=>4, :signed=>false
+  :unsigned_short =>   :bytes=>2, :signed=>false
+                       
+=== Float              
+  :merge_all      =>   :precision => :single, :endian => :big
+  :default        =>   :float
+  :double         =>   :precision => :double
+  :float          =>   {}
+                       
+=== String             
+  :merge_all      =>   :fill => " "
+
+== Files and StringIO
+
+All IO objects (in particular files) can deal with packing easily. These examples will all return an array with 3 elements (a string, an integer and another string):
+
+  io >> :flv_signature >> Integer >> [String, {:bytes => 8}]
+  io.read(:flv_signature, Integer, [String, {:bytes => 8}])
+  io.read(:flv_signature, Integer, String, {:bytes => 8})
+  [io.read(:flv_signature), io.read(Integer), io.read(String, :bytes => 8)]
+
+In a similar fashion, these have the same effect although the return value is different
+
+  io << "x".pack(:flv_signature) << 66.pack << "Hello".pack(:bytes => 8)  # returns io
+  io << ["x", 66, "Hello"].pack(:flv_signature, {} , {:bytes => 8})       # returns io
+  io.write("x", :flv_signature, 66, "Hello", {:bytes => 8})               # returns the # of bytes written
+  io.packed << ["x",:flv_signature] << 66 << ["Hello", {:bytes => 8}]     # returns a "packed io"
+
+The last example shows how <tt>io.packed</tt> returns a special IO object (a packing IO) that will pack arguments before writing it.
+This is to insure compatibility with the usual behavior of IO objects:
+	io << 66  ==> appends "66"
+	io.packed << 66  ==> appends "\000\000\000B"
+
+We "cheated" in the previous example; instead of writing <tt>io.packed.write(...)</tt> we used the shorter form.
+This works because we're passing more than one argument; for only one argument we must call <tt>io.packed.write(66)</tt>
+less the usual +write+ method is called.
+
+Since the standard library desn't define the <tt>>></tt> operator for IO objects, we are free to use either <tt>io.packed</tt> or <tt>io</tt> directly.
+Note that reading one value only will return that value directly, not an array containing that value:
+
+  io.read(Integer)  ===>  42, not [42]
+  io.read(Integer,Integer)  ===>  [42,43]
+  io << Integer     ===>  [42]
+
+== Custom classes
+
+Including the mixin +Packable+ will make a class (un)packable. Packable relies on +write_packed+
+and unpacking on +read_packed+. For example:
+
+  class MyHeader < Struct.new(:signature, :nb_blocks)
+    include Packable
+  
+    def write_packed(packedio, options)
+      packedio << [signature, {:bytes=>3}] << [nb_blocks, :short]
+    end
+
+    def self.read_packed(packedio, options)
+      h = MyHeader.new
+      h.signature, h.nb_blocks = packedio >> [String, {:bytes => 3}] >> :short
+      h
+    end
+  end
+
+We used the argument name +packedio+ to remind us that these are packed IO objects, i.e.
+they will write their arguments after packing them instead of converting them to string like normal IO objects.
+With this definition, +MyHeader+ can be both packed and unpacked:
+
+  h = MyHeader.new("FLV", 65)
+  h.pack  ===>  "FLV\000A"
+  StringIO.new("FLV\000A") >> Signature  ===>  [a copy of h]
+
+A default <tt>self.read_packed</tt> is provided by the +Packable+ mixin, which allows you to define +read_packed+ as
+an instance method instead of a class method. In that case, +read_packed+ instance method is called with
+the same arguments and should modify +self+ accordingly (instead of returning a new object).
+It is not necessary to return +self+. The previous example can thus be shortened:
+
+  class MyHeader
+    #...
+    def read_packed(packedio, options)
+      self.signature, self.nb_blocks = packedio >> [String, {:bytes => 3}] >> :short
+    end
+  end
+
+== Filter
+
+Instead of writing a full-fledge class, sometimes it can be convenient to define a sort of wrapper we'll call filter. Here's an example:
+
+  String.packers.set :length_encoded do |packer|
+    packer.write  { |packedio| packedio << length << self }
+    packer.read   { |packedio| packedio.read(packedio.read(Integer)) }
+  end
+
+	"hello!".pack(:length_encoded)  ===>  "\000\000\000\006hello!"
+	["this", "is", "great!"].pack(*[:length_encoded]*3).unpack(*[:length_encoded]*3)  ===>  ["this", "is", "great!"]
+
+Note that the +write+ block will be executed as an instance method (which is why we could use +length+ & +self+),
+while +read+ is a normal block that must return the newly read object.
+
+== Inheritance
+
+A final note to say that packers are inherited in some way. For instance one could define a filter for all objects:
+
+  Object.packers.set :with_class do |packer|
+    packer.write { |io| io << [self.class.name, :length_encoded] << self }
+    packer.read  do |io|
+      klass = eval(io.read(:length_encoded))
+      io.read(klass)
+    end
+  end
+  
+  [42, MyHeader.new("Wow", 1)].pack(:with_class, :with_class).unpack(:with_class, :with_class) ===> [42, MyHeader.new("Wow", 1)]
+
+= License
+
+packable is licensed under the terms of the (modified) BSD License, see the included LICENSE file.
+
+Author::                 Marc-André Lafortune

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:patch: 0
+:major: 1
+:minor: 2

data/lib/packable.rb

@@ -0,0 +1,9 @@
+require 'rubygems'
+require 'backports'
+require_relative 'packable/packers'
+require_relative 'packable/mixin'
+[Object, Array, String, Integer, Float, IO, Proc].each do |klass|
+  require_relative 'packable/extensions/' + klass.name.downcase
+  klass.class_eval { include Packable::Extensions.const_get(klass.name) }
+end
+StringIO.class_eval { include Packable::Extensions::IO } # Since StringIO doesn't inherit from IO

data/lib/packable/extensions/array.rb

@@ -0,0 +1,47 @@
+require 'stringio'
+
+module Packable
+  module Extensions #:nodoc:
+    module Array #:nodoc:
+      def self.included(base)
+        base.class_eval do
+          alias_method_chain :pack, :long_form
+          include Packable
+          extend ClassMethods
+        end
+      end
+
+      def pack_with_long_form(*arg)
+        return pack_without_long_form(*arg) if arg.first.is_a? String
+        pio = StringIO.new.packed
+        write_packed(pio, *arg)
+        pio.string
+      end
+
+      def write_packed(io, *how)
+        return io << self.original_pack(*how) if how.first.is_a? String
+        how = [:repeat => :all] if how.empty?
+        current = -1
+        how.each do |options|
+          repeat = options.is_a?(Hash) ? options.delete(:repeat) || 1 : 1
+          repeat = length - 1 - current if repeat == :all
+          repeat.times do
+            io.write(self[current+=1],options)
+          end
+        end
+      end
+
+      module ClassMethods #:nodoc:
+        def read_packed(io, *how)
+          raise "Can't support builtin format for arrays" if (how.length == 1) && (how.first.is_a? String)
+          how.inject [] do |r, options|
+            repeat = options.is_a? Hash ? options.delete(:repeat) || 1 : 1
+            (0...repeat).inject r do
+              r << io.read(options)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/packable/extensions/float.rb

@@ -0,0 +1,37 @@
+module Packable
+  module Extensions #:nodoc:
+    module Float #:nodoc:
+      def self.included(base)
+        base.class_eval do
+          include Packable
+          extend ClassMethods
+          packers do |p|
+            p.set :merge_all, :precision => :single, :endian => :big
+            p.set :double   , :precision => :double
+            p.set :float    , {}
+            p.set :default  , :float
+          end
+        end
+      end
+      
+      def write_packed(io, options)
+        io << pack(self.class.pack_option_to_format(options))
+      end
+
+      module ClassMethods #:nodoc:
+        def pack_option_to_format(options)
+          format = {:big => "G", :network => "G", :little => "E"}[options[:endian]]
+          format.downcase! if options[:precision] == :single
+          format
+        end
+
+        def read_packed(io, options)
+          io.read({:single => 4, :double => 8}[options[:precision]])   \
+            .unpack(pack_option_to_format(options))   \
+            .first
+        end
+      end
+      
+    end
+  end
+end

data/lib/packable/extensions/integer.rb

@@ -0,0 +1,44 @@
+module Packable
+  module Extensions #:nodoc:
+    module Integer #:nodoc:
+      def self.included(base)
+        base.class_eval do
+          include Packable
+          extend ClassMethods
+          packers do |p|
+            p.set :merge_all      , :bytes=>4, :signed=>true, :endian=>:big
+            p.set :default        , :long
+            p.set :long           , {}
+            p.set :short          , :bytes=>2
+            p.set :char           , :bytes=>1, :signed=>false
+            p.set :byte           , :bytes=>1
+            p.set :unsigned_long  , :bytes=>4, :signed=>false
+            p.set :unsigned_short , :bytes=>2, :signed=>false
+          end
+        end
+      end
+
+      def write_packed(io, options)
+        val = self
+        chars = (0...options[:bytes]).collect do
+          byte = val & 0xFF
+          val >>= 8
+          byte.chr
+        end
+        chars.reverse! unless options[:endian] == :little
+        io << chars.join
+      end
+
+      module ClassMethods #:nodoc:
+        def unpack_string(s,options)
+          s = s.reverse if options[:endian] == :little
+          r = 0
+          s.each_byte {|b| r = (r << 8) + b}
+          r -= 1 << (8 * options[:bytes])  if options[:signed] && (1 == r >> (8 * options[:bytes] - 1))
+          r
+        end
+      end
+
+    end
+  end
+end

data/lib/packable/extensions/io.rb

@@ -0,0 +1,96 @@
+require 'enumerator'
+Enumerator = Enumerable::Enumerator unless defined?(Enumerator)
+
+module Packable
+  module Extensions #:nodoc:
+    module IO
+      def self.included(base) #:nodoc:
+        base.alias_method_chain :read, :packing
+        base.alias_method_chain :write, :packing
+        base.alias_method_chain :each, :packing
+        attr_accessor :throw_on_error
+      end
+      
+      # Returns the change in io.pos caused by the block.
+      # Has nothing to do with packing, but quite helpful and so simple...
+      def pos_change(&block)
+        delta =- pos
+        yield
+        delta += pos
+      end
+
+      # Usage:
+      #   io >> Class
+      #   io >> [Class, options]
+      #   io >> :shortcut
+      def >> (options)
+        r = []
+        class << r
+          attr_accessor :stream
+          def >> (options)
+            self << stream.read(options)
+          end
+        end
+        r.stream = self
+        r >> options
+      end
+      
+      # Returns (or yields) a modified IO object that will always pack/unpack when writing/reading.
+      def packed
+        packedio = clone
+        packedio.set_encoding("ascii-8bit") if packedio.respond_to? :set_encoding 
+        class << packedio
+          def << (arg)
+            arg = [arg, :default] unless arg.instance_of?(::Array)
+            pack_and_write(*arg)
+            self
+          end
+          def packed
+            block_given? ? yield(self) : self
+          end
+          alias_method :write, :pack_and_write #bypass test for argument length
+        end
+        block_given? ? yield(packedio) : packedio
+      end
+
+      def each_with_packing(*options, &block)
+        return each_without_packing(*options, &block) if (Integer === options.first) || (String === options.first)
+        return Enumerator.new(self, :each_with_packing, *options) unless block_given?
+        yield read(*options) until eof?
+      end
+
+      def write_with_packing(*arg)
+        (arg.length == 1) ? write_without_packing(*arg) : pack_and_write(*arg)
+      end
+    
+      def read_with_packing(*arg)
+        return read_without_packing(*arg) if (arg.length == 0) || (arg.first.is_a?(Numeric) && (arg.length == 1))
+        values = Packable::Packers.to_class_option_list(*arg).map do |klass, options, original|
+          if eof?
+            raise EOFError, "End of IO when attempting to read #{klass} with options #{original.inspect}" if @throw_on_eof
+            nil
+          elsif options[:read_packed]
+            options[:read_packed].call(self)
+          else
+            klass.read_packed(self, options)
+          end
+        end
+        return values.size > 1 ? values : values.first
+      end
+      
+      def pack_and_write(*arg)
+        original_pos = pos
+        Packable::Packers.to_object_option_list(*arg).each do |obj, options|
+          if options[:write_packed]
+            options[:write_packed].bind(obj).call(self)
+          else
+            obj.write_packed(self, options)
+          end
+        end
+        pos - original_pos
+      end
+
+    
+    end
+  end
+end

data/lib/packable/extensions/object.rb

@@ -0,0 +1,14 @@
+module Packable
+  module Extensions #:nodoc:
+    module Object #:nodoc:
+      def self.included(base) #:nodoc:
+        base.class_eval do
+          class << self
+            # include only packers method into Object
+            include PackersClassMethod
+          end
+        end
+      end
+    end
+  end
+end

data/lib/packable/extensions/proc.rb

@@ -0,0 +1,16 @@
+module Packable
+  module Extensions #:nodoc:
+    module Proc
+      # A bit of wizardry to return an +UnboundMethod+ which can be bound to any object
+      def unbind
+        Object.send(:define_method, :__temp_bound_method, &self)
+        Object.instance_method(:__temp_bound_method)
+      end
+      
+      # Shortcut for <tt>unbind.bind(to)</tt>
+      def bind(to)
+        unbind.bind(to)
+      end
+    end
+  end
+end

data/lib/packable/extensions/string.rb

@@ -0,0 +1,34 @@
+require 'stringio'
+
+module Packable
+  module Extensions #:nodoc:
+    module String #:nodoc:
+
+      def self.included(base)
+        base.class_eval do
+          include Packable
+          extend ClassMethods
+          alias_method_chain :unpack, :long_form
+          packers.set :merge_all, :fill => " "
+        end
+      end
+
+      def write_packed(io, options)
+        return io.write_without_packing(self) unless options[:bytes]
+        io.write_without_packing(self[0...options[:bytes]].ljust(options[:bytes], options[:fill] || "\000"))
+      end
+
+      def unpack_with_long_form(*arg)
+        return unpack_without_long_form(*arg) if arg.first.is_a? String
+        StringIO.new(self).packed.read(*arg)
+      end
+
+      module ClassMethods #:nodoc:
+        def unpack_string(s, options)
+          s
+        end
+      end
+
+    end
+  end
+end

data/lib/packable/mixin.rb

@@ -0,0 +1,57 @@
+# The Packable mixin itself...
+
+require 'stringio'
+
+module Packable
+  def self.included(base) #:nodoc:
+    base.class_eval do
+      class << self 
+        include PackersClassMethod
+        include ClassMethods
+      end
+    end
+  end
+
+  # +options+ can be a Hash, a shortcut (Symbol) or a String (old-style)
+  def pack(options = :default)
+    return [self].pack(options) if options.is_a? String
+    (StringIO.new.packed << [self, options]).string
+  end
+
+  module PackersClassMethod
+    # Returns or yields a the Packers.for(class)
+    # Normal use is packers.set ...
+    # (see docs or Packers::set for usage)
+    def packers
+      yield packers if block_given?
+      Packers.for(self) 
+    end
+  end
+
+  module ClassMethods    
+    def unpack(s, options = :default)
+      return s.unpack(options).first if options.is_a? String
+      StringIO.new(s).packed.read(self, options)
+    end
+ 
+    # Default +read_packed+ calls either the instance method <tt>read_packed</tt> or the 
+    # class method +unpack_string+. Choose:
+    # * define a class method +read_packed+ that returns the newly read object
+    # * define an instance method +read_packed+ which reads the io into +self+
+    # * define a class method +unpack_string+ that reads and returns an object from the string. In this case, options[:bytes] should be specified!
+    def read_packed(io, options)
+      if method_defined? :read_packed
+        mandatory = instance_method(:initialize).arity
+        mandatory = -1-mandatory if mandatory < 0
+        obj = new(*[nil]*mandatory)
+        obj.read_packed(io, options)
+        obj
+      else
+        len = options[:bytes]
+        s = len ? io.read(len) : io.read
+        unpack_string(s, options)
+      end
+    end
+
+  end  
+end

data/lib/packable/packers.rb

@@ -0,0 +1,107 @@
+module Packable
+  
+  # Packers for any packable class.
+  class Packers < Hash
+    SPECIAL = [:default, :merge_all].freeze
+  
+    # Usage:
+    #   PackableClass.packers.set :shortcut, :option => value, ...
+    #   PackableClass.packers { |p| p.set...; p.set... }
+    #   PackableClass.packers.set :shortcut, :another_shortcut
+    #   PackableClass.packers.set :shortcut do |packer|
+    #     packer.write{|io| io << self.something... }
+    #     packer.read{|io| Whatever.new(io.read(...)) }
+    #   end
+    def set(key, options_or_shortcut={})
+      if block_given?
+        packer = FilterCapture.new options_or_shortcut
+        yield packer
+      end
+      self[key] = options_or_shortcut
+      self
+    end
+
+    def initialize(klass) #:nodoc:
+      @klass = klass
+    end
+
+    def lookup(key) #:nodoc:
+      k = @klass
+      begin
+        if found = Packers.for(k)[key]
+          return found
+        end
+        k = k.superclass
+      end while k
+      SPECIAL.include?(key) ? {} : raise("Unknown option #{key} for #{@klass}")
+    end
+
+    def finalize(options) #:nodoc:
+      options = lookup(options) while options.is_a? Symbol
+      lookup(:merge_all).merge(options)
+    end
+
+    @@packers_for_class = Hash.new{|h, klass| h[klass] = Packers.new(klass)}
+    
+    # Returns the configuration for the given +klass+.
+    def self.for(klass)
+      @@packers_for_class[klass]
+    end
+
+    def self.to_class_option_list(*arg) #:nodoc:
+      r = []
+      until arg.empty? do
+        k, options = original = arg.shift
+        k, options = global_lookup(k) if k.is_a? Symbol
+        raise TypeError, "Expected a class or symbol: #{k.inspect}" unless k.instance_of? Class
+        options ||= arg.first.is_a?(Hash) ? arg.shift.tap{|o| original = [original, o]} : :default
+        r << [k, k.packers.finalize(options), original]
+      end
+      r
+    end
+    
+    def self.to_object_option_list(*arg) #:nodoc:
+      r=[]
+      until arg.empty? do
+        obj = arg.shift
+        options = case arg.first
+        when Hash, Symbol
+          arg.shift
+        else
+          :default
+        end
+        r << [obj, obj.class.packers.finalize(options)]
+      end
+      r
+    end
+
+  private
+    def self.global_lookup(key) #:nodoc:
+      @@packers_for_class.each do |klass, packers|
+        if options = packers[key]
+          return [klass, options]
+        end
+      end
+      raise "Couldn't find packing option #{key}"
+    end
+
+    
+  end
+
+  # Use to capture the blocks given to read/write
+  class FilterCapture #:nodoc:
+    attr_accessor :options
+    def initialize(options)
+      self.options = options
+    end
+
+    def read(&block)
+      options[:read_packed] = block
+    end
+
+    def write(&block)
+      options[:write_packed] = block.unbind
+    end
+  end
+    
+end

data/test/packing_doc_test.rb

@@ -0,0 +1,106 @@
+require File.dirname(__FILE__) + '/test_helper'
+# Warning: ugly...
+class MyHeader < Struct.new(:signature, :nb_blocks)
+  include Packable
+  
+  def write_packed(packedio, options)
+    packedio << [signature, {:bytes=>3}] << [nb_blocks, :short]
+  end
+
+  def read_packed(packedio, options)
+    self.signature, self.nb_blocks = packedio >> [String, {:bytes => 3}] >> :short
+  end
+  
+  def ohoh
+    :ahah
+  end
+end
+
+
+class PackableDocTest < Test::Unit::TestCase 
+  def test_doc
+
+    assert_equal  [1,2,3], StringIO.new("\000\001\000\002\000\003").each(:short).to_a
+
+
+  	String.packers.set :flv_signature, :bytes => 3, :fill => "FLV"
+
+    assert_equal "xFL", "x".pack(:flv_signature)
+
+    String.packers do |p|
+      p.set :merge_all, :fill => "*"	# Unless explicitly specified, :fill will now be "*"
+      p.set :default, :bytes => 8     # If no option is given, this will act as default
+    end
+    
+    assert_equal "ab******", "ab".pack
+    assert_equal "ab**", "ab".pack(:bytes=>4)
+    assert_equal "ab", "ab".pack(:fill => "!")
+    assert_equal "ab!!", "ab".pack(:fill => "!", :bytes => 4)
+    
+    String.packers do |p|
+  		p.set :creator, :bytes => 4
+  		p.set :app_type, :creator
+  		p.set :default, {} # Reset to a sensible default...
+      p.set :merge_all, :fill => " "
+      p.set :eigth_bytes, :bytes => 8
+  	end
+    
+    assert_equal "hello".pack(:app_type), "hell"
+    
+    assert_equal [["sig", 1, "hello, w"]]*4,
+    [
+    lambda { |io| io >> :flv_signature >> Integer >> [String, {:bytes => 8}]                     },
+    lambda { |io| io.read(:flv_signature, Integer, [String, {:bytes => 8}])                      },
+    lambda { |io| io.read(:flv_signature, Integer, String, {:bytes => 8})                        },
+    lambda { |io| [io.read(:flv_signature), io.read(Integer), io.read(String, {:bytes => 8})]    }
+    ].map {|proc| proc.call(StringIO.new("sig\000\000\000\001hello, world"))}
+    
+    
+    ex = "xFL\000\000\000BHello   "
+    [
+    lambda { |io| io << "x".pack(:flv_signature) << 66.pack << "Hello".pack(:bytes => 8)},   # returns io
+    lambda { |io| io << ["x", 66, "Hello"].pack(:flv_signature, :default , {:bytes => 8})},  # returns io
+    lambda { |io| io.write("x", :flv_signature, 66, "Hello", {:bytes => 8})             },   # returns the # of bytes written
+    lambda { |io| io.packed << ["x",:flv_signature] << 66 << ["Hello", {:bytes => 8}]   }    # returns  io.packed
+    ].zip([StringIO, StringIO, ex.length, StringIO.new.packed.class]) do |proc, compare|
+      ios = StringIO.new
+      assert_operator compare, :===, proc.call(ios)
+      ios.rewind
+      assert_equal ex, ios.read, "With #{proc}"
+    end
+    
+    #insure StringIO class is not affected
+    ios = StringIO.new
+    ios.packed
+    ios << 66
+    ios.rewind
+    assert_equal "66", ios.read
+    
+    
+    String.packers.set :length_encoded do |packer|
+      packer.write  { |io| io << length << self }
+      packer.read   { |io| io.read(io.read(Integer)) }
+    end
+    
+    assert_equal "\000\000\000\006hello!", "hello!".pack(:length_encoded)
+    assert_equal ["this", "is", "great!"], ["this", "is", "great!"].pack(*[:length_encoded]*3).unpack(*[:length_encoded]*3)
+  
+    h = MyHeader.new("FLV", 65)
+    assert_equal "FLV\000A", h.pack
+    h2, = StringIO.new("FLV\000A") >> MyHeader
+    assert_equal h, h2
+    assert_equal h.ohoh, h2.ohoh
+
+
+  
+    Object.packers.set :with_class do |packer|
+      packer.write { |io| io << [self.class.name, :length_encoded] << self }
+      packer.read  do |io|
+        klass = eval(io.read(:length_encoded))
+        io.read(klass)
+      end
+    end
+    ar = [42, MyHeader.new("FLV", 65)]
+    assert_equal ar, ar.pack(:with_class, :with_class).unpack(:with_class, :with_class)
+  end
+end

data/test/packing_test.rb

@@ -0,0 +1,93 @@
+require File.dirname(__FILE__) + '/test_helper'
+# Warning: ugly...
+
+class XYZ
+  include Packable
+  def write_packed(io, options)
+    io << "xyz"
+  end
+  def self.unpack_string(s, options)
+    raise "baddly packed XYZ: #{s}" unless "xyz" == s
+    XYZ.new
+  end
+end
+
+class TestingPack < Test::Unit::TestCase
+  
+  context "Original form" do
+    should "pack like before" do
+      assert_equal "a  \000\000\000\001", ["a",1,66].pack("A3N")
+    end
+
+    should "be equivalent to new form" do
+      assert_equal ["a",1,2.34, 66].pack({:bytes=>3}, {:bytes=>4, :endian=>:big}, {:precision=>:double, :endian=>:big}), ["a",1,2.34, 66].pack("A3NG")
+    end
+  end
+  
+  def test_shortcuts
+    assert_equal 0x123456.pack(:short), 0x123456.pack(:bytes => 2)
+    assert_equal 0x3456, 0x123456.pack(:short).unpack(:short)
+  end
+  
+  def test_custom_form
+    assert_equal "xyz", XYZ.new.pack 
+    assert_equal XYZ, "xyz".unpack(XYZ).class
+  end
+  
+  def test_pack_default
+    assert_equal "\000\000\000\006", 6.pack
+    assert_equal "abcd", "abcd".pack
+    assert_equal "\000\000\000\006abcd", [6,"abcd"].pack
+    String.packers.set :flv_signature, :bytes => 3, :fill => "FLV"
+    assert_equal "xFL", "x".pack(:flv_signature)
+  end
+  
+  def test_integer
+    assert_equal "\002\001\000", 258.pack(:bytes => 3, :endian => :little)
+    assert_equal 258, Integer.unpack("\002\001\000", :bytes => 3, :endian => :little)
+    assert_equal (1<<24)-1, -1.pack(:bytes => 3).unpack(Integer, :bytes => 3, :signed => false)
+    assert_equal -1, -1.pack(:bytes => 3).unpack(Integer, :bytes => 3, :signed => true)
+  end
+  
+  def test_io
+    io = StringIO.new("\000\000\000\006abcdE!")
+    n, s, c = io >> [Fixnum, {:signed=>false}] >> [String, {:bytes => 4}] >> :char
+    assert_equal 6, n
+    assert_equal "abcd", s
+    assert_equal 69, c
+    assert_equal "!", io.read
+  end
+  
+  should "do basic type checking" do
+    assert_raise(TypeError) {"".unpack(42, :short)}
+  end
+  
+  context "Filters" do
+    context "for Object" do
+      Object.packers.set :generic_class_writer do |packer|
+        packer.write do |io|
+          io << self.class.name << self
+        end
+      end
+      should "be follow accessible everywhere" do
+        assert_equal "StringHello", "Hello".pack(:generic_class_writer)
+        assert_equal "Fixnum\000\000\000\006", 6.pack(:generic_class_writer)
+      end
+    end
+    context "for a specific class" do
+      String.packers.set :specific_writer do |packer|
+        packer.write do |io|
+          io << "Hello"
+        end
+      end
+
+      should "be accessible only from that class and descendants" do
+        assert_equal "Hello", "World".pack(:specific_writer)
+        assert_raise RuntimeError do
+          6.pack(:specific_writer)
+        end
+      end
+    end
+  end
+    
+end

data/test/test_helper.rb

@@ -0,0 +1,8 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+require 'mocha'
+require File.dirname(__FILE__)+'/../lib/packable'
+
+class Test::Unit::TestCase
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification 
+name: packable
+version: !ruby/object:Gem::Version 
+  version: 1.2.0
+platform: ruby
+authors: 
+- "Marc-Andr\xC3\xA9 Lafortune"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-04-03 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: marcandre-backports
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: If you need to do read and write binary data, there is of course <Array::pack and String::unpack The packable library makes (un)packing nicer, smarter and more powerful.
+email: github@marc-andre.ca
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+- LICENSE
+files: 
+- CHANGELOG.rdoc
+- README.rdoc
+- VERSION.yml
+- lib/packable
+- lib/packable/extensions
+- lib/packable/extensions/array.rb
+- lib/packable/extensions/float.rb
+- lib/packable/extensions/integer.rb
+- lib/packable/extensions/io.rb
+- lib/packable/extensions/object.rb
+- lib/packable/extensions/proc.rb
+- lib/packable/extensions/string.rb
+- lib/packable/mixin.rb
+- lib/packable/packers.rb
+- lib/packable.rb
+- test/packing_doc_test.rb
+- test/packing_test.rb
+- test/test_helper.rb
+- LICENSE
+has_rdoc: true
+homepage: http://github.com/marcandre/packable
+post_install_message: 
+rdoc_options: 
+- --title
+- Packable library
+- --main
+- README.rdoc
+- --line-numbers
+- --inline-source
+- --inline-source
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: marcandre
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: Extensive packing and unpacking capabilities
+test_files: []
+