protobuf_descriptor 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 92458122a645db219c0487d36ef7ea0357716986
-  data.tar.gz: 9a8be457e83289c5df3ff5f9103f05ef33023121
+  metadata.gz: 96fc09ef03f710c5955087be5c7296009c3e3122
+  data.tar.gz: 1be9567e58b0188dc5c9b6d84daf60168ca3d07c
 SHA512:
-  metadata.gz: c8a7801ee8978c2f2c0ccd7520ea7a6c25b3013ffdc6af992b19daa025eed7acc3d0e015b7d062d9f2059f10123a94537e2a1f2d29624f26bb7bf32ef93fc4b8
-  data.tar.gz: 019010a9b3e35dbdced724a078ecc31dd753a06c00adf95acbfb14c3bb712908c53af567e6006673194456d693ce27a08229ce544b924c53a3e39def6b348e12
+  metadata.gz: 0570eb154fab727bdcbe836ad82100ec194a730e0a906ff91178658c18bab228929816dc55ba41e9662e268f4305f8d4342c2fd8c9e5dfab5198ea64c9307974
+  data.tar.gz: efd4d050cd8b0298626ba3a5a882520b24c72f6b43b43adbb08ad015267b6aef10750b638c1e9ec59461b44dd0407879c9fbe89bfbb5dbd666696a2cdc85848d

data/.gitignore

@@ -17,5 +17,8 @@ tmp
 _yardoc
 doc/
 
+# Ignore gemfile.lock
+Gemfile.lock
+
 # Ignore wire-compiler.jar, its auto-downloaded when running specs.
 wire-compiler.jar

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - "1.9.3"
+  - "2.0.0"
+  - "2.1.0"
+  - "2.1.1"

data/.yardopts

@@ -1 +1 @@
---markup rdoc --title "protobuf_descriptor Documentation" --protected
+--markup markdown --title "protobuf_descriptor Documentation" --protected

data/ChangeLog.rdoc

@@ -1,3 +1,15 @@
+=== 1.1.0 / 2014-05-14
+
+Add support for accessing the +source_code_info+ bits of protobuf
+descriptors. This mainly means that the leading and trailing comments can be
+extracted for various declarations.
+
+=== 1.0.1 / not released
+
+Remove active_support dependency. The protobuf library still requires
+active_support though, so this doesn't really change anything.
+
+
 === 1.0.0 / 2014-04-25
 
 Huge version bump, update gem dependency to not be non-sensical. Should have no

data/README.md

