google-apis-generator 0.1.0

data/lib/google/apis/generator.rb

@@ -0,0 +1,99 @@
+# Copyright 2015 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'google/apis/discovery_v1'
+require 'google/apis/generator/annotator'
+require 'google/apis/generator/model'
+require 'google/apis/generator/template'
+require 'google/apis/generator/updater'
+require 'google/apis/generator/version'
+require 'active_support'
+require 'active_support/core_ext'
+require 'active_support/inflector'
+require 'yaml'
+
+module Google
+  module Apis
+    # Generates ruby classes for APIs from discovery documents
+    # @private
+    class Generator
+      Discovery = Google::Apis::DiscoveryV1
+
+      Result = Struct.new :files, :version_path, :changelog_path, :gem_name, :revision
+
+      # Load templates
+      def initialize(api_names: nil, api_names_out: nil)
+        @names = Google::Apis::Generator::Names.new(api_names_out || File.join(Google::Apis::ROOT, "api_names_out.yaml"),
+                                                    api_names || File.join(Google::Apis::ROOT, "api_names.yaml"))
+        @templates = {}
+      end
+
+      # Generates ruby source for an API
+      #
+      # @param [String] json
+      #  API Description, as JSON text
+      # @return [Hash<String,String>]
+      #  Hash of generated files keyed by path
+      def render(json)
+        api = parse_description(json)
+        Annotator.process(api, @names)
+        context = {
+          "api" => api,
+          "generator_version" => Google::Apis::Generator::VERSION
+        }
+
+        base_path = api.gem_name
+        lib_path = File.join(base_path, "lib")
+        spec_path = File.join(base_path, "spec")
+        module_path = File.join(lib_path, ActiveSupport::Inflector.underscore(api.qualified_name))
+
+        result = Result.new({},
+                            File.join(module_path, "gem_version.rb"),
+                            File.join(base_path, "CHANGELOG.md"),
+                            api.gem_name,
+                            api.revision)
+        result.files[File.join(base_path, ".rspec")] = render_template("dot-rspec", context)
+        result.files[File.join(base_path, ".yardopts")] = render_template("dot-yardopts", context)
+        result.files[result.changelog_path] = render_template("initial-changelog.md", context)
+        result.files[File.join(base_path, "Gemfile")] = render_template("gemfile", context)
+        result.files[File.join(base_path, "#{api.gem_name}.gemspec")] = render_template("gemspec", context)
+        result.files[File.join(base_path, "LICENSE.md")] = render_template("license.md", context)
+        result.files[File.join(base_path, "OVERVIEW.md")] = render_template("overview.md", context)
+        result.files[File.join(base_path, "Rakefile")] = render_template("rakefile", context)
+        result.files[File.join(lib_path, "#{api.gem_name}.rb")] = render_template("entry-point.rb", context)
+        result.files[module_path + ".rb"] = render_template("module.rb", context)
+        result.files[File.join(module_path, "classes.rb")] = render_template("classes.rb", context)
+        result.files[File.join(module_path, "representations.rb")] = render_template("representations.rb", context)
+        result.files[File.join(module_path, "service.rb")] = render_template("service.rb", context)
+        result.files[result.version_path] = render_template("initial-gem_version.rb", context)
+        result.files[File.join(spec_path, "generated_spec.rb")] = render_template("generated_spec.rb", context)
+        result
+      end
+
+      def render_template(name, context)
+        (@templates[name] ||= Template.load(name)).render(context)
+      end
+
+      # Dump mapping of API names
+      # @return [String] Mapping of paths to ruby names in YAML format
+      def dump_api_names
+        @names.dump
+      end
+
+      def parse_description(json)
+        Discovery::RestDescription::Representation.new(Discovery::RestDescription.new).from_json(json)
+      end
+    end
+  end
+end

data/lib/google/apis/generator/annotator.rb

