protobuf 2.8.13 → 3.0.0.rc1

data/lib/protobuf/enum.rb

@@ -1,58 +1,319 @@
-require 'protobuf/enum_value'
+require 'delegate'
+require 'protobuf/optionable'
+require 'protobuf/deprecator'
+
+##
+# Adding extension to Numeric until
+# we can get people to stop calling #value
+# on Enum instances.
+#
+class Numeric
+  unless method_defined?(:value)
+    def value
+      $stderr.puts <<-DEPRECATION
+[DEPRECATED] Enum#value is deprecated and will be removed in the next release.
+              Use Enum#to_i instead.
+DEPRECATION
+      self
+    end
+  end
+end
 
 module Protobuf
-  class Enum
-
-    def self.define(name, value)
-      enum_value = ::Protobuf::EnumValue.new(self, name, value)
-      const_set(name, enum_value)
-      @values ||= {}
-      @names ||= {}
-      @values[name] = enum_value
-      @names[value] = name
-    end
-
-    # Fetch the given enum by a variety of type-checking
-    # mechanisms. This is useful for the enum field setters
-    # as well as repeated enum field construction.
-    def self.fetch(value)
-      case value
-      when ::Protobuf::EnumValue then
-        value
-      when Numeric then
-        enum_by_value(value.to_i)
-      when String, Symbol then
-        value_by_name(value.to_sym)
+  class Enum < SimpleDelegator
+
+    ##
+    # Deprecations
+    #
+
+    extend ::Protobuf::Deprecator
+
+    # Public: Allows setting Options on the Enum class.
+    include ::Protobuf::Optionable
+
+    def self.aliases_allowed?
+      self.get_option(:allow_alias)
+    end
+
+    # Public: Get all integer tags defined by this enum.
+    #
+    # Examples
+    #
+    #   class StateMachine < ::Protobuf::Enum
+    #     set_option :allow_alias
+    #     define :ON, 1
+    #     define :STARTED, 1
+    #     define :OFF, 2
+    #   end
+    #
+    #   StateMachine.all_tags #=> [ 1, 2 ]
+    #
+    # Returns an array of unique integers.
+    #
+    def self.all_tags
+      @all_tags ||= self.enums.map(&:to_i).uniq
+    end
+
+    # Internal: DSL method to create a new Enum. The given name will
+    # become a constant for this Enum pointing to the new instance.
+    #
+    # Examples
+    #
+    #   class StateMachine < ::Protobuf::Enum
+    #     define :ON, 1
+    #     define :OFF, 2
+    #   end
+    #
+    #   StateMachine::ON  #=> #<StateMachine::ON=1>
+    #   StateMachine::OFF #=> #<StateMachine::OFF=2>
+    #
+    # Returns nothing.
+    #
+    def self.define(name, tag)
+      enum = self.new(self, name, tag)
+      @enums ||= []
+      @enums << enum
+      const_set(name, enum)
+    end
+
+    # Public: All defined enums.
+    #
+    def self.enums
+      @enums
+    end
+
+    # Public: Get an array of Enum objects with the given tag.
+    #
+    # tag - An object that responds to to_i.
+    #
+    # Examples
+    #
+    #   class StateMachine < ::Protobuf::Enum
+    #     set_option :allow_alias
+    #     define :ON, 1
+    #     define :STARTED, 1
+    #     define :OFF, 2
+    #   end
+    #
+    #   StateMachine.enums_for_tag(1) #=> [ #<StateMachine::ON=1>, #<StateMachine::STARTED=1> ]
+    #   StateMachine.enums_for_tag(2) #=> [ #<StateMachine::OFF=2> ]
+    #
+    # Returns an array with zero or more Enum objects or nil.
+    #
+    def self.enums_for_tag(tag)
+      self.enums.select { |enum|
+        enum.to_i == tag.to_i
+      }
+    end
+
+    # Public: Get the Enum associated with the given name.
+    #
+    # name - A string-like object. Case-sensitive.
+    #
+    # Example
+    #
+    #   class StateMachine < ::Protobuf::Enum
+    #     define :ON, 1
+    #     define :OFF, 2
+    #   end
+    #
+    #   StateMachine.enum_for_name(:ON)  # => #<StateMachine::ON=1>
+    #   StateMachine.enum_for_name("ON") # => #<StateMachine::ON=1>
+    #   StateMachine.enum_for_name(:on)  # => nil
+    #   StateMachine.enum_for_name(:FOO) # => nil
+    #
+    # Returns the Enum object with the given name or nil.
+    #
+    def self.enum_for_name(name)
+      self.const_get(name)
+    rescue ::NameError
+      nil
+    end
+
+    # Public: Get the Enum object corresponding to the given tag.
+    #
+    # tag - An object that responds to to_i.
+    #
+    # Returns an Enum object or nil. If the tag corresponds to multiple
+    #   Enums, the first enum defined will be returned.
+    #
+    def self.enum_for_tag(tag)
+      self.enums_for_tag(tag).first
+    end
+
+    # Public: Get an Enum by a variety of type-checking mechanisms.
+    #
+    # candidate - An Enum, Numeric, String, or Symbol object.
+    #
+    # Example
+    #
+    #   class StateMachine < ::Protobuf::Enum
+    #     set_option :allow_alias
+    #     define :ON, 1
+    #     define :STARTED, 1
+    #     define :OFF, 2
+    #   end
+    #
+    #   StateMachine.fetch(StateMachine::ON)  # => #<StateMachine::ON=1>
+    #   StateMachine.fetch(:ON)               # => #<StateMachine::ON=1>
+    #   StateMachine.fetch("STARTED")         # => #<StateMachine::STARTED=1>
+    #   StateMachine.fetch(1)                 # => [ #<StateMachine::ON=1>, #<StateMachine::STARTED=1> ]
+    #
+    # Returns an Enum object or nil.
+    #
+    def self.fetch(candidate)
+      case candidate
+      when self then
+        candidate
+      when ::Numeric then
+        enum_for_tag(candidate.to_i)
+      when ::String, ::Symbol then
+        enum_for_name(candidate)
       else
         nil
       end
     end
 
