protobuf_descriptor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 86e4104ff69b390ba22f41af198f8f57100d6fae
+  data.tar.gz: 906471ce7f9431af23b952d547586dcf78cce699
+SHA512:
+  metadata.gz: 2546c493431fe79360a7aaecec47a7104d5a76748a745ae43d6745b8a3b2a0c65357e447668c5c017c4e561848bc70850787fd6e543a4ce53cf0e2ea0e532cf9
+  data.tar.gz: f0cd6897c1c5c107c1aec223c4dbb2eac872a29a216a97857f1fc112fb7dacb83516361c832f571d4d41b328a9ba51cca41bc39cf44aa3446ab4eac950b85096

data/.document

@@ -0,0 +1,3 @@
+- 
+ChangeLog.rdoc
+LICENSE.txt

data/.gitignore

@@ -0,0 +1,21 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/
+
+# Ignore wire-compiler.jar, its auto-downloaded when running specs.
+wire-compiler.jar

data/.rspec

@@ -0,0 +1 @@
+--colour --format documentation

data/.yardopts

@@ -0,0 +1 @@
+--markup rdoc --title "protobuf_descriptor Documentation" --protected

data/ChangeLog.rdoc

@@ -0,0 +1,4 @@
+=== 0.1.0 / 2014-04-11
+
+* Initial release:
+

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,57 @@
+PATH
+  remote: .
+  specs:
+    protobuf_descriptor (0.1.0)
+      protobuf (~> 3.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (4.1.0)
+      i18n (~> 0.6, >= 0.6.9)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.1)
+      tzinfo (~> 1.1)
+    coderay (1.1.0)
+    diff-lcs (1.2.5)
+    i18n (0.6.9)
+    json (1.8.1)
+    method_source (0.8.2)
+    middleware (0.1.0)
+    minitest (5.3.2)
+    multi_json (1.9.2)
+    protobuf (3.0.4)
+      activesupport (>= 3.2)
+      middleware
+      multi_json
+      thor
+    pry (0.9.12.6)
+      coderay (~> 1.0)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.8)
+    rspec-expectations (2.14.5)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.6)
+    rubygems-tasks (0.2.4)
+    slop (3.5.0)
+    thor (0.19.1)
+    thread_safe (0.3.3)
+    tzinfo (1.1.0)
+      thread_safe (~> 0.1)
+    yard (0.8.7.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  protobuf_descriptor!
+  pry (~> 0.9.12.6)
+  rspec (~> 2.4)
+  rubygems-tasks (~> 0.2)
+  yard (~> 0.8)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2014 Hsiu-Fan Wang
+
+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.rdoc

@@ -0,0 +1,51 @@
+= protobuf_descriptor
+
+* {Homepage}[https://rubygems.org/gems/protobuf_descriptor]
+* {Documentation}[http://rubydoc.info/gems/protobuf_descriptor/frames]
+
+== Description
+
+Protobuf_descriptor provides helper methods to make working with Google Protocol
+Buffer descriptors easier, go figure.. It handles type resolution, and computing
+type names (both within protocol buffers and in the generated output).
+
+== Examples
+
+Given the +descriptor.desc+ generated by the protocol buffer compiler, you
+can introspect the various data types. This example references the descriptor
+that would be generated by compiling
+{single_file.proto}[https://github.com/hfwang/protobuf_descriptor/blob/master/spec/protos/single_file_test/single_file.proto]
+
+  require 'protobuf_descriptor'
+  descriptor = ProtobufDescriptor.load("descriptor.desc")
+
+  # Load a single file by its filename/basename
+  file_descriptor = descriptor[:single_file]
+
+  # Grab a handle to an enum, or a message
+  file_descriptor.messages[:FieldOptions]
+  file_descriptor.enums[:UnnestedEnum]
+
+  # Also allows resolving types by their fully qualified name:
+  descriptor.resolve_type(".porkbuns.UnnestedEnum") # note the leading "."
+  # or even doing so relative to another enum
+  descriptor.resolve_type("CType", ".porkbuns.FieldOptions")
+
+For even more gory details, please peruse the actual
+{documentation}[link:ProtobufDescriptor.html].
+
+== Requirements
+
+I've only tested this on Ruby 1.9.3+. If it works for you on an older version of
+Ruby, let me know. You most likely want to install the
+{Google Protocol Buffer library}[https://code.google.com/p/protobuf/].
+
+== Install
+
+  $ gem install protobuf_descriptor
+
+== Copyright
+
+Copyright (c) 2014 Hsiu-Fan Wang
+
+See LICENSE.txt for details.

data/Rakefile

@@ -0,0 +1,46 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'rubygems/tasks'
+
+  Gem::Tasks.new
+rescue LoadError => e
+  warn e.message
+  warn "Run `gem install rubygems-tasks` to install Gem::Tasks."
+end
+
+begin
+  require 'rspec/core/rake_task'
+
+  RSpec::Core::RakeTask.new
+rescue LoadError => e
+  task :spec do
+    abort "Please run `gem install rspec` to install RSpec."
+  end
+end
+
+task :test    => :spec
+task :default => :spec
+
+begin
+  gem 'yard', '~> 0.8'
+  require 'yard'
+
+  YARD::Rake::YardocTask.new
+rescue LoadError => e
+  task :yard do
+    abort "Please run `gem install yard` to install YARD."
+  end
+end
+task :doc => :yard
+
+task :spec => ["wire-compiler.jar"] do |t|
+  # Declare this to ensure wire-compiler is downloaded
+end
+
+file "wire-compiler.jar" do |t|
+  sh 'wget --no-check-certificate --output-document="wire-compiler.jar" "http://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=com.squareup.wire&a=wire-compiler&v=LATEST&c=jar-with-dependencies"'
+end

data/lib/protobuf_descriptor/enum_descriptor.rb

@@ -0,0 +1,35 @@
+require "active_support"
+require "protobuf_descriptor/named_child"
+require "active_support/core_ext/module/delegation"
+
+class ProtobufDescriptor
+  # Describes an enum type.
+  #
+  # See {+EnumDescriptorProto+}[https://code.google.com/p/protobuf/source/browse/trunk/src/google/protobuf/descriptor.proto#84]
+  class EnumDescriptor
+    # The containing FileDescriptor[link:FileDescriptor.html]
+    # or MessageDescriptor[link:MessageDescriptor.html] that
+    # defines this enum.
+    attr_reader :parent
+
+    # The +EnumDescriptorProto+ this +EnumDescriptor+ is wrapping.
+    attr_reader :enum_descriptor_proto
+
+    def initialize(parent, enum_descriptor_proto)
+      @parent = parent
+      @enum_descriptor_proto = enum_descriptor_proto
+    end
+
+    # The name of the enum
+    def name; enum_descriptor_proto.name; end
+
+    # The possible values of the enum
+    def value; enum_descriptor_proto.value; end
+    alias_method :values, :value
+
+    # The +EnumOptions+ defined for this enum
+    def options; enum_descriptor_proto.options; end
+
+    include NamedChild
+  end
+end

data/lib/protobuf_descriptor/file_descriptor.rb

@@ -0,0 +1,130 @@
+require "protobuf_descriptor/enum_descriptor"
+require "protobuf_descriptor/message_descriptor"
+require "protobuf_descriptor/service_descriptor"
+
+require "active_support"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/string/inflections"
+
+class ProtobufDescriptor
+  # Describes a complete .proto file.
+  #
+  # See {+FileDescriptorProto+}[https://code.google.com/p/protobuf/source/browse/trunk/src/google/protobuf/descriptor.proto#56]
+  class FileDescriptor
+    # The parent FileDescriptorSet[link:ProtobufDescriptor.html]
+    attr_reader :file_descriptor_set
+
+    # The +FileDescriptorProto+ this +FileDescriptor+ is wrapping.
+    attr_reader :file_descriptor_proto
+
+    # List of the message types that are defined at the top level of this file,
+    # as a NamedCollection of
+    # MessageDescriptors[link:MessageDescriptor.html]
+    attr_reader :message_type
+
+    # List of the enum types that are defined at the top level of this file,
+    # as a NamedCollection of
+    # EnumDescriptors[link:EnumDescriptor.html]
+    attr_reader :enum_type
+
+    # List of the services that are defined at the top level of this file, as a
+    # NamedCollection of
+    # ServiceDescriptors[link:ServiceDescriptor.html]
+    attr_reader :service
+
+    def initialize(file_descriptor_set, file_descriptor_proto) #:nodoc:
+      # This is basically a parent pointer.
+      @file_descriptor_set = file_descriptor_set
+      @file_descriptor_proto = file_descriptor_proto
+
+      @message_type = ProtobufDescriptor::NamedCollection.new(
+          file_descriptor_proto.message_type.map { |m|
+            ProtobufDescriptor::MessageDescriptor.new(self, m)
+          })
+      @enum_type = ProtobufDescriptor::NamedCollection.new(
+          file_descriptor_proto.enum_type.map { |m|
+            ProtobufDescriptor::EnumDescriptor.new(self, m)
+          })
+      @service = ProtobufDescriptor::NamedCollection.new(
+          file_descriptor_proto.service.map { |m|
+            ProtobufDescriptor::ServiceDescriptor.new(self, m)
+          })
+    end
+
+    alias_method :parent, :file_descriptor_set
+    alias_method :message_types, :message_type
+    alias_method :messages, :message_type
+    alias_method :enum_types, :enum_type
+    alias_method :enums, :enum_types
+    alias_method :services, :service
+
+    # Set of all top-level messages, enums and services that are defined inside
+    # of this file
+    def children
+      @children ||= ProtobufDescriptor::NamedCollection.new(
+          @message_type.collection + @enum_type.collection + @service.collection)
+    end
+
+    # Filename relative to root of source tree.
+    def name
+      file_descriptor_proto.name
+    end
+
+    # The package name defined by the .proto file. E.G. "foo", "foo.bar", etc.
+    def package
+      file_descriptor_proto.package
+    end
+
+    # The Java package where classes generated from this .proto will be
+    # placed. By default, the proto package is used, but this is often
+    # inappropriate because proto packages do not normally start with backwards
+    # domain names.
+    def java_package
+      if file_descriptor_proto.has_field?(:options) && file_descriptor_proto.options.java_package.present?
+        return file_descriptor_proto.options.java_package
+      else
+        return file_descriptor_proto.package
+      end
+    end
+
+    # If set, all the classes from the .proto file are wrapped in a single
+    # outer class with the given name. This applies to both Proto1
+    # (equivalent to the old "--one_java_file" option) and Proto2 (where
+    # a .proto always translates to a single class, but you may want to
+    # explicitly choose the class name).
+    def java_outer_classname
+      if file_descriptor_proto.has_field?(:options) && file_descriptor_proto.options.java_multiple_files.present?
+        return nil
+      elsif file_descriptor_proto.has_field?(:options) && file_descriptor_proto.options.java_outer_classname.present?
+        return file_descriptor_proto.options.java_outer_classname
+      else
+        basename = name.split('/').last
+        basename = basename.gsub('.proto', '')
+        return basename.camelize
+      end
+    end
+
+    # Returns the fully qualified name, as used by the +resolve_type+ methods.
+    def fully_qualified_name
+      return ".#{self.package}"
+    end
+
+    # Returns the fully qualified Java class name.
+    def fully_qualified_java_name
+      return [java_package, java_outer_classname].compact.join('.')
+    end
+
+    # Returns the fully qualified Java name as Wire would generate it. Wire
+    # never wraps the definitions in a class named after the .proto file
+    # (essentially behaving as if +java_outer_classname+ were always true)
+    def fully_qualified_wire_name
+      return java_package
+    end
+
+    # Returns the fully qualified Ruby class name as generated by various
+    # protobuf gems.
+    def fully_qualified_ruby_name
+      return "::#{self.package.gsub('.', '::')}"
+    end
+  end
+end

data/lib/protobuf_descriptor/has_parent.rb

@@ -0,0 +1,19 @@
+class ProtobufDescriptor
+  module HasParent
+    def file_descriptor
+      p = self.parent
+      while p.class.name != "ProtobufDescriptor::FileDescriptor"
+        p = p.parent
+      end
+      return p
+    end
+
+    def protobuf_descriptor
+      p = self.parent
+      while p.class.name != "ProtobufDescriptor"
+        p = p.parent
+      end
+      return p
+    end
+  end
+end

data/lib/protobuf_descriptor/message_descriptor.rb

@@ -0,0 +1,167 @@
+require "protobuf_descriptor/enum_descriptor"
+require "protobuf_descriptor/has_parent"
+require "protobuf_descriptor/named_child"
+require "protobuf_descriptor/named_collection"
+
+require "active_support"
+require "active_support/core_ext/module/delegation"
+
+class ProtobufDescriptor
+  # Describes a message type.
+  #
+  # See DescriptorProto[https://code.google.com/p/protobuf/source/browse/trunk/src/google/protobuf/descriptor.proto#84]
+  class MessageDescriptor
+    # Describes a field within a message.
+    #
+    # See FieldDescriptorProto[https://code.google.com/p/protobuf/source/browse/trunk/src/google/protobuf/descriptor.proto#103]
+    class FieldDescriptor
+      # The parent MessageDescriptor[link:MessageDescriptor.html]
+      attr_reader :parent
+      # The +FieldDescriptorProto+ this +FieldDescriptor+ is wrapping.
+      attr_reader :field_descriptor_proto
+
+      def initialize(parent, field_descriptor_proto)
+        @parent = parent
+        @field_descriptor_proto = field_descriptor_proto
+      end
+
+      # The +FieldOptions+ for this field
+      def options
+        field_descriptor_proto.options
+      end
+
+      # Default value for this field.
+      # * For numeric types, contains the original text representation of the
+      #   value.
+      # * For booleans, "true" or "false".
+      # * For strings, contains the default text contents (not escaped in any
+      #   way).
+      # * For bytes, contains the C escaped value.  All bytes >= 128 are
+      #   escaped.
+      def default_value
+        field_descriptor_proto.default_value
+      end
+
+      # For extensions, this is the name of the type being extended.  It is
+      # resolved in the same manner as type_name.
+      def extendee
+        field_descriptor_proto.extendee
+      end
+
+      # For message and enum types, this is the name of the type.  If the name
+      # starts with a '.', it is fully-qualified.  Otherwise, C++-like scoping
+      # rules are used to find the type (i.e. first the nested types within this
+      # message are searched, then within the parent, on up to the root
+      # namespace).
+      #
+      # Note: the protocol buffer compiler always emits the fully qualified name!
+      def type_name
+        field_descriptor_proto.type_name
+      end
+
+      # Whether the field is optional/required/repeated.
+      def label
+        field_descriptor_proto.label
+      end
+
+      # The tag number of this field.
+      def number
+        field_descriptor_proto.number
+      end
+
+      # The name of this field.
+      def name
+        field_descriptor_proto.name
+      end
+
+      include ProtobufDescriptor::HasParent
+
+      # If type_name is set, this need not be set.  If both this and type_name
+      # are set, this must be either TYPE_ENUM or TYPE_MESSAGE.
+      def field_type
+        field_descriptor_proto.type
+      end
+
+      # Resolves the field's +type_name+, returning the
+      # MessageDescriptor[link:MessageDescriptor.html] or
+      # EnumDescriptor[link:EnumDescriptor.html] that this field will represent.
+      def resolve_type
+        protobuf_descriptor.resolve_type_name(self.type_name, self.parent)
+      end
+    end
+
+    # The containing FileDescriptor[link:FileDescriptor.html]
+    # or MessageDescriptor[link:MessageDescriptor.html] that
+    # defines this message.
+    attr_reader :parent
+
+    # The +MessageDescriptorProto+ this +MessageDescriptor+ is wrapping.
+    attr_reader :message_descriptor_proto
+
+    # The messages that are defined at the top level of this message, as a
+    # NamedCollection of MessageDescriptors[link:MessageDescriptor.html]
+    attr_reader :nested_type
+
+    # The enums that are defined at the top level of this message, as a
+    # NamedCollection of EnumDescriptors[link:EnumDescriptor.html]
+    attr_reader :enum_type
+
+    # The fields of this message, as a NamedCollection of
+    # FieldDescriptors[link:MessageDescriptor/FieldDescriptor.html]
+    attr_reader :field
+
+    def initialize(parent, message_descriptor_proto)
+      @parent = parent
+      @message_descriptor_proto = message_descriptor_proto
+      @nested_type = ProtobufDescriptor::NamedCollection.new(
+          message_descriptor_proto.nested_type.map { |m|
+              ProtobufDescriptor::MessageDescriptor.new(self, m)
+          })
+      @enum_type = ProtobufDescriptor::NamedCollection.new(
+          message_descriptor_proto.enum_type.map { |m|
+              ProtobufDescriptor::EnumDescriptor.new(self, m)
+          })
+      @field = ProtobufDescriptor::NamedCollection.new(
+          message_descriptor_proto.field.map { |m|
+              ProtobufDescriptor::MessageDescriptor::FieldDescriptor.new(self, m)
+          })
+    end
+
+    # The +MessageOptions+ defined for this message.
+    def options
+      message_descriptor_proto.options
+    end
+
+    # The extension ranges defined for this message
+    def extension_range
+      message_descriptor_proto.extension_range
+    end
+
+    # The extensions defined for this message
+    def extension
+      message_descriptor_proto.extension
+    end
+
+    # The name of the message
+    def name
+      message_descriptor_proto.name
+    end
+
+    alias_method :fields, :field
+    alias_method :extensions, :extension
+    alias_method :nested_types, :nested_type
+    alias_method :messages, :nested_type
+    alias_method :enum_types, :enum_type
+    alias_method :enums, :enum_type
+    alias_method :extension_ranges, :extension_range
+
+    include ProtobufDescriptor::NamedChild
+
+    # Set of all top-level messages ahnd enums that are defined within this
+    # message.
+    def children
+      @children ||= ProtobufDescriptor::NamedCollection.new(
+          @nested_type.collection + @enum_type.collection)
+    end
+  end
+end

data/lib/protobuf_descriptor/named_child.rb

@@ -0,0 +1,21 @@
+class ProtobufDescriptor
+  # A mixin module that adds tasty fully qualified name methods to objects that
+  # have a name and a parent.
+  module NamedChild
+    def fully_qualified_name
+      return "#{parent.fully_qualified_name}.#{self.name}"
+    end
+
+    def fully_qualified_java_name
+      return "#{parent.fully_qualified_java_name}.#{self.name}"
+    end
+
+    def fully_qualified_wire_name
+      return "#{parent.fully_qualified_wire_name}.#{self.name}"
+    end
+
+    def fully_qualified_ruby_name
+      return "#{parent.fully_qualified_ruby_name}::#{self.name}"
+    end
+  end
+end

data/lib/protobuf_descriptor/named_collection.rb

@@ -0,0 +1,45 @@
+require 'forwardable'
+
+class ProtobufDescriptor
+  # Array wrapper that also supports lookup by "name"
+  #
+  # By default all members must respond to name, but this behavior can be
+  # overriden by passing a block in the initializer.
+  class NamedCollection
+    attr_accessor :collection, :matcher
+
+    include Enumerable
+    extend Forwardable
+
+    def_delegators :@collection, :each, :<<, :size, :length
+
+    def initialize(collection, &matcher)
+      @collection = []
+      collection.each { |c| @collection << c }
+
+      if block_given?
+        @matcher = matcher
+      else
+        @matcher = lambda { |name, member| return member.name == name }
+      end
+    end
+
+    def [](index)
+      if Fixnum === index
+        return collection[index]
+      else
+        return find_by_name(index)
+      end
+    end
+
+    def find_by_name(name)
+      return collection.find { |member|
+        matcher.call(name.to_s, member)
+      }
+    end
+
+    def to_a
+      return self.collection.to_a
+    end
+  end
+end