aws-sdk-code-generator 0.1.0.pre

data/lib/aws-sdk-code-generator/generators/client_operation_documentation.rb

@@ -0,0 +1,166 @@
+module AwsSdkCodeGenerator
+  module Generators
+    class ClientOperationDocumentation
+
+      include Helper
+
+      def self.apply(options)
+        new(options).apply(options)
+      end
+
+      # @option options [required, Hash] :api
+      # @option options [required, String] :service_identifier
+      # @option options [required, String] :operation_name
+      # @option options [required, Hash] :operation
+      # @option options [Hash] :examples
+      def initialize(options)
+        @api = options.fetch(:api)
+        @service_id = options.fetch(:service_identifier)
+        @operation_name = options.fetch(:operation_name)
+        @method_name = underscore(@operation_name)
+        @operation = options.fetch(:operation)
+        @examples = options.fetch(:examples, nil) || { 'examples' => {} }
+      end
+
+      def apply(options)
+        method = options.fetch(:method)
+        method.docstring do |docstring|
+          apply_operation_docs(docstring)
+          apply_option_tags(docstring)
+          apply_return_tags(docstring)
+          apply_shared_examples(docstring)
+          apply_examples_from_disk(docstring)
+          apply_request_syntax_example(docstring)
+          apply_response_struture_example(docstring)
+          apply_overload_tag(docstring)
+        end
+      end
+
+      private
+
+      def apply_operation_docs(docstring)
+        docstring.append(markdown(@operation['documentation']))
+      end
+
+      def apply_option_tags(docstring)
+        # document the `:response_target` option if the response is streaming
+        if output = shape(@operation['output'])
+          if output['payload'] && output['members'][output['payload']]['streaming']
+            docstring.lines.concat(Dsl::OptionTag.new(
+              name: 'response_target',
+              type: 'String, IO',
+              param: 'params',
+              required: false,
+              docstring: 'Where to write response data, file path, or IO object.'
+            ).lines)
+          end
+        end
+
+        if input_shape = shape(@operation['input'])
+          required = input_shape['required'] || []
+          input_shape['members'].each_pair do |member_name, member_ref|
+            docstring.lines.concat(Dsl::OptionTag.new(
+              name: underscore(member_name),
+              type: ruby_input_type(member_ref),
+              param: 'params',
+              required: required.include?(member_name),
+              docstring: documentation(member_ref),
+            ).lines)
+          end
+        end
+      end
+
+      def apply_return_tags(docstring)
+        output_shape = shape(@operation['output'])
+        resp = '{Seahorse::Client::Response response}'
+        if output_shape && output_shape['members'].size > 0
+          type = ruby_type(@operation['output'])
+          returns = "@return [#{type}] Returns a #{resp} object which responds to "
+          returns << "the following methods:\n\n"
+          output_shape['members'].each_pair do |mname, mref|
+            mtype = ruby_type(mref).gsub(/</, '&lt;').gsub(/>/, '&gt;')
+            returns << "  * {#{type}##{underscore(mname)} ##{mname}} => #{mtype}\n"
+          end
+          docstring.append(returns)
+        else
+          docstring.append("@return [Struct] Returns an empty #{resp}.")
+        end
+      end
+
+      def apply_shared_examples(docstring)
+        (@examples[@operation_name] || []).size.times do |n|
+          begin
+            # TODO : known issue with an ec2 shared example that
+            #        attempts to document a member that is not
+            #        present in the model any longer (intentionally
+            #        removed in customizations) - raises runtime
+            #        error. This should be cleaned up.
+            docstring.append(
+              SharedExample.new(
+                operation_name: @operation_name,
+                api: @api,
+                examples: @examples,
+                example: n
+              ).to_s
+            )
+          rescue
+          end
+        end
+      end
+
+      def apply_shared_example(docstring, example)
+        return
+
+        input_comments = json_ex['comments']['input']
+        input = SharedExample.new(json_ex['input'], method_name, operation, input_comments).to_str_input
+        parts = []
+        parts << "@example Example: #{json_ex['title']}\n\n"
+        parts << "  # #{json_ex['description']}\n\n"
+        parts += input.lines.map { |line| "  " + line }
+        if json_ex['output']
+          output_comments = json_ex['comments']['output']
+          output = SharedExample.new(json_ex['output'], method_name, operation, output_comments).to_str_output
+          parts << "\n\n  # resp.to_h outputs the following:\n"
+          parts += output.lines.map { |line| "  " + line }
+        end
+        tag(parts.join)
+      end
+
+      def apply_examples_from_disk(docstring)
+        examples = File.expand_path('../../../../../../doc-src/examples', __FILE__)
+        glob = "#{examples}/#{@service_id}/client/#{@method_name}/*.rb"
+        Dir.glob(glob).map do |path|
+          title = File.basename(path).split(/\./).first
+          title = title.sub(/^\d+_/, '').gsub(/_/, ' ')
+          title = title[0].upcase + title[1..-1]
+          docstring.append("\n@example #{title}")
+          docstring.append("  " + File.read(path).lines.join('  '))
+        end
+      end
+
+      def apply_request_syntax_example(docstring)
+        if @operation['input']
+          syntax = SyntaxExample.new(
+            struct_shape: shape(@operation['input']),
+            api: @api,
+            indent: '  '
+          ).format.strip
+          docstring.append("\n@example Request syntax with placeholder values")
+          docstring.append("  resp = client.#{@method_name}(#{syntax})")
+        end
+      end
+
+      def apply_response_struture_example(docstring)
+        output = @operation['output']
+        if output && shape(output)['members'].size > 0
+          docstring.append(ResponseStructureExample.new(shape_ref:output, api:@api).to_s)
+        end
+      end
+
+      def apply_overload_tag(docstring)
+        docstring.append("@overload #{@method_name}(params = {})")
+      end
+
+    end
+  end
+end

