protostar 0.1.0.beta1

data/lib/protostar/message/field_info.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Protostar
+  class Message
+    # Everything the runtime and the codec need about one field of a message
+    # class, resolved once when the class is defined: the slot it is stored
+    # in, its kind as a small Integer to dispatch on, precomputed tag bytes,
+    # the classes and enum tables it refers to. Frozen and shareable.
+    # @api private
+    class FieldInfo
+      # Kinds are FieldDescriptorProto.Type numbers
+      DOUBLE = 1
+      FLOAT = 2
+      INT64 = 3
+      UINT64 = 4
+      INT32 = 5
+      FIXED64 = 6
+      FIXED32 = 7
+      BOOL = 8
+      STRING = 9
+      GROUP = 10
+      MESSAGE = 11
+      BYTES = 12
+      UINT32 = 13
+      ENUM = 14
+      SFIXED32 = 15
+      SFIXED64 = 16
+      SINT32 = 17
+      SINT64 = 18
+
+      KINDS = {
+        double: DOUBLE, float: FLOAT, int64: INT64, uint64: UINT64, int32: INT32, fixed64: FIXED64,
+        fixed32: FIXED32, bool: BOOL, string: STRING, group: GROUP, message: MESSAGE, bytes: BYTES,
+        uint32: UINT32, enum: ENUM, sfixed32: SFIXED32, sfixed64: SFIXED64, sint32: SINT32, sint64: SINT64
+      }.freeze
+
+      # Byte width and unpack directive of the fixed-width kinds
+      FIXED = {
+        DOUBLE => [8, "E"], FLOAT => [4, "e"], FIXED64 => [8, "Q<"], FIXED32 => [4, "V"],
+        SFIXED32 => [4, "l<"], SFIXED64 => [8, "q<"]
+      }.transform_values(&:freeze).freeze
+
+      # @return [Schema::Field]
+      attr_reader :descriptor
+      # @return [String]
+      attr_reader :name
+      # @return [Symbol]
+      attr_reader :symbol
+      # @return [Integer]
+      attr_reader :number
+      # @return [Integer, nil] the slot in the message's value array; nil for map keys and values
+      attr_reader :index
+      # @return [Integer] one of the kind constants
+      attr_reader :kind
+      # @return [Integer] wire type of one unpacked value
+      attr_reader :wire_type
+      # @return [Boolean]
+      attr_reader :repeated, :packed, :packable, :presence, :map, :closed_enum, :utf8_validation, :required
+      # @return [Array<Integer>, nil] slots of the other members of the field's real oneof
+      attr_reader :siblings
+      # @return [Class, nil] for message and group fields
+      attr_reader :message_class
+      # @return [Module, nil] for enum fields
+      attr_reader :enum_module
+      # @return [Hash{Integer => Symbol}, nil] enum number to its first name
+      attr_reader :enum_names
+      # @return [Hash{Symbol => Integer}, nil] every enum name, aliases included, to its number
+      attr_reader :enum_numbers
+      # @return [Object] the value an unset field reads as
+      attr_reader :default
+      # @return [String] the tag of one unpacked value, varint-encoded
+      attr_reader :tag
+      # @return [String, nil] the length-delimited tag, for packable fields
+      attr_reader :packed_tag
+      # @return [String, nil] the end-group tag, for groups
+      attr_reader :end_tag
+      # @return [FieldInfo, nil] for map fields
+      attr_reader :key, :value
+
+      # @param field [Schema::Field]
+      # @param index [Integer, nil]
+      # @param classes [#call] resolves a Schema::Message or Schema::Enum to its Class or Module
+      # @param open_enums [Boolean] treat a closed enum as open
+      def initialize(field, index, classes, siblings: nil, open_enums: false)
+        @descriptor = field
+        @name = field.name
+        @symbol = field.name.to_sym
+        @number = field.number
+        @index = index
+        @kind = KINDS.fetch(field.type)
+        @wire_type = field.wire_type
+        @map = field.map?
+        @repeated = field.repeated? && !@map
+        @packed = field.packed?
+        @packable = field.packable?
+        @presence = field.presence?
+        @required = field.required?
+        @utf8_validation = field.utf8_validation?
+        @siblings = siblings
+        @tag = Wire.tag_bytes(@number, @wire_type)
+        @packed_tag = Wire.tag_bytes(@number, Wire::LENGTH_DELIMITED) if @packable
+        @end_tag = Wire.tag_bytes(@number, Wire::END_GROUP) if @kind == GROUP
+        if @map
+          @key = FieldInfo.new(field.map_key, nil, classes)
+          @value = FieldInfo.new(field.map_value, nil, classes, open_enums: open_enums)
+        elsif field.message_type
+          @message_class = classes.call(field.message_type)
+        end
+        if field.enum_type
+          @enum_module = classes.call(field.enum_type)
+          @enum_names = @enum_module.__names
+          @enum_numbers = @enum_module.__numbers
+          @closed_enum = !open_enums && field.enum_type.closed?
+        else
+          @closed_enum = false
+        end
+        @default = field.default unless @map || @repeated
+        # an enum default may name an alias; values are stored by their first name
+        @default = @enum_names[@enum_numbers.fetch(@default)] if @enum_names && @default
+      end
+
+      # @return [Boolean] whether the field is a message or group
+      def message?
+        @kind == MESSAGE || @kind == GROUP
+      end
+
+      # @return [Boolean] whether a singular value equals the type's zero
+      #   value, so that a field without presence is left out on encode.
+      #   Negative zero is not a default, as in protoc.
+      def zero?(value)
+        case @kind
+        when DOUBLE, FLOAT then value == 0 && (1.0 / value) > 0
+        when STRING, BYTES then value.empty?
+        when BOOL then value == false
+        when ENUM then (value.is_a?(Symbol) ? @enum_numbers[value] : value) == 0
+        else value == 0
+        end
+      end
+
+      def inspect
+        "#<#{self.class.name} #{@descriptor.full_name} slot=#{@index}>"
+      end
+    end
+  end
+end

