beefcake 0.1.0

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2011 Blake Mizerany
+
+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,126 @@
+# Beefcake (A sane Google Protocol Buffers library for Ruby)
+## It's all about being Buf; ProtoBuf.
+
+# Install
+
+    $ gem install beefcake
+
+# Example
+
+    require 'beefcake'
+
+    class Variety
+      include Beefcake::Message
+
+      # Required
+      required :x, :int32, 1
+      required :y, :int32, 2
+
+      # Optional
+      optional :tag, :string, 3
+
+      # Repeated
+      repeated :ary,  :fixed64, 4
+      repeated :pary, :fixed64, 5, :packed => true
+
+      # Enums - Simply use a Module (NOTE: defaults are optional)
+      module Foonum
+        A = 1
+        B = 2
+      end
+
+      # As per the spec, defaults are only set at the end
+      # of decoding a message, not on object creation.
+      optional :foo, Foonum, 6, :default => Foonum::B
+    end
+
+    x = Variety.new :x => 1, :y => 2
+    # or
+    x = Variety.new
+    x.x = 1
+    x.y = 2
+
+## Encoding
+
+Any object responding to `<<` can accept encoding
+
+    s = ""
+    x.encode(s)
+    p [:s, s]
+    # or (because encode returns the string/stream)
+    p [:s, x.encode]
+    # or
+    open("x.dat") do |f|
+      x.encode(f)
+    end
+
+    # decode
+    encoded = x.encode
+    decoded = Variety.decode(encoded)
+    p [:x, decoded]
+
+    # decode merge
+    Variety.decoded(more_data, decoded)
+
+# Why?
+
+  Ruby deserves and needs first-class ProtoBuf support.
+  Other libs didn't feel very "Ruby" to me and were hard to parse.
+
+# Caveats
+
+  Currently Beefcake doesn't parse `.proto` files.  This is OK for now.
+  In the simple case, you can create message types by hand; This is Ruby
+  after all.
+
+  Example (for the above):
+
+    message Variety {
+      required int32 x = 1
+      required int32 y = 2
+      optional string tag = 3
+
+      ...
+    }
+
+  In the near future, a generator would be nice.  I welcome anyone willing
+  to work on it to submit patches.  The other ruby libs lacked things I would
+  like, such as an optional namespace param rather than installing on (main).
+
+  This library was built with EventMachine in mind.  Not just blocking-IO.
+
+# Dev
+
+Source:
+
+    $ git clone git://github.com/bmizerany/beefcake
+
+Testing:
+
+    $ gem install turn
+    $ cd /path/to/beefcake
+    $ turn
+
+VMs:
+
+Currently Beefcake is tested and working on:
+
+  Ruby 1.8.7
+  Ruby 1.9.2
+  JRuby 1.5.6
+
+  There is a bug in Rubinius preventing proper ZigZag encoding.
+  The team is aware and I'm sure they're working on a fix.
+
+Nice to have:
+
+* `.proto` -> Ruby generator
+* Groups (would be nice for accessing older protos)
+
+# Further Reading
+
+http://code.google.com/apis/protocolbuffers/docs/encoding.html
+
+# Thank You
+
+Aman Gupta (tmm1) for help with cross VM support and performance enhancements.

data/lib/beefcake.rb