-    def self.enum_by_value(value)
-      value_by_name(name_by_value(value))
+    # Public: Get the Symbol name associated with the given number.
+    #
+    # number - An object that responds to to_i.
+    #
+    # Examples
+    #
+    #   # Without aliases
+    #   class StateMachine < ::Protobuf::Enum
+    #     define :ON, 1
+    #     define :OFF, 2
+    #   end
+    #
+    #   StateMachine.name_for_tag(1) # => :ON
+    #   StateMachine.name_for_tag(2) # => :OFF
+    #   StateMachine.name_for_tag(3) # => nil
+    #
+    #   # With aliases
+    #   class StateMachine < ::Protobuf::Enum
+    #     set_option :allow_alias
+    #     define :STARTED, 1
+    #     define :ON, 1
+    #     define :OFF, 2
+    #   end
+    #
+    #   StateMachine.name_for_tag(1) # => :STARTED
+    #   StateMachine.name_for_tag(2) # => :OFF
+    #
+    # Returns the symbol name of the enum constant given it's associated tag or nil.
+    #   If the given tag has multiple names associated (due to allow_alias)
+    #   the first defined name will be returned.
+    #
+    def self.name_for_tag(tag)
+      self.enum_for_tag(tag).try(:name)
+    end
+
+    # Public: Check if the given tag is defined by this Enum.
+    #
+    # number - An object that responds to to_i.
+    #
+    # Returns a boolean.
+    #
+    def self.valid_tag?(tag)
+      tag.respond_to?(:to_i) && self.all_tags.include?(tag.to_i)
     end
 
-    def self.name_by_value(value)
-      (!value.nil? && value.respond_to?(:to_i)) ? @names[value.to_i] : nil
+    # Public: [DEPRECATED] Return a hash of Enum objects keyed
+    # by their :name.
+    #
+    def self.values
+      self.warn_deprecated(:values, :enums)
+
+      @values ||= begin
+                    self.enums.inject({}) do |hash, enum|
+                      hash[enum.name] = enum
+                      hash
+                    end
+                  end
     end
 
