prepor-beefcake 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c84028ca26869888306b5bf5c48b48dfb79909b2
+  data.tar.gz: 7396b01b5432a3452ec5d59b3f19e3b140c66e19
+SHA512:
+  metadata.gz: ffea398a17e0efa2bf8e6278c895caea789a086aff759ebb06bd57f25fff28da763fce39ac618c2cc13a6b814897079257322d6973bf330bc8e1ade0953a980a
+  data.tar.gz: 719b223605e7c5acaa0b795df704caf16576478cea4dd870225f7118d31613ac171f9ca62601fc242d0ba91d33942e9c919451d486038a6059f80defc8db4e67

data/.gitignore

@@ -0,0 +1,3 @@
+*.gem
+Gemfile.lock
+bench/beefcake.prof.*

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - 2.1.1
+  - 2.1.2
+  - jruby-19mode

data/Gemfile

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

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,161 @@
+# Beefcake
+
+A sane Google Protocol Buffers library for Ruby. It's all about being Buf;
+ProtoBuf.
+
+## Installation
+
+```shell
+gem install beefcake
+```
+
+## Usage
+
+```ruby
+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
+
+# You can create a new message with hash arguments:
+x = Variety.new(:x => 1, :y => 2)
+
+# You can set fields individually using accessor methods:
+x = Variety.new
+x.x = 1
+x.y = 2
+
+# And you can access fields using Hash syntax:
+x[:x] # => 1
+x[:y] = 4
+x # => <Variety x: 1, y: 4>
+```
+
+### Encoding
+
+Any object responding to `<<` can accept encoding
+
+```ruby
+# see code example above for the definition of Variety
+x = Variety.new(:x => 1, :y => 2)
+
+# For example, you can encode into a String:
+s = ""
+x.encode(s)
+s # => "\b\x01\x10\x02)\0"
+
+# If you don't encode into anything, a new Beefcake::Buffer will be returned:
+x.encode # => #<Beefcake::Buffer:0x007fbfe1867ab0 @buf="\b\x01\x10\x02)\0">
+
+# And that buffer can be converted to a String:
+x.encode.to_s # => "\b\x01\x10\x02)\0"
+```
+
+### Decoding
+
+```ruby
+# see code example above for the definition of Variety
+x = Variety.new(:x => 1, :y => 2)
+
+# You can decode from a Beefcake::Buffer
+encoded = x.encode
+Variety.decode(encoded) # => <Variety x: 1, y: 2, pary: [], foo: B(2)>
+
+# Decoding from a String works the same way:
+Variety.decode(encoded.to_s) # => <Variety x: 1, y: 2, pary: [], foo: B(2)>
+
+# You can update a Beefcake::Message instance with new data too:
+new_data = Variety.new(x: 12345, y: 2).encode
+Variety.decoded(new_data, x)
+x # => <Variety x: 12345, y: 2, pary: [], foo: B(2)>
+```
+
+### Generate code from `.proto` file
+
+```shell
+protoc --beefcake_out output/path -I path/to/proto/files/dir path/to/file.proto
+```
+
+You can set the `BEEFCAKE_NAMESPACE` variable to generate the classes under a
+desired namespace. (i.e. App::Foo::Bar)
+
+## About
+
+Ruby deserves and needs first-class ProtoBuf support. Other libs didn't feel
+very "Ruby" to me and were hard to parse.
+
+This library was built with EventMachine in mind.  Not just blocking-IO.
+
+Source: https://github.com/protobuf-ruby/beefcake
+
+### Support Features
+
+  * Optional fields
+  * Required fields
+  * Repeated fields
+  * Packed Repeated Fields
+  * Varint fields
+  * 32-bit fields
+  * 64-bit fields
+  * Length-delimited fields
+  * Embedded Messages
+  * Unknown fields are ignored (as per spec)
+  * Enums
+  * Defaults (i.e. `optional :foo, :string, :default => "bar"`)
+  * Varint-encoded length-delimited message streams
+
+### Future
+
+  * Imports
+  * Use package in generation
+  * Groups (would be nice for accessing older protos)
+
+### Further Reading
+
+http://code.google.com/apis/protocolbuffers/docs/encoding.html
+
+## Testing
+
+    rake test
+
+Beefcake conducts continuous integration on [Travis CI](http://travis-ci.org).
+The current build status for HEAD is [![Build Status](https://travis-ci.org/protobuf-ruby/beefcake.png?branch=master)](https://travis-ci.org/protobuf-ruby/beefcake).
+
+All pull requests automatically trigger a build request.  Please ensure that
+tests succeed.
+
+Currently Beefcake is tested and working on:
+
+  * Ruby 1.9.3
+  * Ruby 2.0.0
+  * Ruby 2.1.0
+  * Ruby 2.1.1
+  * Ruby 2.1.2
+  * JRuby in 1.9 mode
+
+## Thank You
+
+  * Keith Rarick (kr) for help with encoding/decoding.
+  * Aman Gupta (tmm1) for help with cross VM support and performance enhancements.

data/RELEASE_NOTES.md

@@ -0,0 +1,38 @@
+# Beefcake Release Notes
+
+# 0.1.0 - 2014-09-05
+
+Release 1.0.0 includes changes and improvements.
+
+* Version numbering now properly semantic.
+* Ruby 1.8 is no longer supported.
+* Field number re-use raises a `DuplicateFieldNumber` error.
+* Checking to see if a type is encodable is much faster.
+* Fields named `fields` are now supported.
+* String read and decoding are benchmarked during testing.
+* `string` fields now decode with a `UTF-8` encoding.
+
+# 0.5.0 - 2013-12-20
+
+Release 0.5.0 corrects a few behaviors.
+
+* Drastically revised README, written by Tobias "grobie" Schmidt
+* Output fewer newlines in generated files, fixed by Tobias "grobie" Schmidt
+* Don't crash when attempting to reencode frozen strings,
+  found thanks to Kyle "Aphyr" Kingsbury
+* Return `nil` instead of raising a generic Ruby error when trying to
+  decode a zero-length buffer, fixed by Tobias "grobie" Schmidt 
+
+# 0.4.0 - 2013-10-10
+
+Release 0.4.0 is the first with new maintainers.
+
+* Modernize tests
+* Add Travis CI monitoring
+* Support varint-encoded length-delimited buffers
+* Support generation with recursive definitions
+* Support Ruby 2.0
+* Support encoded buffers
+* Support false but non-nil values
+* Support top-level enums, added by Kim Altintop:
+  https://github.com/protobuf-ruby/beefcake/pull/23

data/Rakefile

@@ -0,0 +1,12 @@
+require 'rake'
+require 'rake/testtask'
+require 'bundler/gem_tasks'
+Bundler::GemHelper.install_tasks
+
+Rake::TestTask.new do |t|
+  t.libs << 'minitest'
+  t.test_files = FileList['test/*_test.rb']
+  t.verbose = true
+end
+
+task :default => :test

data/beefcake.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "beefcake/version"
+
+Gem::Specification.new do |s|
+  s.name        = "prepor-beefcake"
+  s.version     = Beefcake::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Blake Mizerany", "Matt Proud", "Bryce Kerley"]
+  s.email       = ["blake.mizerany@gmail.com", "matt.proud@gmail.com", "bkerley@brycekerley.net"]
+  s.homepage    = "https://github.com/protobuf-ruby/beefcake"
+  s.summary     = %q{A sane protobuf library for Ruby}
+  s.description = %q{A sane protobuf library for Ruby}
+  s.license     = 'MIT'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.required_ruby_version = '>= 1.9.3'
+
+  s.add_development_dependency('rake', '~> 10.1.0')
+  s.add_development_dependency('minitest', '~> 5.3')
+end

data/bench/simple.rb

@@ -0,0 +1,116 @@
+$:.unshift File.expand_path('../../lib', __FILE__)
+require 'beefcake'
+
+class MyMessage
+  include Beefcake::Message
+  required :number, :int32,  1
+  required :chars,  :string, 2
+  required :raw,    :bytes,  3
+  required :bool,   :bool,   4
+  required :float,  :float,  5
+end
+
+ITERS = 100_000
+
+case ARGV[0]
+when 'pprof'
+  # profile message creation/encoding/decoding w/ perftools.rb
+  # works on 1.8 and 1.9
+  #   ruby bench/simple.rb pprof
+  #   open bench/beefcake.prof.gif
+
+  ENV['CPUPROFILE_FREQUENCY'] = '4000'
+  require 'rubygems'
+  require 'perftools'
+  PerfTools::CpuProfiler.start(File.expand_path("../beefcake.prof", __FILE__)) do
+    ITERS.times do
+      str = MyMessage.new(
+        :number => 12345,
+        :chars  => 'hello',
+        :raw    => 'world',
+        :bool   => true,
+        :float  => 1.2345
+      ).encode
+      MyMessage.decode(str)
+    end
+  end
+  Dir.chdir(File.dirname(__FILE__)) do
+    `pprof.rb beefcake.prof --gif > beefcake.prof.gif`
+  end
+
+when 'ruby-prof'
+  # profile message creation/encoding/decoding w/ ruby-prof
+  # works on 1.8 and 1.9
+  #   ruby bench/simple.rb ruby-prof
+  #   open bench/beefcake.prof.html
+
+  require 'ruby-prof'
+  result = RubyProf.profile do
+    ITERS.times do
+      str = MyMessage.new(
+        :number => 12345,
+        :chars  => 'hello',
+        :raw    => 'world',
+        :bool   => true,
+        :float  => 1.2345
+      ).encode
+      MyMessage.decode(str)
+    end
+  end
+
+  filename = File.expand_path('beefcake.prof.html', File.dirname(__FILE__))
+  File.open(filename, 'w') do |file|
+    RubyProf::GraphHtmlPrinter.new(result).print(file)
+  end
+
+else
+  # benchmark message creation/encoding/decoding
+  #   rvm install 1.8.7 1.9.2 jruby rbx
+  #   rvm 1.8.7,1.9.2,jruby,rbx ruby bench/simple.rb
+
+  require 'benchmark'
+
+  Benchmark.bmbm do |x|
+    x.report 'object creation' do
+      ITERS.times do
+        Object.new
+      end
+    end
+    x.report 'message creation' do
+      ITERS.times do
+        MyMessage.new(
+          :number => 12345,
+          :chars  => 'hello',
+          :raw    => 'world',
+          :bool   => true,
+          :float  => 1.2345
+        )
+      end
+    end
+    x.report 'message encoding' do
+      m = MyMessage.new(
+        :number => 12345,
+        :chars  => 'hello',
+        :raw    => 'world',
+        :bool   => true,
+        :float  => 1.2345
+      )
+      ITERS.times do
+        m.encode
+      end
+    end
+    x.report 'message decoding' do
+      str = MyMessage.new(
+        :number => 12345,
+        :chars  => 'hello',
+        :raw    => 'world',
+        :bool   => true,
+        :float  => 1.2345
+      ).encode.to_s
+      ITERS.times do
+        MyMessage.decode(str.dup)
+      end
+    end
+  end
+
+end

data/bin/protoc-gen-beefcake

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'beefcake/generator'
+
+req = CodeGeneratorRequest.decode(STDIN.read)
+res = Beefcake::Generator.compile(req)
+
+# Send it out!
+STDOUT.print(res.encode)

data/lib/beefcake.rb

@@ -0,0 +1,283 @@
+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 DuplicateFieldNumber < StandardError
+      def initialize(num, name)
+        super("Field number #{num} (#{name}) was already used")
+      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)
+        if fields.include?(fn)
+          raise DuplicateFieldNumber.new(fn, name)
+        end
+        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
+
+        __beefcake_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)
+        v = self[fld.name]
+        v = v.is_a?(Array) ? v : [v]
+
+        v.compact.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 write_delimited(buf = Buffer.new)
+        if ! buf.respond_to?(:<<)
+          raise ArgumentError, "buf doesn't respond to `<<`"
+        end
+
+        if ! buf.is_a?(Buffer)
+          buf = Buffer.new(buf)
+        end
+
+        buf.append_bytes(encode)
+
+        buf
+      end
+
+      def valid_enum?(mod, val)
+        !!name_for(mod, val)
+      end
+
+      def name_for(mod, val)
+        mod.constants.each do |name|
+          if mod.const_get(name) == val
+            return name
+          end
+        end
+        nil
+      end
+
+      def validate!
+        __beefcake_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
+          elsif fld.rule == :repeated
+            val = buf.read(fld.type)
+            (o[fld.name] ||= []) << val
+          else
+            val = buf.read(fld.type)
+            o[fld.name] = val
+          end
+        end
+
+        # Set defaults
+        fields.values.each do |f|
+          next if o[f.name] == false
+          o[f.name] ||= f.opts[:default]
+        end
+
+        o.validate!
+
+        o
+      end
+
+      def read_delimited(buf, o=self.new)
+        if ! buf.is_a?(Buffer)
+          buf = Buffer.new(buf)
+        end
+
+        return if buf.length == 0
+
+        n = buf.read_int64
+        tmp = Buffer.new(buf.read(n))
+
+        decode(tmp, o)
+      end
+    end
+
+
+    def self.included(o)
+      o.extend Dsl
+      o.extend Decode
+      o.send(:include, Encode)
+    end
+
+    def initialize(attrs={})
+      __beefcake_fields__.values.each do |fld|
+        self[fld.name] = attrs[fld.name]
+      end
+    end
+
+    def __beefcake_fields__
+      self.class.fields
+    end
+
+    def [](k)
+      __send__(k)
+    end
+
+    def []=(k, v)
+      __send__("#{k}=", v)
+    end
+
+    def ==(o)
+      return false if (o == nil) || (o == false)
+      return false unless o.is_a? self.class
+      __beefcake_fields__.values.all? {|fld| self[fld.name] == o[fld.name] }
+    end
+
+    def inspect
+      set = __beefcake_fields__.values.select {|fld| self[fld.name] != nil }
+
+      flds = set.map do |fld|
+        val = self[fld.name]
+
+        case fld.type
+        when Class
+          "#{fld.name}: #{val.inspect}"
+        when Module
+          title = name_for(fld.type, val) || "-NA-"
+          "#{fld.name}: #{title}(#{val.inspect})"
+        else
+          "#{fld.name}: #{val.inspect}"
+        end
+      end
+
+      "<#{self.class.name} #{flds.join(", ")}>"
+    end
+
+    def to_hash
+      __beefcake_fields__.values.inject({}) do |h, fld|
+        value = self[fld.name]
+        unless value.nil?
+          h[fld.name] = value
+        end
+        h
+      end
+    end
+
+  end
+
+end