@@ -0,0 +1,61 @@
+# protobuf_descriptor
+
+[![Gem Version](http://img.shields.io/gem/v/protobuf_descriptor.svg)][gem]
+[![Build Status](http://img.shields.io/travis/hfwang/protobuf_descriptor.svg)][travis]
+[![MIT license](http://img.shields.io/badge/license-MIT-red.svg)][license]
+
+[gem]: https://rubygems.org/gems/protobuf_descriptor
+[travis]: https://travis-ci.org/hfwang/protobuf_descriptor
+[license]: https://github.com/hfwang/protobuf_descriptor/blob/master/LICENSE.txt
+
+* [Homepage](https://rubygems.org/gems/protobuf_descriptor)
+* [Documentation](http://rubydoc.info/github/hfwang/protobuf_descriptor/master/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)
+
+```ruby
+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](http://rubydoc.info/github/hfwang/protobuf_descriptor/master/frames).
+
+## 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

@@ -41,6 +41,120 @@ task :spec => ["wire-compiler.jar"] do |t|
   # Declare this to ensure wire-compiler is downloaded
 end
 
+desc "Compiles the protocol buffer decls used by the specs"
+task :compile_spec_protos do
+  require "pathname"
+  require "tempfile"
+  require "tmpdir"
+  require "zip"
+
+  VERBOSE = ENV["VERBOSE"]
+
+  exec_proto_compiler = lambda do |args|
+    args = {
+      :source => ".",
+      :extra_args => [],
+      :plugin => nil,
+      :plugin_out => "",
+      :out => "out.desc",
+      :include_source_info => false,
+    }.merge(args)
+    args[:source] += '/' unless args[:source].end_with?('/')
+
+    command = []
+    command << "protoc"
+    command << "-I#{args[:source]}"
+    if args[:plugin]
+      command << "--#{args[:plugin]}_out=#{args[:plugin_out]}"
+    end
+    command += args[:extra_args]
+    command << "--descriptor_set_out=#{args[:out]}"
+    if args[:include_source_info]
+      command << "--include_source_info"
+    end
+    command += Dir.glob(File.join(args[:source], "**", "*.proto"))
+
+    rv = system(*command)
+
+    raise "ProtobufDescriptor generation failed!" unless rv
+  end
+
+  exec_wire_compiler = lambda do |args|
+    args = {
+      :out => ".",
+      :source => ".",
+      :extra_args => []
+    }.merge(args)
+
+    jar_path = File.realpath(File.join(File.dirname(__FILE__), "wire-compiler.jar"))
+    command = ["java", "-jar", jar_path]
+    command << "--proto_path=#{args[:source]}"
+    command += args[:extra_args]
+    command << "--java_out=#{args[:out]}"
+    sources = Dir.glob(File.join(args[:source], "**", "*.proto")).map { |p|
+      Pathname.new(p).relative_path_from(Pathname.new(args[:source])).to_s
+    }
+    command += sources
+
+    tmp_log = Tempfile.new(["wire-compiler", ".log"])
+    begin
+      rv = system(*command, out: [tmp_log.path, "a"], err: [tmp_log.path, "a"])
+      puts File.read(tmp_log) if VERBOSE
+
+      raise "Wire protobuf generation failed!\n#{File.read(tmp_log)}" unless rv
+    ensure
+      tmp_log.close
+      tmp_log.unlink
+    end
+  end
+  create_zip = lambda do |dir, dest|
+    dirpath = Pathname.new(dir)
+    File.delete(dest) if File.exist?(dest)
+    Zip::File.open(dest, Zip::File::CREATE) do |zipfile|
+      # require "pry"
+      # binding.pry
+      (Dir[File.join(dir, "**", "**")] + Dir[File.join(dir, "**")]).uniq.each do |file|
+        next if File.directory?(file)
+        relative_path = Pathname.new(file).relative_path_from(dirpath)
+        zipfile.add(relative_path, file)
+        puts "#{dest} <- #{relative_path}" if VERBOSE
+      end
+    end
+  end
+
+  file_sets = Dir["spec/protos/*"].select { |d| File.directory?(d) }
+
+  source = "spec/protos/source_info"
+  puts "Building #{source} (with included source info)"
+  exec_proto_compiler.call({
+    :out => "#{source}.srcinfo.desc",
+    :source => source,
+    :include_source_info => true
+  })
+  file_sets.each do |source|
+    puts "Building #{source}"
+    Dir.mktmpdir do |dir|
+      args = {
+        :out => "#{source}.desc",
+        :source => source,
+        :plugin => :java,
+        :plugin_out => dir
+      }
+      exec_proto_compiler.call(args)
+      create_zip.call(dir, "#{source}.java.zip")
+    end
+
+    Dir.mktmpdir do |dir|
+      args = {
+        :source => source,
+        :out => dir
+      }
+      exec_wire_compiler.call(args)
+      create_zip.call(dir, "#{source}.wire.zip")
+    end
+  end
+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

@@ -1,12 +1,12 @@
-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]
+  # See {+EnumDescriptorProto+}[https://code.google.com/p/protobuf/source/browse/trunk/src/google/protobuf/descriptor.proto#171]
   class EnumDescriptor
+    include ProtobufDescriptor::HasParent
+    include ProtobufDescriptor::NamedChild
+    include ProtobufDescriptor::HasChildren
+
     # The containing {ProtobufDescriptor::FileDescriptor} or
     # {ProtobufDescriptor::MessageDescriptor} that defines this enum.
     attr_reader :parent
@@ -14,21 +14,27 @@ class ProtobufDescriptor
     # The +EnumDescriptorProto+ this +EnumDescriptor+ is wrapping.
     attr_reader :enum_descriptor_proto
 
+    # List of the enum values for this `EnumDescriptor` as a `NamedCollection`
+    # of {ProtobufDescriptor::EnumValueDescriptor}
+    attr_reader :value
+    alias_method :values, :value
+
+    register_children(:value, 2)
+
     def initialize(parent, enum_descriptor_proto)
       @parent = parent
       @enum_descriptor_proto = enum_descriptor_proto
+
+      @value = ProtobufDescriptor::NamedCollection.new(
+          enum_descriptor_proto.value.map { |m|
+            ProtobufDescriptor::EnumValueDescriptor.new(self, m)
+          })
     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/enum_value_descriptor.rb

@@ -0,0 +1,29 @@
+class ProtobufDescriptor
+  # Describes an enum type.
+  #
+  # See {+EnumValueDescriptorProto+}[https://code.google.com/p/protobuf/source/browse/trunk/src/google/protobuf/descriptor.proto#180]
+  class EnumValueDescriptor
+    include ProtobufDescriptor::HasParent
+
+    # The containing {ProtobufDescriptor::EnumDescriptor} that this is a value
+    # for.
+    attr_reader :parent
+
+    # The +EnumValueDescriptorProto+ this +EnumValueDescriptor+ is wrapping.
+    attr_reader :enum_value_descriptor_proto
+
+    def initialize(parent, enum_value_descriptor_proto)
+      @parent = parent
+      @enum_value_descriptor_proto = enum_value_descriptor_proto
+    end
+
+    # The name of the enum value
+    def name; enum_value_descriptor_proto.name; end
+
+    # The number mapped to the enum value
+    def number; enum_value_descriptor_proto.number; end
+
+    # The +EnumValueOptions+ defined for this enum
+    def options; enum_value_descriptor_proto.options; end
+  end
+end

data/lib/protobuf_descriptor/field_descriptor.rb

@@ -0,0 +1,80 @@
+class ProtobufDescriptor
+  # 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
+    include ProtobufDescriptor::HasParent
+
+    # The parent {ProtobufDescriptor::MessageDescriptor}
+    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
+
+    # 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
+    # {ProtobufDescriptor::MessageDescriptor} or
+    # {ProtobufDescriptor::EnumDescriptor} that this field will represent.
+    def resolve_type
+      protobuf_descriptor.resolve_type_name(self.type_name, self.parent)
+    end
+  end
+end

data/lib/protobuf_descriptor/file_descriptor.rb

@@ -1,16 +1,10 @@
-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
+    include ProtobufDescriptor::HasChildren
+
     # The parent {ProtobufDescriptor}
     attr_reader :file_descriptor_set
 
@@ -29,6 +23,12 @@ class ProtobufDescriptor
     # NamedCollection of {ProtobufDescriptor::ServiceDescriptor}
     attr_reader :service
 
+    # Field index is hard-coded since these are a bit annoying to grab
+    # consistently with the different protocol buffer implementations.
+    self.register_children(:message_type, 4)
+    self.register_children(:enum_type, 5)
+    self.register_children(:service, 6)
+
     def initialize(file_descriptor_set, file_descriptor_proto) #:nodoc:
       # This is basically a parent pointer.
       @file_descriptor_set = file_descriptor_set
@@ -55,11 +55,13 @@ class ProtobufDescriptor
     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)
+    # Whether source code info is associated with this descriptor
+    def has_source_code_info?
+      file_descriptor_proto.has_field?(:source_code_info)
+    end
+
+    def source_code_info
+      file_descriptor_proto.source_code_info
     end
 
     # Filename relative to root of source tree.
@@ -77,7 +79,7 @@ class ProtobufDescriptor
     # 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?
+      if file_descriptor_proto.has_field?(:options) && present?(file_descriptor_proto.options.java_package)
         return file_descriptor_proto.options.java_package
       else
         return file_descriptor_proto.package
@@ -90,14 +92,14 @@ class ProtobufDescriptor
     # 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?
+      if file_descriptor_proto.has_field?(:options) && present?(file_descriptor_proto.options.java_multiple_files)
         return nil
-      elsif file_descriptor_proto.has_field?(:options) && file_descriptor_proto.options.java_outer_classname.present?
+      elsif file_descriptor_proto.has_field?(:options) && present?(file_descriptor_proto.options.java_outer_classname)
         return file_descriptor_proto.options.java_outer_classname
       else
         basename = name.split('/').last
         basename = basename.gsub('.proto', '')
-        return basename.camelize
+        return camelize(basename)
       end
     end
 
@@ -123,5 +125,23 @@ class ProtobufDescriptor
     def fully_qualified_ruby_name
       return "::#{self.package.gsub('.', '::')}"
     end
+
+    private
+    # Copy over a bunch of methods that are normally part of active_support:
+    def present?(string)
+      return !blank?(string)
+    end
+
+    def blank?(string)
+      string.respond_to?(:empty?) ? !!string.empty? : !string
+    end
+
+    def camelize(string)
+      if string.respond_to?(:camelize)
+        return string.camelize
+      else
+        return string.split("_").map { |s| s.capitalize }.join("")
+      end
+    end
   end
 end

data/lib/protobuf_descriptor/has_children.rb

@@ -0,0 +1,49 @@
+class ProtobufDescriptor
+  # Mixin module to support classes with different "kinds" of children
+  module HasChildren
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # To be called by the containing class, registers a set of children
+      def register_children(children_method, child_kind_id)
+        @registered_children ||= Hash.new { |h, k| h[k] = [] }
+
+        @registered_children[child_kind_id] = children_method
+      end
+
+      def registered_children
+        return @registered_children
+      end
+    end
+
+    def named_children
+      return @named_children if @named_children
+
+      @named_children = NamedCollection.new([])
+
+      self.class.registered_children.each do |id, method|
+        collection = self.send(method)
+        collection = collection.is_a?(NamedCollection) ? collection.collection : collection
+        collection.each do |m|
+          @named_children << m if m.is_a?(NamedChild)
+        end
+      end
+      return @named_children
+    end
+
+    # Computes the "relative path" from this node to one of its direct children
+    # according to the rules specified by
+    # [descriptor.proto line 506](https://code.google.com/p/protobuf/source/browse/trunk/src/google/protobuf/descriptor.proto#506).
+    def compute_source_code_info_path_component(child)
+      self.class.registered_children.each do |kind_id, collection|
+        idx = self.send(collection).find_index(child)
+        if !idx.nil?
+          return [kind_id, idx]
+        end
+      end
+      raise "Could not find #{child} in #{self}"
+    end
+  end
+end

data/lib/protobuf_descriptor/has_parent.rb

@@ -1,4 +1,11 @@
 class ProtobufDescriptor
+  # Mixin module to make accessing ancestors easier.
+  #
+  # Also has a random method for computing the source code info path (as well as
+  # methods that rely on it to do things like grab comments and the like.)
+  #
+  # Classes that include this module must respond_to `parent`, in addition their
+  # parent include `HasChildren`
   module HasParent
     def file_descriptor
       p = self.parent
@@ -15,5 +22,40 @@ class ProtobufDescriptor
       end
       return p
     end
+
+    def compute_source_code_info_path
+      path_component = parent.compute_source_code_info_path_component(self)
+      parent_path = if parent.class.name == "ProtobufDescriptor::FileDescriptor"
+                      []
+                    else
+                      parent.compute_source_code_info_path
+                    end
+      return parent_path + path_component
+    end
+
+    def source_code_info_locations
+      raise "No source code info attached!" unless file_descriptor.has_source_code_info?
+
+      source_code_info_path = compute_source_code_info_path
+      return file_descriptor.source_code_info.location.select { |location|
+        location.path == source_code_info_path
+      }
+    end
+
+    def source_code_info_location
+      return source_code_info_locations.first
+    end
+
+    def source_code_info_span
+      return source_code_info_location.span
+    end
+
+    def leading_comments
+      return source_code_info_location.leading_comments
+    end
+
+    def trailing_comments
+      return source_code_info_location.trailing_comments
+    end
   end
 end