@@ -0,0 +1,203 @@
+require 'beefcake/buffer'
+
+module Beefcake
+  module Message
+
+    class WrongTypeError < StandardError
+      def initialize(name, exp, got)
+        super("Wrong type `#{got}` given for (#{name}).  Expected #{exp}")
+      end
+    end
+
+
+    class InvalidValueError < StandardError
+      def initialize(name, val)
+        super("Invalid Value given for `#{name}`: #{val.inspect}")
+      end
+    end
+
+
+    class RequiredFieldNotSetError < StandardError
+      def initialize(name)
+        super("Field #{name} is required but nil")
+      end
+    end
+
+
+    class Field < Struct.new(:rule, :name, :type, :fn, :opts)
+      def <=>(o)
+        fn <=> o.fn
+      end
+    end
+
+
+    module Dsl
+      def required(name, type, fn, opts={})
+        field(:required, name, type, fn, opts)
+      end
+
+      def repeated(name, type, fn, opts={})
+        field(:repeated, name, type, fn, opts)
+      end
+
+      def optional(name, type, fn, opts={})
+        field(:optional, name, type, fn, opts)
+      end
+
+      def field(rule, name, type, fn, opts)
+        fields[fn] = Field.new(rule, name, type, fn, opts)
+        attr_accessor name
+      end
+
+      def fields
+        @fields ||= {}
+      end
+    end
+
+    module Encode
+
+      def encode(buf = Buffer.new)
+        validate!
+
+        if ! buf.respond_to?(:<<)
+          raise ArgumentError, "buf doesn't respond to `<<`"
+        end
+
+        if ! buf.is_a?(Buffer)
+          buf = Buffer.new(buf)
+        end
+
+        # TODO: Error if any required fields at nil
+
+        fields.values.sort.each do |fld|
+          if fld.opts[:packed]
+            bytes = encode!(Buffer.new, fld, 0)
+            buf.append_info(fld.fn, Buffer.wire_for(fld.type))
+            buf.append_uint64(bytes.length)
+            buf << bytes
+          else
+            encode!(buf, fld, fld.fn)
+          end
+        end
+
+        buf
+      end
+
+      def encode!(buf, fld, fn)
+        Array(self[fld.name]).each do |val|
+          case fld.type
+          when Class # encodable
+            # TODO: raise error if type != val.class
+            buf.append(:string, val.encode, fn)
+          when Module # enum
+            if ! valid_enum?(fld.type, val)
+              raise InvalidValueError.new(fld.name, val)
+            end
+
+            buf.append(:int32, val, fn)
+          else
+            buf.append(fld.type, val, fn)
+          end
+        end
+
+        buf
+      end
+
+      def valid_enum?(mod, val)
+        mod.constants.any? {|name| mod.const_get(name) == val }
+      end
+
+      def validate!
+        fields.values.each do |fld|
+          if fld.rule == :required && self[fld.name].nil?
+            raise RequiredFieldNotSetError, fld.name
+          end
+        end
+      end
+
+    end
+
+
+    module Decode
+      def decode(buf, o=self.new)
+        if ! buf.is_a?(Buffer)
+          buf = Buffer.new(buf)
+        end
+
+        # TODO: test for incomplete buffer
+        while buf.length > 0
+          fn, wire = buf.read_info
+
+          fld = fields[fn]
+
+          # We don't have a field for with index fn.
+          # Ignore this data and move on.
+          if fld.nil?
+            buf.skip(wire)
+            next
+          end
+
+          exp = Buffer.wire_for(fld.type)
+          if wire != exp
+            raise WrongTypeError.new(fld.name, exp, wire)
+          end
+
+          if fld.rule == :repeated && fld.opts[:packed]
+            len = buf.read_uint64
+            tmp = Buffer.new(buf.read(len))
+            o[fld.name] ||= []
+            while tmp.length > 0
+              o[fld.name] << tmp.read(fld.type)
+            end
+
+            next
+          end
+
+          val = buf.read(fld.type)
+          if fld.rule == :repeated
+            (o[fld.name] ||= []) << val
+          else
+            o[fld.name] = val
+          end
+
+        end
+
+        # Set defaults
+        fields.values.each do |f|
+          o[f.name] ||= f.opts[:default]
+        end
+
+        o.validate!
+
+        o
+      end
+    end
+
+
+    def self.included(o)
+      o.extend Dsl
+      o.extend Decode
+      o.send(:include, Encode)
+    end
+
+    def initialize(attrs={})
+      fields.values.each do |fld|
+        self[fld.name] = attrs[fld.name]
+      end
+    end
+
+    def fields
+      self.class.fields
+    end
+
+    def [](k)
+      __send__(k)
+    end
+
+    def []=(k, v)
+      __send__("#{k}=", v)
+    end
+
+  end
+
+end

data/lib/beefcake/buffer.rb

@@ -0,0 +1,2 @@
+require 'beefcake/buffer/encode'
+require 'beefcake/buffer/decode'

data/lib/beefcake/buffer/base.rb

@@ -0,0 +1,92 @@
+module Beefcake
+
+  class Buffer
+
+    MinUint32 =  0
+    MaxUint32 =  (1<<32)-1
+    MinInt32  = -(1<<31)
+    MaxInt32  =  (1<<31)-1
+
+    MinUint64 =  0
+    MaxUint64 =  (1<<64)-1
+    MinInt64  = -(1<<63)
+    MaxInt64  =  (1<<63)-1
+
+    def self.wire_for(type)
+      case type
+      when :int32, :uint32, :sint32, :int64, :uint64, :sint64, :bool
+        0
+      when :fixed64, :sfixed64, :double
+        1
+      when :string, :bytes
+        2
+      when :fixed32, :sfixed32, :float
+        5
+      else
+        if encodable?(type)
+          2
+        else
+          raise UnknownType, type
+        end
+      end
+    end
+
+    def self.encodable?(type)
+      return false if ! type.is_a?(Class)
+      pims = type.public_instance_methods
+      pims.include?(:encode) || pims.include?("encode")
+    end
+
+    attr_accessor :buf
+
+    alias :to_s   :buf
+    alias :to_str :buf
+
+    class OutOfRangeError < StandardError
+      def initialize(n)
+        super("Value of of range: %d" % [n])
+      end
+    end
+
+    class BufferOverflowError < StandardError
+      def initialize(s)
+        super("Too many bytes read for %s" % [s])
+      end
+    end
+
+    class UnknownType < StandardError
+      def initialize(s)
+        super("Unknown type '%s'" % [s])
+      end
+    end
+
+    def initialize(buf="")
+      self.buf = buf
+    end
+
+    if ''.respond_to?(:force_encoding)
+      def buf=(buf)
+        @buf = buf.force_encoding('BINARY')
+      end
+    end
+
+    def length
+      @buf.respond_to?(:bytesize) ? @buf.bytesize : @buf.length
+    end
+
+    def <<(bytes)
+      buf << bytes
+    end
+
+    def read(n)
+      case n
+      when Symbol
+        __send__("read_#{n}")
+      else
+        buf.slice!(0, n)
+      end
+    end
+
+  end
+
+end