@@ -0,0 +1,339 @@
+# Copyright 2015 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'logger'
+require 'erb'
+require 'yaml'
+require 'json'
+require 'active_support/inflector'
+require 'google/apis/core/logging'
+require 'google/apis/generator/template'
+require 'google/apis/generator/model'
+require 'google/apis/generator/helpers'
+require 'addressable/uri'
+
+module Google
+  module Apis
+
+    # @private
+    class Generator
+
+      # Helper for picking names for methods, properties, types, etc. Performs various normaliations
+      # as well as allows for overriding individual names from a configuration file for cases
+      # where algorithmic approaches produce poor APIs.
+      class Names
+        ActiveSupport::Inflector.inflections do |inflections|
+          inflections.uncountable('send_as', 'as')
+          inflections.irregular('drive', 'drives')
+          inflections.irregular('teamdrive', 'teamdrives')
+        end
+
+        include Google::Apis::Core::Logging
+        include NameHelpers
+
+        def initialize(names_out_file_path = nil, names_file_path = nil)
+          if names_out_file_path && File.file?(names_out_file_path)
+            logger.info { sprintf('Loading API names from %s', names_out_file_path) }
+            @names = YAML.load(File.read(names_out_file_path)) || {}
+          else
+            @names = {}
+          end
+          if names_file_path && File.file?(names_file_path)
+            logger.info { sprintf('Loading API names from %s', names_file_path) }
+            @names = @names.merge(YAML.load(File.read(names_file_path)) || {})
+          end
+          @path = []
+        end
+
+        def with_path(path)
+          @path.push(path)
+          begin
+            yield
+          ensure
+            @path.pop
+          end
+        end
+
+        def infer_parameter_name
+          pick_name(normalize_param_name(@path.last))
+        end
+
+        def infer_property_name
+          pick_name(normalize_property_name(@path.last))
+        end
+
+        def pick_name(alt_name)
+          preferred_name = @names[key]
+          if preferred_name && preferred_name == alt_name
+            # logger.warn { sprintf("Unnecessary name override '%s': %s", key, alt_name) }
+          elsif preferred_name.nil?
+            preferred_name = @names[key] = alt_name
+          end
+          preferred_name
+        end
+
+        def [](key)
+          @names[key]
+        end
+
+        def []=(key, value)
+          @names[key] = value
+        end
+
+        def dump
+          YAML.dump(Hash[@names.sort])
+        end
+
+        def key
+          @path.reduce('') { |a, e| a + '/' + e }
+        end
+
+        def option(opt_name)
+          @names[sprintf('%s?%s', key, opt_name)]
+        end
+
+        # For RPC style methods, pick a name based off the request objects.
+        # @param [Google::Apis::DiscoveryV1::RestMethod] method
+        # @param [Boolean] pick_name
+        #  Fragment of the discovery doc describing the method
+        def infer_method_name_for_rpc(method, pick_name = true)
+          return nil if method.request.nil?
+          parts = method.id.split('.')
+          parts.shift
+          verb = ActiveSupport::Inflector.underscore(parts.pop)
+          match = method.request._ref.match(/(.*)(?i:request)/)
+          return nil if match.nil?
+          name = ActiveSupport::Inflector.underscore(match[1])
+          return nil unless name == verb || name.start_with?(verb + '_')
+          if !parts.empty?
+            resource_name = ActiveSupport::Inflector.singularize(parts.pop)
+            resource_name = ActiveSupport::Inflector.underscore(resource_name)
+            if !name.include?(resource_name)
+              name = name.split('_').insert(1, resource_name).join('_')
+            end
+          end
+          if pick_name
+            pick_name(name)
+          else
+            name
+          end
+        end
+
+        # For REST style methods, build a method name from the verb/resource(s) in the method
+        # id. IDs are in the form <api>.<resource>.<verb>
+        # @param [Google::Apis::DiscoveryV1::RestMethod] method
+        #  Fragment of the discovery doc describing the method
+        def infer_method_name_from_id(method)
+          parts = method.id.split('.')
+          parts.shift
+          verb = ActiveSupport::Inflector.underscore(parts.pop)
+          return verb if parts.empty?
+          resource_name = ActiveSupport::Inflector.underscore(parts.pop)
+          if pluralize_method?(verb)
+            resource_name = ActiveSupport::Inflector.pluralize(resource_name)
+          else
+            resource_name = ActiveSupport::Inflector.singularize(resource_name)
+          end
+          if parts.empty?
+            resource_path = resource_name
+          else
+            resource_path = parts.map do |p|
+              p = ActiveSupport::Inflector.singularize(p)
+              ActiveSupport::Inflector.underscore(p)
+            end.join('_') + '_' + resource_name
+          end
+          method_name = verb.split('_').insert(1, resource_path.split('_')).join('_')
+          pick_name(method_name)
+        end
+      end
+
+      # Modifies an API description to support ruby code generation. Primarily does:
+      # - Ensure all names follow appopriate ruby conventions
+      # - Maps types to ruby types, classes, and resolves $refs
+      # - Attempts to simplify names where possible to make APIs more sensible
+      class Annotator
+        include NameHelpers
+        include Google::Apis::Core::Logging
+
+        # Prepare the API for the templates.
+        # @param [Google::Apis::DiscoveryV1::RestDescription] description
+        #  API Description
+        def self.process(description, api_names = nil)
+          Annotator.new(description, api_names).annotate_api
+        end
+
+        # @param [Google::Apis::DiscoveryV1::RestDescription] description
+        #  API Description
+        # @param [Google::Api::Generator::Names] api_names
+        #  Name helper instanace
+        def initialize(description, api_names = nil)
+          api_names = Names.new if api_names.nil?
+          @names = api_names
+          @rest_description = description
+          @registered_types = []
+          @deferred_types = []
+          @strip_prefixes = []
+          @all_methods = {}
+          @dup_method_names_for_rpc = collect_dup_method_names_for_rpc
+          @path = []
+        end
+
+        def collect_method_names_for_rpc(resource, method_names_for_rpc)
+          resource.api_methods.each do |_k, v|
+            # First look for the method name in the `@names` hash. If there's
+            # no override set, generate it without inserting the generated name
+            # into the `@names` hash.
+            method_name_for_rpc = @names[@names.key]
+            if method_name_for_rpc.nil?
+              method_name_for_rpc = @names.infer_method_name_for_rpc(v, false)
+            end
+            method_names_for_rpc << method_name_for_rpc if method_name_for_rpc
+          end unless resource.api_methods.nil?
+
+          resource.resources.each do |_k, v|
+            collect_method_names_for_rpc(v, method_names_for_rpc)
+          end unless resource.resources.nil?
+        end
+
+        def collect_dup_method_names_for_rpc
+          method_names_for_rpc = []
+          collect_method_names_for_rpc(@rest_description, method_names_for_rpc)
+          method_names_for_rpc.group_by{ |e| e }.select { |k, v| v.size > 1 }.map(&:first)
+        end
+
+        def annotate_api
+          @names.with_path(@rest_description.id) do
+            @strip_prefixes << @rest_description.name
+            if @rest_description.auth
+              @rest_description.auth.oauth2.scopes.each do |key, value|
+                value.constant = constantize_scope(key)
+              end
+            end
+            @rest_description.force_alt_json = @names.option('force_alt_json')
+            annotate_parameters(@rest_description.parameters)
+            annotate_resource(@rest_description.name, @rest_description)
+            @rest_description.schemas.each do |k, v|
+              annotate_type(k, v, @rest_description)
+            end unless @rest_description.schemas.nil?
+          end
+          resolve_type_references
+          resolve_variants
+        end
+
+        def annotate_type(name, type, parent)
+          @names.with_path(name) do
+            type.name = name
+            type.path = @names.key
+            type.generated_name = @names.infer_property_name
+            if type.type == 'object'
+              type.generated_class_name = ActiveSupport::Inflector.camelize(type.generated_name)
+              @registered_types << type
+            end
+            type.parent = parent
+            @deferred_types << type if type._ref
+            type.properties.each do |k, v|
+              annotate_type(k, v, type)
+            end unless type.properties.nil?
+            if type.additional_properties
+              type.type = 'hash'
+              annotate_type(ActiveSupport::Inflector.singularize(type.generated_name), type.additional_properties,
+                            parent)
+            end
+            annotate_type(ActiveSupport::Inflector.singularize(type.generated_name), type.items, parent) if type.items
+          end
+        end
+
+        def annotate_resource(name, resource, parent_resource = nil)
+          @strip_prefixes << name
+          resource.parent = parent_resource unless parent_resource.nil?
+          resource.api_methods.each do |_k, v|
+            annotate_method(v, resource)
+          end unless resource.api_methods.nil?
+
+          resource.resources.each do |k, v|
+            annotate_resource(k, v, resource)
+          end unless resource.resources.nil?
+        end
+
+        def annotate_method(method, parent_resource = nil)
+          @names.with_path(method.id) do
+            method.parent = parent_resource
+	    # Grab the method name generated from the request object without
+	    # inserting into, or querying, the names hash.
+            method_name_for_rpc = @names.infer_method_name_for_rpc(method, false)
+	    # If `method_name_for_rpc` is a duplicate (more than one method in
+	    # the API will generate this name), generate the method name from
+	    # the method ID instead.
+            if @dup_method_names_for_rpc.include?(method_name_for_rpc)
+              method.generated_name = @names.infer_method_name_from_id(method)
+            # Otherwise, proceed as normal.
+            elsif method_name_for_rpc
+              method.generated_name = @names.infer_method_name_for_rpc(method)
+            else
+              method.generated_name = @names.infer_method_name_from_id(method)
+            end
+            check_duplicate_method(method)
+            annotate_parameters(method.parameters)
+          end
+        end
+
+        def annotate_parameters(parameters)
+          parameters.each do |key, value|
+            @names.with_path(key) do
+              value.name = key
+              value.generated_name = @names.infer_parameter_name
+              @deferred_types << value if value._ref
+            end
+          end unless parameters.nil?
+        end
+
+        def resolve_type_references
+          @deferred_types.each do |type|
+            if type._ref
+              ref = @rest_description.schemas[type._ref]
+              ivars = ref.instance_variables - [:@name, :@generated_name]
+              (ivars).each do |var|
+                type.instance_variable_set(var, ref.instance_variable_get(var))
+              end
+            end
+          end
+        end
+
+        def resolve_variants
+          @deferred_types.each do |type|
+            if type.variant
+              type.variant.map.each do |v|
+                ref = @rest_description.schemas[v._ref]
+                ref.base_ref = type
+                ref.discriminant = type.variant.discriminant
+                ref.discriminant_value = v.type_value
+              end
+            end
+          end
+        end
+
+        def check_duplicate_method(m)
+          if @all_methods.include?(m.generated_name)
+            logger.error do
+              sprintf('Duplicate method %s generated, conflicting paths %s and %s',
+                m.generated_name, @names.key, @all_methods[m.generated_name])
+            end
+            fail 'Duplicate name generated'
+          end
+          @all_methods[m.generated_name] = @names.key
+        end
+      end
+    end
+  end
+end