-    def self.valid_tag?(tag)
-      !! name_by_value(tag)
+    ##
+    # Class Deprecations
+    #
+
+    deprecate_class_method :enum_by_value,   :enum_for_tag
+    deprecate_class_method :name_by_value,   :name_for_tag
+    deprecate_class_method :get_name_by_tag, :name_for_tag
+    deprecate_class_method :value_by_name,   :enum_for_name
+
+
+    ##
+    # Attributes
+    #
+
+    attr_reader :parent_class, :name, :tag
+
+    ##
+    # Instance Methods
+    #
+
+    def initialize(parent_class, name, tag)
+      @parent_class = parent_class
+      @name = name
+      @tag = tag
+      super(@tag)
     end
 
-    def self.value_by_name(name)
-      @values[name]
+    # Overriding the class so ActiveRecord/Arel visitor will visit the enum as a Fixnum
+    #
+    def class
+      Fixnum
     end
 
-    def self.values
-      @values
+    def inspect
+      "\#<Protobuf::Enum(#{parent_class})::#{name}=#{tag}>"
     end
 
-    ##
-    # Class Aliases
+    def to_i
+      tag
+    end
+
+    def to_int
+      tag.to_int
+    end
+
+    def to_s(format = :tag)
+      case format
+      when :tag then
+        self.to_i.to_s
+      when :name then
+        name.to_s
+      else
+        self.to_i.to_s
+      end
+    end
+
+    # Re-implement `try` in order to fix the problem where
+    # the underlying fixnum doesn't respond to all methods (e.g. name or tag).
+    # If we respond to the first argument, `__send__` the args. Otherwise,
+    # delegate the `try` call to the underlying vlaue fixnum.
     #
-    class << self
-      alias_method :get_name_by_tag, :name_by_value
+    def try(*args, &block)
+      case
+      when args.empty? && block_given?
+        yield self
+      when respond_to?(args.first)
+        __send__(*args, &block)
+      else
+        @tag.try(*args, &block)
+      end
     end
+
+    def value
+      parent_class.warn_deprecated(:value, :to_i)
+      to_i
+    end
+
+    ##
+    # Instance Aliases
+    #
+    alias_method :to_hash_value, :to_i
   end
 end
+

data/lib/protobuf/field/base_field.rb

@@ -4,9 +4,11 @@ require 'protobuf/field/field_array'
 module Protobuf
   module Field
     class BaseField
+
       ##
       # Constants
       #