data/lib/protostar/message/reflection.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Protostar
+  class Message
+    # Reading and writing a message class's fields by descriptor, name or
+    # number rather than through the accessors, for code that walks messages
+    # it does not know in advance: serializers, builders, form mappers.
+    # Every message class has one, made when the class is defined, frozen and
+    # shareable:
+    #
+    #   r = Acme::Person.reflection
+    #   r.fields.map(&:name)                 # => ["name", "id", "emails", "address"]
+    #   r.get(person, :name)                 # => "Ada"
+    #   r.set(person, "id", 7)
+    #   r.set?(person, :address)             # => false
+    #   r.message_class(:address)            # => Acme::Address
+    #   r.each(person) { |field, value| ... } # fields that are set, in declaration order
+    #
+    # It lives on the class (`Klass.reflection`), where no field accessor can
+    # take its name. Values go through the same coercion and checks as the
+    # accessors: `set(m, f, v)` is `m.f = v`, `get(m, f)` is `m.f`.
+    class Reflection
+      # @return [Class] the message class it reflects
+      attr_reader :klass
+      # @return [Schema::Message]
+      attr_reader :descriptor
+
+      # @api private
+      def initialize(klass, descriptor)
+        @klass = klass
+        @descriptor = descriptor
+        @by_number = klass.__by_number
+        @by_name = klass.__by_name
+      end
+
+      # @return [Array<Schema::Field>] in declaration order
+      def fields
+        @descriptor.fields
+      end
+
+      # @return [Array<Schema::Oneof>] real oneofs; a proto3 `optional` field's
+      #   synthetic oneof is left out, as it is no choice
+      def oneofs
+        @descriptor.real_oneofs
+      end
+
+      # @param key [Schema::Field, String, Symbol, Integer] a field, its name or its number
+      # @return [Schema::Field, nil]
+      def field(key)
+        info(key)&.descriptor
+      end
+
+      # @param message [Message] an instance of the class
+      # @param key [Schema::Field, String, Symbol, Integer]
+      # @return [Object] what the field's reader returns
+      # @raise [ArgumentError] when there is no such field
+      def get(message, key)
+        message.__get(info!(key))
+      end
+
+      # @param message [Message]
+      # @param key [Schema::Field, String, Symbol, Integer]
+      # @param value [Object] nil clears the field
+      # @raise [ArgumentError] when there is no such field
+      # @raise [Protostar::TypeError] for a value the field cannot hold
+      def set(message, key, value)
+        message.__set(info!(key).index, value)
+        message
+      end
+
+      # @param message [Message]
+      # @param key [Schema::Field, String, Symbol, Integer]
+      # @return [Boolean] set, for a field with presence; not empty, for a
+      #   repeated or map field; not its zero value, for any other
+      def set?(message, key)
+        info = info!(key)
+        v = message.__values[info.index]
+        return false if v.nil?
+        return !v.empty? if info.repeated || info.map
+        info.presence || !info.zero?(v)
+      end
+
+      # @param message [Message]
+      # @param key [Schema::Field, String, Symbol, Integer]
+      def clear(message, key)
+        message.__set(info!(key).index, nil)
+        message
+      end
+
+      # @param message [Message]
+      # @param oneof [Schema::Oneof, String, Symbol]
+      # @return [Schema::Field, nil] the member that is set
+      def which(message, oneof)
+        oneof = @descriptor.oneofs.find { |o| o.name == oneof.to_s } unless oneof.is_a?(Schema::Oneof)
+        raise ArgumentError, "#{@descriptor.full_name} has no oneof #{oneof.inspect}" unless oneof
+        oneof.fields.find { |f| !message.__values[@by_number.fetch(f.number).index].nil? }
+      end
+
+      # @param key [Schema::Field, String, Symbol, Integer] a message or group field,
+      #   or a map field whose values are messages
+      # @return [Class, nil] the class its values are instances of
+      def message_class(key)
+        info = info!(key)
+        info.map ? info.value.message_class : info.message_class
+      end
+
+      # @param key [Schema::Field, String, Symbol, Integer] an enum field, or a map field of enum values
+      # @return [Module, nil] the enum's module
+      def enum_module(key)
+        info = info!(key)
+        info.map ? info.value.enum_module : info.enum_module
+      end
+
+      # Yields each field that is {#set?}, in declaration order
+      # @param message [Message]
+      # @yieldparam field [Schema::Field]
+      # @yieldparam value [Object] what the reader returns
+      # @return [Enumerator] without a block
+      def each(message)
+        return enum_for(:each, message) unless block_given?
+        @klass.__fields.each do |info|
+          next unless set?(message, info.descriptor)
+          yield info.descriptor, message.__get(info)
+        end
+        nil
+      end
+
+      def inspect
+        "#<#{self.class.name} #{@descriptor.full_name}>"
+      end
+
+      private
+
+      def info(key)
+        case key
+        when Integer then @by_number[key]
+        when Schema::Field
+          found = @by_number[key.number]
+          found if found&.descriptor.equal?(key)
+        else @by_name[key]
+        end
+      end
+
+      def info!(key)
+        info(key) || raise(ArgumentError, "#{@descriptor.full_name} has no field #{key.inspect}")
+      end
+    end
+  end
+end