data/lib/aws-sdk-code-generator/generators/errors_module.rb

@@ -0,0 +1,25 @@
+module AwsSdkCodeGenerator
+  module Generators
+    class ErrorsModule < Dsl::Module
+
+      include Helper
+
+      def initialize(options)
+        @api = options.fetch(:api)
+        super('Errors')
+        self.extend('Aws::Errors::DynamicErrors')
+        self.class('ResourceNotLoadable', extends: 'RuntimeError') do |c|
+          c.docstring(<<-DOCSTRING)
+Raised when calling #load or #data on a resource class that can not be
+loaded.  This can happen when:
+
+* A resource class has identifiers, but no data attributes.
+* Resource data is only available when making an API call that
+enumerates all resources of that type.
+          DOCSTRING
+        end
+      end
+
+    end
+  end
+end

data/lib/aws-sdk-code-generator/generators/resource/action.rb

@@ -0,0 +1,88 @@
+module AwsSdkCodeGenerator
+  module Generators
+    module Resource
+      class Action < Dsl::Method
+
+        include Helper
+
+        # @option options [required, String] :name
+        # @option options [required, Hash] :action
+        # @option options [required, Hash] :api
+        # @option options [String] :var_name ('')
+        def initialize(options = {})
+          @api = options.fetch(:api)
+          @request = options.fetch(:action).fetch('request')
+          @resource = options.fetch(:action).fetch('resource', nil)
+          @var_name = options.fetch(:var_name, '')
+          super(underscore(options.fetch(:name)))
+          param('options', type:Hash, default:{})
+          apply_client_request_docs
+          apply_response
+          apply_return_tag
+        end
+
+        private
+
+        def apply_client_request_docs
+          ClientRequestDocs.new(
+            request: @request,
+            api: @api,
+            var_name: @var_name,
+            returns: @resource ? @resource['type'].downcase : nil
+          ).apply(self)
+        end
+
+        def apply_response
+          if @resource && batch?(@resource)
+            code('batch = []')
+            add(client_request)
+            code(BatchBuilder.new(resource: @resource))
+            code("#{resource_type}::Collection.new([batch], size: batch.size)")
+          elsif @resource
+            add(client_request)
+            code(Builder.new(resource: @resource, request_made: true))
+          else
+            add(client_request)
+            code('resp.data')
+          end
+        end
+
+        def client_request
+          ClientRequest.new(
+            request: @request,
+            resp: true
+          )
+        end
+
+        def apply_return_tag
+          if @resource && batch?(@resource)
+            returns("#{resource_type}::Collection")
+          elsif @resource
+            returns(resource_type)
+          else
+            returns(request_return_type)
+          end
+        end
+
+        def resource_type
+          @resource['type']
+        end
+
+        def request_return_type
+          operation = @api['operations'][@request['operation']]
+          if operation['output']
+            "Types::#{operation['output']['shape']}"
+          else
+            'EmptyStructure'
+          end
+        end
+
+        def batch?(resource)
+          paths = (@resource['identifiers'] || []).map {|i| i['path'] }
+          paths << @resource['path']
+          paths.compact.any? { |path| path.match(/\[/) }
+        end
+      end
+    end
+  end
+end

data/lib/aws-sdk-code-generator/generators/resource/batch_builder.rb

@@ -0,0 +1,211 @@
+require 'set'
+
+module AwsSdkCodeGenerator
+  module Generators
+    module Resource
+      class BatchBuilder < Dsl::CodeLiteral
+
+        include Helper
+
+        # @option options [required, Hash] :resource
+        # @option options [String] :resp_var_name ('resp')
+        def initialize(options)
+          @resource = options.fetch(:resource)
+          @resp_var_name = options.fetch(:resp_var_name, 'resp')
+          verify_resource!
+          @context = loop_context
+          super()
+
+          # create nested blocks from each loop expression
+          stack = [self]
+          loops.each do |loop_expression|
+            stack.last.append(loop_expression)
+            stack << stack.last.indent
+          end
+
+          # add resource to the batch
+          stack.last.append("batch << #{resource_class}.new(#{constructor_args})")
+
+          # add closing end tags
+          stack.pop
+          stack.each { |c| c.append('end') }
+        end
+
+        private
+
+        def resource_class
+          @resource['type']
+        end
+
+        def constructor_args
+          hash = {}
+          hash.update(identifiers)
+          hash[:data] = data_path if @resource['path']
+          hash[:client] = "@client"
+          HashFormatter.new(wrap:false, inline:true).format(hash)
+        end
+
+        def identifiers
+          (@resource['identifiers'] || []).inject({}) do |hash, identifier|
+            value = relative_identifier_path(identifier)
+            hash[underscore(identifier['target']).to_sym] = value
+            hash
+          end
+        end
+
+        def data_path
+          relative_identifier_path({
+            'source' => 'data',
+            'path' => @resource['path'],
+          })
+        end
+
+        def relative_identifier_path(identifier)
+          path = identifier['path']
+          if path && path.include?('[]')
+            prefix = loops.last.match(/\|(.+)\|/)[1]
+            suffix = underscore(path[common_prefix.length..-1])
+            if @context == :options
+              suffix = suffix.gsub(/\.\w+/) { |word| "[:#{word[1..-1]}]" }
+            end
+            suffix.length == 0 ? prefix : prefix + suffix
+          else
+            ValueSource.new(identifier).to_s
+          end
+        end
+
+        def common_prefix
+          paths = plural_paths
+          if paths.empty?
+            ''
+          elsif paths.size == 1
+            # grab everything upto and including the final []
+            paths.first.match(/(.+\[\]).*?$/)[1]
+          else
+            prefix = find_prefix(paths)
+            prefix = prefix.sub(/\[\].+?$/, '[]')
+            if prefix[-2..-1] != '[]'
+              msg = 'response paths must have a common prefix ending in [], got :'
+              msg << paths.inspect
+              raise ArgumentError, msg
+            else
+              prefix
+            end
+          end
+        end
+
+        def find_prefix(paths)
+          prefix = ''
+          loop.with_index do |_, n|
+            return prefix if paths.empty?
+            letter = paths[0][n]
+            paths.each do |path|
+              return prefix if path[n].nil?
+              return prefix if path[n] != letter
+            end
+            prefix += letter
+          end
+        end
+
+        def loops
+          loop_var =
+            case @context
+            when :data then 'data.'
+            when :options then 'options'
+            when :response then "#{@resp_var_name}.data."
+            end
+
+          used_vars = Set.new
+          used_vars << loop_var
+
+          parts = common_prefix.split('[]')
+          parts = parts.map.with_index do |part,n|
+            part = underscore(part)
+            if @context == :options
+              part = part.gsub(/\w+/) { |word| "[:#{word}]" }
+              part = part.gsub(/\./, '')
+            end
+            part = "#{loop_var}#{part}"
+            loop_var = loop_letter(part, used_vars)
+            part = part + ".each do |#{loop_var}|"
+            part
+          end
+          parts
+        end
+
+        def loop_letter(str, used_vars)
+          letter = if @context == :options
+            str.scan(/:\w/).last[1]
+          else
+            str.split('.').last[0]
+          end
+          n = 1
+          var = letter
+          while used_vars.include?(var)
+            n += 1
+            var = "#{letter}#{n}"
+          end
+          used_vars << var
+          var
+        end
+
+        def all_plural_paths
+          paths = {}
+          @resource['identifiers'].each do |i|
+            if i['path'] && i['path'].include?('[]')
+              paths[i['source']] ||= []
+              paths[i['source']] << i['path']
+            end
+          end
+          #if @resource['path'] && @resource['path'].include?('[]')
+          #  type = @context == :data ? 'data' : 'response'
+          #  paths[type] ||= []
+          #  paths[type] << @resource['path']
+          #end
+          paths
+        end
+
+        def plural_paths
+          all_plural_paths.values.first
+        end
+
+        def verify_resource!
+          verify_plural_paths!
+        end
+
+        def verify_plural_paths!
+          paths = all_plural_paths
+          case paths.size
+          when 0
+            msg = 'expected at least one plural identifier path, got none'
+            raise ArgumentError, msg
+          when 1
+            case paths.keys.first
+            when 'requestParameter'
+            when 'response'
+            when 'data'
+            else
+              msg = "unsupported identifier source #{paths.keys.first.inspect}"
+              raise ArgumentError, msg
+            end
+          else
+            msg = 'mixing plural source types is not supported'
+            raise ArgumentError, msg
+          end
+        end
+
+        def loop_context
+          case all_plural_paths.keys
+          when ['response'] then :response
+          when ['data'] then :data
+          when ['requestParameter'] then :options
+          else
+            msg = "unable to determine loop context: #{@resource.inspect}"
+            raise msg
+          end
+        end
+
+      end
+    end
+  end
+end