+
       PACKED_TYPES = [
         ::Protobuf::WireType::VARINT,
         ::Protobuf::WireType::FIXED32,
@@ -16,11 +18,16 @@ module Protobuf
       ##
       # Attributes
       #
-      attr_reader :message_class, :rule, :type, :name, :tag, :default, :default_value, :setter_method_name, :getter_method_name
+
+      attr_reader :default, :default_value, :deprecated, :extension,
+                  :getter_method_name, :message_class, :name, :optional,
+                  :packed, :repeated, :required, :rule, :setter_method_name,
+                  :tag, :type_class
 
       ##
       # Class Methods
       #
+
       def self.default
         nil
       end
@@ -28,14 +35,15 @@ module Protobuf
       ##
       # Constructor
       #
-      def initialize(message_class, rule, type, name, tag, options)
-        @message_class, @rule, @type, @name, @tag = \
-          message_class, rule, type, name, tag
+
+      def initialize(message_class, rule, type_class, name, tag, options)
+        @message_class, @rule, @type_class, @name, @tag = \
+          message_class, rule, type_class, name, tag
 
         set_rule_predicates
 
         @getter_method_name = name
-        @setter_method_name = "#{name}=".to_sym
+        @setter_method_name = "#{name}="
         @default   = options.delete(:default)
         @extension = options.delete(:extension)
         @packed    = repeated? && options.delete(:packed)
@@ -50,6 +58,7 @@ module Protobuf
       ##
       # Public Instance Methods
       #
+
       def acceptable?(value)
         true
       end
@@ -98,41 +107,46 @@ module Protobuf
       end
 
       def extension?
-        !! @extension
+        !! extension
       end
 
       # Is this a repeated field?
       def repeated?
-        !! @repeated
+        !! repeated
       end
 
       # Is this a required field?
       def required?
-        !! @required
+        !! required
       end
 
       # Is this a optional field?
       def optional?
-        !! @optional
+        !! optional
       end
 
       # Is this a deprecated field?
       def deprecated?
-        !! @deprecated
+        !! deprecated
       end
 
       # Is this a packed repeated field?
       def packed?
-        !! @packed
+        !! packed
       end
 
       def to_s
-        "#{@rule} #{@type} #{@name} = #{@tag} #{@default ? "[default=#{@default.inspect}]" : ''}"
+        "#{rule} #{type_class} #{name} = #{tag} #{default ? "[default=#{default.inspect}]" : ''}"
+      end
+
+      def type
+        $stderr.puts("[DEPRECATED] #{self.class.name}#type usage is deprecated.\nPlease use #type_class instead.")
+        type_class
       end
 
       def warn_if_deprecated
         if ::Protobuf.print_deprecation_warnings? && deprecated?
-          $stderr.puts("[WARNING] #{@message_class.name}##{@name} field usage is deprecated.")
+          $stderr.puts("[WARNING] #{message_class.name}##{name} field usage is deprecated.")
         end
       end
 
@@ -141,6 +155,7 @@ module Protobuf
       ##
       # Private Instance Methods
       #
+
       def define_accessor
         if repeated?
           define_array_getter
@@ -153,7 +168,7 @@ module Protobuf
 
       def define_array_getter
         field = self
-        @message_class.class_eval do
+        message_class.class_eval do
           define_method(field.getter_method_name) do
             field.warn_if_deprecated
             @values[field.name] ||= ::Protobuf::Field::FieldArray.new(field)
@@ -163,7 +178,7 @@ module Protobuf
 
       def define_array_setter
         field = self
-        @message_class.class_eval do
+        message_class.class_eval do
           define_method(field.setter_method_name) do |val|
             field.warn_if_deprecated
 
@@ -171,12 +186,10 @@ module Protobuf
               val = val.dup
               val.compact!
             else
-              error_text = <<-TYPE_ERROR
-                Expected repeated value of type '#{field.type}'
+              raise TypeError, <<-TYPE_ERROR
+                Expected repeated value of type '#{field.type_class}'
                 Got '#{val.class}' for repeated protobuf field #{field.name}
               TYPE_ERROR
-
-              raise TypeError, error_text
             end
 
             if val.nil? || (val.respond_to?(:empty?) && val.empty?)
@@ -191,7 +204,7 @@ module Protobuf
 
       def define_getter
         field = self
-        @message_class.class_eval do
+        message_class.class_eval do
           define_method(field.getter_method_name) do
             field.warn_if_deprecated
             @values.fetch(field.name, field.default_value)
@@ -201,7 +214,7 @@ module Protobuf
 
       def define_setter
         field = self
-        @message_class.class_eval do
+        message_class.class_eval do
           define_method(field.setter_method_name) do |val|
             field.warn_if_deprecated
 
@@ -210,7 +223,7 @@ module Protobuf
             elsif field.acceptable?(val)
               @values[field.name] = val
             else
-              raise TypeError, "Unacceptable value #{val} for field #{field.name} of type #{field.type}"
+              raise TypeError, "Unacceptable value #{val} for field #{field.name} of type #{field.type_class}"
             end
           end
         end
@@ -225,7 +238,7 @@ module Protobuf
       end
 
       def set_rule_predicates
-        case @rule
+        case rule
         when :repeated then
           @required = @optional = false
           @repeated = true
@@ -239,23 +252,24 @@ module Protobuf
       end
 
       def typed_default_value
-        if @default.nil?
+        if default.nil?
           self.class.default
         else
-          @default
+          default
         end
       end
 
       def validate_packed_field
         if packed? && ! ::Protobuf::Field::BaseField::PACKED_TYPES.include?(wire_type)
-          raise "Can't use packed encoding for `#{@type}' type"
+          raise "Can't use packed encoding for '#{type_class}' type"
         end
       end
 
       def warn_excess_options(options)
-        warn "WARNING: Invalid options: #{options.inspect} (in #{@message_class.name.split('::').last}.#{@name})"
+        warn "WARNING: Invalid options: #{options.inspect} (in #{message_class.name}##{name})"
       end
 
     end
   end
 end
+

data/lib/protobuf/field/bool_field.rb

@@ -3,10 +3,20 @@ require 'protobuf/field/varint_field'
 module Protobuf
   module Field
     class BoolField < VarintField
+
+      ##
+      # Class Methods
+      #
+
       def self.default
         false
       end
 
+
+      ##
+      # Public Instance Methods
+      # #
+
       def acceptable?(val)
         [true, false].include?(val)
       end
@@ -15,11 +25,21 @@ module Protobuf
         value == 1
       end
 
+      def encode(value)
+        [value ? 1 : 0].pack('C')
+      end
+
+      private
+
+      ##
+      # Private Instance Methods
+      #
+
       def define_getter
         super
 
         field = self
-        @message_class.class_eval do
+        message_class.class_eval do
           define_method("#{field.getter_method_name}?") do
             field.warn_if_deprecated
             @values.fetch(field.name, field.default_value)
@@ -27,9 +47,7 @@ module Protobuf
         end
       end
 
-      def encode(value)
-        [value ? 1 : 0].pack('C')
-      end
     end
   end
 end
+

data/lib/protobuf/field/bytes_field.rb

@@ -3,12 +3,25 @@ require 'protobuf/wire_type'
 module Protobuf
   module Field
     class BytesField < BaseField
+
+      ##
+      # Constants
+      #
+
       BYTES_ENCODING = "ASCII-8BIT".freeze
 
+      ##
+      # Class Methods
+      #
+
       def self.default
         ''
       end
 
+      ##
+      # Public Instance Methods
+      #
+
       def acceptable?(val)
         if val.nil? || val.is_a?(::Protobuf::Message) || val.instance_of?(String)
           return true
@@ -23,9 +36,28 @@ module Protobuf
         bytes_to_decode
       end
 
+      def encode(value)
+        value_to_encode = value.dup
+        value_to_encode = value.encode if value.is_a?(::Protobuf::Message)
+        value_to_encode.force_encoding(::Protobuf::Field::BytesField::BYTES_ENCODING)
+
+        string_size = ::Protobuf::Field::VarintField.encode(value_to_encode.size)
+        string_size << value_to_encode
+      end
+
+      def wire_type
+        ::Protobuf::WireType::LENGTH_DELIMITED
+      end
+
+      private
+
+      ##
+      # Private Instance Methods
+      #
+
       def define_setter
         field = self
-        @message_class.class_eval do
+        message_class.class_eval do
           define_method(field.setter_method_name) do |val|
             begin
               field.warn_if_deprecated
@@ -35,29 +67,18 @@ module Protobuf
               elsif field.acceptable?(val)
                 @values[field.name] = val.dup
               else
-                raise TypeError, "Unacceptable value #{val} for field #{field.name} of type #{field.type}"
+                raise TypeError, "Unacceptable value #{val} for field #{field.name} of type #{field.type_class}"
               end
             rescue NoMethodError => ex
               ::Protobuf::Logger.error { ex.message }
               ::Protobuf::Logger.error { ex.backtrace.join("\n") }
-              raise TypeError, "Got NoMethodError attempting to set #{val} for field #{field.name} of type #{field.type}: #{ex.message}"
+              raise TypeError, "Got NoMethodError attempting to set #{val} for field #{field.name} of type #{field.type_class}: #{ex.message}"
             end
           end
         end
       end
 
-      def encode(value)
-        value_to_encode = value.dup
-        value_to_encode = value.encode if value.is_a?(::Protobuf::Message)
-        value_to_encode.force_encoding(::Protobuf::Field::BytesField::BYTES_ENCODING)
-
-        string_size = ::Protobuf::Field::VarintField.encode(value_to_encode.size)
-        string_size << value_to_encode
-      end
-
-      def wire_type
-        ::Protobuf::WireType::LENGTH_DELIMITED
-      end
     end
   end
 end
+