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

data/lib/aws-sdk-code-generator/crosslink.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module AwsSdkCodeGenerator
+  module Crosslink
+
+    BASEURL = 'http://docs.aws.amazon.com/'
+    EXCLUDE_UIDS = [
+      "apigateway",
+      "budgets",
+      "cloudsearch",
+      "cloudsearchdomain",
+      "discovery",
+      "elastictranscoder",
+      "es",
+      "glacier",
+      "importexport",
+      "iot",
+      "iot-data",
+      "machinelearning",
+      "rekognition",
+      "sdb",
+      "swf"
+    ]
+
+    def self.tag_string(uid, name)
+      path = "#{BASEURL}goto/WebAPI/#{uid}/#{name}"
+      "@see #{path} AWS API Documentation"
+    end
+
+    def self.taggable?(uid)
+      uid && !exclude?(uid)
+    end
+
+    private
+    def self.exclude?(uid)
+      EXCLUDE_UIDS.any? do |service|
+        uid.match(/^#{service}/)
+      end
+    end
+
+  end
+end

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

@@ -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

@@ -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

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

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

@@ -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