data/lib/google/apis/generator/helpers.rb

@@ -0,0 +1,78 @@
+require 'active_support/inflector'
+
+module Google
+  module Apis
+    # @private
+    class Generator
+      # Methods for validating & normalizing symbols
+      module NameHelpers
+        KEYWORDS = %w(__ENCODING__ def in self __LINE__ defined? module super __FILE__ do next then BEGIN
+                      else nil true END elsif not undef alias end or unless and ensure redo until begin
+                      false rescue when break for retry while case if return yield class command)
+        PLURAL_METHODS = %w(list search)
+
+        # Check to see if the method name should be plauralized
+        # @return [Boolean]
+        def pluralize_method?(method_name)
+          PLURAL_METHODS.include?(method_name)
+        end
+
+        # Check to see if the method is either a keyword or built-in method on object
+        # @return [Boolean]
+        def reserved?(name)
+          keyword?(name) || object_method?(name)
+        end
+
+        # Check to see if the name is a ruby keyword
+        # @return [Boolean]
+        def keyword?(name)
+          KEYWORDS.include?(name)
+        end
+
+        # Check to see if the method already exists on ruby objects
+        # @return [Boolean]
+        def object_method?(name)
+          Object.new.respond_to?(name)
+        end
+
+        # Convert a parameter name to ruby conventions
+        # @param [String] name
+        # @return [String] updated param name
+        def normalize_param_name(name)
+          name = name.gsub(/\W/, '_')
+          name = name.gsub(/IPv4/, 'Ipv4')
+          name = ActiveSupport::Inflector.underscore(name)
+          if reserved?(name)
+            logger.warn { sprintf('Found reserved keyword \'%1$s\'', name) }
+            name += '_'
+            logger.warn { sprintf('Changed to \'%1$s\'', name) }
+          end
+          name
+        end
+
+        # Convert a property name to ruby conventions
+        # @param [String] name
+        # @return [String]
+        def normalize_property_name(name)
+          name = ActiveSupport::Inflector.underscore(name.gsub(/\W/, '_'))
+          if object_method?(name)
+            logger.warn { sprintf('Found reserved property \'%1$s\'', name) }
+            name += '_prop'
+            logger.warn { sprintf('Changed to \'%1$s\'', name) }
+          end
+          name
+        end
+
+        # Converts a scope string into a ruby constant
+        # @param [String] url
+        #   Url to convert
+        # @return [String]
+        def constantize_scope(url)
+          scope = Addressable::URI.parse(url).path[1..-1].upcase.gsub(/\W/, '_')
+          scope = 'AUTH_SCOPE' if scope.nil? || scope.empty?
+          scope
+        end
+      end
+    end
+  end
+end