RubyGems - aws-sdk-code-generator - Versions diffs - 0.1.0.pre → 0.2.4.pre - Mend

aws-sdk-code-generator 0.1.0.pre → 0.2.4.pre

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (155) hide show

data/lib/aws-sdk-code-generator/docstring.rb ADDED Viewed

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+# kramdown
+require 'kramdown'
+# end kramdown
+module AwsSdkCodeGenerator
+  module Docstring
+    class << self
+      # Prefixes each line of `text` with a pound sign. Given the string
+      #
+      #     Hello
+      #     World
+      #
+      # The following string would be returned:
+      #
+      #     # Hello
+      #     # World
+      #
+      # @param [String, nil] text
+      # @option options [String] :gap (' ')
+      # @return [String, nil]
+      def block_comment(text, options = {})
+        if text
+          gap = options.fetch(:gap, ' ')
+          text.lines.map do |line|
+            line = line.rstrip
+            if line == ''
+              "#"
+            else
+              "##{gap}#{line}"
+            end
+          end.join("\n")
+        end
+      end
+      # Joins multiple doc strings into a single doc block. Each entry
+      # in the given `docstrings` array can be a string, nil, or an another array.
+      # Arrays are flattened, and nils are compacted out.
+      #
+      # Given the following `docstrings`:
+      #
+      #     [
+      #       "First doc block",
+      #       nil,
+      #       "Second doc block\nthat contains\nmultiple lines\n",
+      #       [
+      #         "Third doc block\n",
+      #         "Last doc block\n",
+      #       ],
+      #     ]
+      #
+      # The following joined doc block would be returned:
+      #
+      #     # First doc block
+      #     #
+      #     # Second doc block
+      #     # that contains
+      #     # multiple lines
+      #     #
+      #     # Third doc block
+      #     #
+      #     # Last doc block
+      #
+      # @param [Array<String>] docstrings
+      #
+      # @option options [Boolean] :block_comment (true)
+      #   By default, each docstring is commented by passing
+      #   it to {Docstring.block_comment}. Setting `:block_comment` to
+      #   false disables this behavior.
+      #
+      # @option options [String] :gap (' ')
+      #   This option is given to {Docstring.block_comment} when
+      #   `:block_comment` is `true`.
+      #
+      # @option options [String] :separator (true)
+      #   When `true`, a blank line is inserted between
+      #   each documentation section.
+      #
+      # @return [String, nil] If the given `docstrings` is empty,
+      #   then a `nil` is returned.
+      #
+      def join_docstrings(docstrings, options = {})
+        docs = docstrings.flatten.inject([]) do |sections, section|
+          if section.nil? || section.size == 0
+            sections
+          else
+            sections << (options.fetch(:block_comment, true) ?
+              block_comment(section, options) :
+              section)
+            sections << (options.fetch(:separator, true) ? "\n#\n" : "\n")
+            sections
+          end
+        end
+        if docs.empty?
+          nil
+        else
+          docs[-1] = docs[-1].rstrip
+          docs.join
+        end
+      end
+      # @param [String]
+      # @return [String]
+      def escape_html(string)
+        string.to_s.encode(:xml => :text)
+      end
+      # kramdown html
+      # @param [String<HTML>, nil] html
+      # @option options [Integer] :line_width (70)
+      # @return [String<Markdown>, nil]
+      def html_to_markdown(html, options = {})
+        line_width = options.fetch(:line_width, 70)
+        # TODO : this section of code is **very slow** and runs many times
+        #   while building a service.
+        if html
+          html = "<p>#{html}</p>" unless html.match(/<\w+>/)
+          # unescaped curly braces cause YARD errors, they are interpreted
+          # as code links.
+          html = html.gsub('{', "\\{").gsub('}', "\\}")
+          # Kramdown generates invalid markup when there are attributes
+          # on the code tag, have to reduce these down to get the proper markdown.
+          html = html.gsub(/<code.*?>(.+?)<\/code>/) { "<code>#{$1}</code>" }
+          # Kramdown creates invalid markup with target="_blank" attributes.
+          html = html.gsub(' target="_blank"', '')
+          # There are quite a few empty <a> tags. These appear to be code names,
+          # such as structure member names, or structure type names. We should
+          # investigate if it is possible to inflect these properly and then
+          # turn them into YARD links.
+          html = html.gsub(/<a>(.+?)<\/a>/) { $1 }
+          # For span tags, it can contain customized attributes, e.g. data-target
+          # keeping text context only for now
+          html = html.gsub(/<span.*?>(.+?)<\/span>/) { $1 }
+          # <important> tag doesn't render well
+          html = html.gsub(/<important>(.+?)<\/important>/){ "<p>#{$1}</p>" }
+          # <replaceable> doesn't render anything, so sub it out for italic
+          html = html.gsub(/<replaceable>(.+?)<\/replaceable>/) { "<i>#{$1}</i>" }
+          markdown = Kramdown::Document.new(
+            html,
+            input: 'html',
+            line_width: line_width,
+            auto_ids: false
+          ).to_kramdown.strip
+          # remove extra escape
+          markdown.gsub(/\\(\*|`|'|")/, '\1')
+        end
+      end
+      # end kramdown html
+      # @param [Array<Array<String>>]
+      def markdown_table(table)
+        # compute the width of each column by scanning for longest values
+        column_width = lambda do |col|
+          table.map { |row| row[col].size }.max
+        end
+        widths = [
+          column_width.call(0),
+          column_width.call(1),
+          column_width.call(2),
+          column_width.call(3),
+        ]
+        # insert a dashed line after the header row
+        table = [
+          table[0],
+          ['-' * widths[0], '-' * widths[1], '-' * widths[2], '-' * widths[3]]
+        ] + table[1..-1]
+        # build the final table
+        line = "| #{widths.map{|n| "%-#{n}s" }.join(' | ')} |"
+        table.map { |row| line % row }.join("\n")
+      end
+      def ucfirst(string)
+        if string
+          string[0].upcase + string[1..-1]
+        end
+      end
+      def indent(string, space = '  ')
+        string.lines.map do |line|
+          "#{space}#{line}"
+        end.join.lstrip
+      end
+    end
+  end
+end

data/lib/aws-sdk-code-generator/error_list.rb ADDED Viewed

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+module AwsSdkCodeGenerator
+  class ErrorList
+    include Enumerable
+    def initialize(options)
+      @api = options[:api]
+      @module_name = options[:module_name]
+      @errors = @api['shapes'].inject([]) do |es, (name, shape)|
+        # only generate error shape with non empty members
+        # excluding event shapes marked as error
+        if error_struct?(shape)
+          members = shape['members'].inject([]) do |arr, (k, v)|
+            arr << {
+              name: Underscore.underscore(k),
+              type: Docstring.ucfirst(v['type'] ||'String'),
+              shared: k.downcase == 'message' || k.downcase == 'code'
+            }
+            arr
+          end
+          es << Error.new(
+            name: name,
+            members: members,
+            data_type: "#{@module_name}::Types::#{name}",
+            retryable: !!shape['retryable'],
+            throttling: throttling?(shape)
+          )
+        end
+        es
+      end
+    end
+    def error_struct?(shape)
+      shape['type'] == 'structure' && !!!shape['event'] &&
+        (shape['error'] || shape['exception'])
+    end
+    def each(&block)
+      @errors.each(&block)
+    end
+    def throttling?(shape)
+      shape['retryable'] && shape['retryable'].kind_of?(Hash) && shape['retryable']['throttling']
+    end
+    class Error
+      def initialize(options)
+        @name = options.fetch(:name)
+        @data_type = options[:data_type]
+        @members = options[:members]
+        @retryable = options[:retryable]
+        @throttling = options[:throttling]
+      end
+      # @return [String]
+      attr_reader :name
+      # @return [String]
+      attr_reader :data_type
+      # @return [Array<Hash>]
+      attr_reader :members
+      # @return [Boolean]
+      attr_reader :retryable
+      # @return [Boolean]
+      attr_reader :throttling
+    end
+  end
+end

data/lib/aws-sdk-code-generator/errors.rb CHANGED Viewed

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
 module AwsSdkCodeGenerator
   module Errors

data/lib/aws-sdk-code-generator/eventstream_example.rb ADDED Viewed

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+module AwsSdkCodeGenerator
+  class EventStreamExample
+    def initialize(options = {})
+      @api = options.fetch(:api)
+      @method_name = options.fetch(:method_name)
+      @module_name = options.fetch(:module_name)
+      @receiver = options.fetch(:receiver)
+      @resp_var = options.fetch(:resp_var)
+      @operation = options.fetch(:operation)
+      @input_eventstream_member, @input_eventstream_shape = input_eventstream_shape
+      @output_eventstream_member, @output_eventstream_shape = output_eventstream_shape
+      if @input_eventstream_shape && @output_eventstream_shape &&
+          @input_eventstream_shape == @output_eventstream_shape
+        # input and output sharing same eventstream
+        # renaming, see EventStreamModules
+        @input_eventstream = "#{@module_name}::EventStreams::Input#{@input_eventstream_shape}"
+        @output_eventstream = "#{@module_name}::EventStreams::Output#{@output_eventstream_shape}"
+      else
+        @input_eventstream = "#{@module_name}::EventStreams::#{@input_eventstream_shape}" if @input_eventstream_shape
+        @output_eventstream = "#{@module_name}::EventStreams::#{@output_eventstream_shape}" if @output_eventstream_shape
+      end
+    end
+    def format
+      if @input_eventstream_member && @output_eventstream_member
+        bi_directional_format
+      elsif @output_eventstream_member
+        output_format
+     # elsif @input_eventstream_member
+       # input stream only is supported naturally, but
+       # unclear usage when just input streaming, so pending for now
+      end
+    end
+    def bi_directional_format
+      <<-EXAMPLE.strip
+# @example Bi-directional EventStream Operation Example
+#
+#   You can signal input events after initial request is
+#   established, events will be sent to stream
+#   immediately (once stream connection is established successfully).
+#
+#   To signal events, you can call #signal methods from an #{@input_eventstream} object.
+#   Make sure signal events before calling #wait or #join! at async response.
+#
+#     input_stream = #{@input_eventstream}.new
+#
+#     async_resp = #{@receiver}.#{@method_name}( # params input,
+#       input_event_stream_handler: input_stream) do |out_stream|
+#
+#       # register callbacks for events arrival
+#{event_entry(:output, 'out_stream', 2)}
+#
+#     end
+#     # => returns Aws::Seahorse::Client::AsyncResponse
+#
+#     # signal events
+#{event_entry(:input, 'input_stream')}
+#
+#     # make sure signaling :end_stream in the end
+#     input_stream.signal_end_stream
+#
+#     # wait until stream is closed before finalizing sync response
+#     resp = async_resp.wait
+#     # Or close stream and finalizing sync response immediately
+#     # resp = async_resp.join!
+#
+#   Inorder to streamingly processing events received, you can also provide an #{@output_eventstream}
+#   object to register callbacks before initializing request instead of processing from request block
+#
+#     output_stream = #{@output_eventstream}.new
+#     # register callbacks for events arrival
+#{event_entry(:output, 'output_stream')}
+#{error_event_entry('output_stream')}
+#
+#     async_resp = #{@receiver}.#{@method_name} ( #params input,
+#       input_event_stream_handler: input_stream
+#       output_event_stream_handler: output_stream
+#     )
+#
+#     resp = async_resp.wait!
+#
+#   Besides above usage patterns for process events when they arrive immediately, you can also
+#   iterate through events after response complete.
+#
+#   Events are available at #{@resp_var}.#{@output_eventstream_member} # => Enumerator
+      EXAMPLE
+    end
+    def output_format
+      <<-EXAMPLE.strip
+# @example EventStream Operation Example
+#
+#   You can process event once it arrives immediately, or wait until
+#   full response complete and iterate through eventstream enumerator.
+#
+#   To interact with event immediately, you need to register ##{@method_name}
+#   with callbacks, callbacks can be register for specifc events or for all events,
+#   callback for errors in the event stream is also available for register.
+#
+#   Callbacks can be passed in by `:event_stream_handler` option or within block
+#   statement attached to ##{@method_name} call directly. Hybrid pattern of both
+#   is also supported.
+#
+#   `:event_stream_handler` option takes in either Proc object or
+#   #{@output_eventstream} object.
+#
+#   Usage pattern a): callbacks with a block attached to ##{@method_name}
+#     Example for registering callbacks for all event types and error event
+#
+#     #{@receiver}.#{@method_name}( # params input# ) do |stream|
+#{error_event_entry('stream', 2)}
+#
+#       stream.on_event do |event|
+#         # process all events arrive
+#         puts event.event_type
+#         ...
+#       end
+#
+#     end
+#
+#   Usage pattern b): pass in `:event_stream_handler` for ##{@method_name}
+#
+#     1) create a #{@output_eventstream} object
+#     Example for registering callbacks with specific events
+#
+#       handler = #{@output_eventstream}.new
+#{event_entry(:output, 'handler', 2)}
+#
+#     #{@receiver}.#{@method_name}( # params input #, event_stream_handler: handler)
+#
+#     2) use a Ruby Proc object
+#     Example for registering callbacks with specific events
+#
+#     handler = Proc.new do |stream|
+#{event_entry(:output, 'stream', 2)}
+#     end
+#
+#     #{@receiver}.#{@method_name}( # params input #, event_stream_handler: handler)
+#
+#   Usage pattern c): hybird pattern of a) and b)
+#
+#       handler = #{@output_eventstream}.new
+#{event_entry(:output, 'handler', 2)}
+#
+#     #{@receiver}.#{@method_name}( # params input #, event_stream_handler: handler) do |stream|
+#{error_event_entry('stream', 2)}
+#     end
+#
+#   Besides above usage patterns for process events when they arrive immediately, you can also
+#   iterate through events after response complete.
+#
+#   Events are available at #{@resp_var}.#{@output_eventstream_member} # => Enumerator
+#   For parameter input example, please refer to following request syntax
+      EXAMPLE
+    end
+    def event_entry(type, ctx, indent = 0)
+      case type
+      when :input then input_event_entries(ctx, indent)
+      when :output then output_event_entries(ctx, indent)
+      end
+    end
+    def error_event_entry(ctx, indent = 0)
+      entries = []
+      entries << "#     #{' ' * indent}#{ctx}.on_error_event do |event|"
+      entries << "#     #{' ' * indent}  # catch unmodeled error event in the stream"
+      entries << "#     #{' ' * indent}  raise event"
+      entries << "#     #{' ' * indent}  # => Aws::Errors::EventError"
+      entries << "#     #{' ' * indent}  # event.event_type => :error"
+      entries << "#     #{' ' * indent}  # event.error_code => String"
+      entries << "#     #{' ' * indent}  # event.error_message => String"
+      entries << "#     #{' ' * indent}end"
+      entries.join("\n")
+    end
+    def input_event_entries(ctx, indent = 0)
+      @api['shapes'][@input_eventstream_shape]['members'].each.inject([]) do |entries, (name, _)|
+        event_type = Underscore.underscore(name)
+        # TODO, place holder values
+        entries << "#     #{' ' * indent}#{ctx}.signal_#{event_type}_event( ... )"
+        entries
+      end.join("\n")
+    end
+    def output_event_entries(ctx, indent = 0)
+      @api['shapes'][@output_eventstream_shape]['members'].keys.each.inject([]) do |entry, name|
+        event_type = Underscore.underscore(name)
+        entry << "#     #{' ' * indent}#{ctx}.on_#{event_type}_event do |event|"
+        entry << "#       #{' ' * indent}event # => #{@module_name}::Types::#{name}"
+        entry << "#     #{' ' * indent}end"
+      end.join("\n")
+    end
+    def input_eventstream_shape
+      input_shape = @api['shapes'][@operation['input']['shape']] if @operation['input']
+      if input_shape
+        input_shape['members'].each do |name, ref|
+          return [Underscore.underscore(name), ref['shape']] if Api.eventstream?(ref, @api)
+        end
+      end
+      nil
+    end
+    def output_eventstream_shape
+      output_shape = @api['shapes'][@operation['output']['shape']] if @operation['output']
+      if output_shape
+        output_shape['members'].each do |name, ref|
+          return [Underscore.underscore(name), ref['shape']] if Api.eventstream?(ref, @api)
+        end
+      end
+      nil
+    end
+  end
+end

data/lib/aws-sdk-code-generator/gem_builder.rb CHANGED Viewed

@@ -1,25 +1,37 @@
+# frozen_string_literal: true
 module AwsSdkCodeGenerator
   class GemBuilder
     # @param [Hash] options
-    # @option options [required, Service] :service
+    # @option (see CodeBuilder#initialize)
     def initialize(options)
       @options = options
       @service = options.fetch(:service)
+      validate_model!
     end
     # @return [Hash]
     attr_reader :options
+    def validate_model!
+      validate_document_support!
+    end
     def each(&block)
       Enumerator.new do |y|
-        y.yield(gemspec_path, gemspec_file)
-        y.yield(features_env_path, features_env_file)
-        y.yield(features_step_definitions_path, features_step_definitions_file)
-        y.yield(spec_helper_path, spec_helper_file)
-        y.yield(version_path, version_file)
+        y.yield("#{@service.gem_name}.gemspec", gemspec_file)
+        y.yield('features/env.rb', features_env_file)
+        y.yield('features/step_definitions.rb', features_step_definitions_file)
+        y.yield('spec/spec_helper.rb', spec_helper_file)
+        if @service.smoke_tests
+          y.yield('features/smoke.feature', smoke_file)
+          y.yield('features/smoke_step_definitions.rb', smoke_step_definitions_file)
+        end
+        y.yield('VERSION', version_file)
+        y.yield('LICENSE.txt', license_file)
         code = CodeBuilder.new(@options)
-        code.source_files(prefix: @service.gem_name).each do |path, code|
+        code.source_files.each do |path, code|
           y.yield("lib/#{path}", code)
         end
       end.each(&block)
@@ -27,45 +39,50 @@ module AwsSdkCodeGenerator
     private
-    def gemspec_path
-      "#{@service.gem_name}.gemspec"
-    end
     def gemspec_file
       Views::Gemspec.new(options).render
     end
-    def features_env_path
-      'features/env.rb'
-    end
     def features_env_file
       Views::Features::Env.new(options).render
     end
-    def features_step_definitions_path
-      'features/step_definitions.rb'
+    def smoke_file
+      Views::Features::Smoke.new(options).render
     end
-    def features_step_definitions_file
-      Views::Features::StepDefinitions.new(options).render
+    def smoke_step_definitions_file
+      Views::Features::SmokeStepDefinitions.new(options).render
     end
-    def spec_helper_path
-      'spec/spec_helper.rb'
+    def features_step_definitions_file
+      Views::Features::StepDefinitions.new(options).render
     end
     def spec_helper_file
       Views::Spec::SpecHelper.new(options).render
     end
-    def version_path
-      'VERSION'
-    end
     def version_file
       Views::Version.new(options).render
     end
+    def license_file
+      File.read(File.expand_path('../../../templates/license.txt',__FILE__ ))
+    end
+    private
+    # document types are only supported for rest-json and json
+    def validate_document_support!
+      return if ['rest-json', 'json'].include?(@service.protocol)
+      # Check all shapes and raise if any are Document types
+      @service.api.fetch('shapes', {}).each do |name, shape|
+        if shape['type'] == 'structure' && shape['document']
+          raise "Shape #{name} is a document type.  Document types are only supported in json protocols."
+        end
+      end
+    end
   end
 end

data/lib/aws-sdk-code-generator/hash_formatter.rb CHANGED Viewed

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
 module AwsSdkCodeGenerator
   class HashFormatter
@@ -15,10 +17,11 @@ module AwsSdkCodeGenerator
       @wrap = options.fetch(:wrap, true)
       @inline = options.fetch(:inline, false)
       @quote_strings = options.fetch(:quote_strings, false)
+      @indent = options.fetch(:indent, '')
     end
     def format(obj)
-      result = hash(obj, i:'', inline:@inline)
+      result = hash(obj, i: @indent, inline:@inline)
       result = unwrap(result, obj.size) if !@wrap
       result = result.strip if @inline && result.lines.to_a.length == 1
       result
@@ -34,7 +37,7 @@ module AwsSdkCodeGenerator
       when Array then array(obj, i:i)
       when String then @quote_strings ? obj.inspect : obj
       when Symbol then obj.inspect
-      when Fixnum, true, false then obj.inspect
+      when Integer, true, false then obj.inspect
       else raise ArgumentError, "unsupported value `#{obj.class}'"
       end
     end