aws-sdk-code-generator 0.1.0.pre

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

@@ -0,0 +1,52 @@
+require 'set'
+
+module AwsSdkCodeGenerator
+  module Generators
+    class TypesModule < Dsl::Module
+
+      include Helper
+
+      # @option options [required, Hash] :api
+      def initialize(options)
+        @api = options.fetch(:api)
+        super('Types')
+        input_shapes = compute_input_shapes(@api)
+        structures.each do |shape_name, shape|
+          add(StructureTypeClass.new(
+            name: shape_name,
+            api: @api,
+            used_as_input: input_shapes.include?(shape_name)
+          ))
+        end
+      end
+
+      private
+
+      def compute_input_shapes(api)
+        inputs = Set.new
+        (api['operations'] || {}).each do |_, operation|
+          visit_inputs(operation['input'], inputs) if operation['input']
+        end
+        inputs
+      end
+
+      def visit_inputs(shape_ref, inputs)
+        return if inputs.include?(shape_ref['shape']) # recursion
+        inputs << shape_ref['shape']
+        s = shape(shape_ref)
+        case s['type']
+        when 'structure'
+          s['members'].each_pair do |_, member_ref|
+            visit_inputs(member_ref, inputs)
+          end
+        when 'list'
+          visit_inputs(s['member'], inputs)
+        when 'map'
+          visit_inputs(s['key'], inputs)
+          visit_inputs(s['value'], inputs)
+        end
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+module AwsSdkCodeGenerator
+  module Generators
+    class WaiterClass < Dsl::Class
+
+      # @option options [required, String] :waiter_name
+      # @option options [required, Hash] :waiter
+      def initialize(options)
+        waiter = options.fetch(:waiter)
+        client_method = underscore(waiter['operation'])
+        super(options.fetch(:waiter_name))
+        code <<-CODE
+# @param [Hash] options
+# @option options [required, Client] :client
+# @option options [Integer] :max_attempts (#{waiter['maxAttempts']})
+# @option options [Integer] :delay (#{waiter['delay']})
+# @option options [Proc] :before_attempt
+# @option options [Proc] :before_wait
+def initialize(options)
+  @client = options.fetch(:client)
+  @waiter = Aws::Waiters::Waiter.new({
+    max_attempts: #{waiter['maxAttempts']},
+    delay: #{waiter['delay']},
+    poller: Aws::Waiters::Poller.new(#{poller_args(waiter)}    )
+  }.merge(options))
+end
+
+# @option (see Client##{client_method})
+# @return (see Client##{client_method})
+def wait(params = {})
+  @waiter.wait(client: @client, params: params)
+end
+
+# @api private
+attr_reader :waiter
+        CODE
+      end
+
+      private
+
+      def poller_args(hash)
+        hash = hash.dup
+        hash.delete('delay')
+        hash.delete('maxAttempts')
+        hash[:operation_name] = Underscore.underscore(hash.delete('operation')).to_sym
+        hash[:acceptors] = hash.delete('acceptors').map do |acceptor|
+          if acceptor['argument']
+            acceptor['argument'] = Underscore.underscore_jmespath(acceptor['argument'])
+          end
+          acceptor
+        end
+        formatter = HashFormatter.new(
+          wrap: false,
+          inline: false,
+          quote_strings: true
+        )
+        lines = formatter.format(hash).lines
+        lines.map { |line| "    #{line}" }.join
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+module AwsSdkCodeGenerator
+  module Generators
+    class WaitersModule < Dsl::Module
+
+      include Helper
+
+      # @option options [required, Module] :parent
+      # @option options [required, Hash, nil] :waiters
+      def initialize(options)
+        waiters = options.fetch(:waiters)
+        super('Waiters', parent: options.fetch(:parent))
+        require_statement('aws-sdk-core/waiters')
+        waiters['waiters'].each do |waiter_name, waiter|
+          add(WaiterClass.new(waiter_name: waiter_name, waiter: waiter))
+        end
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,122 @@
+module AwsSdkCodeGenerator
+  class HashFormatter
+
+    # @option options [Boolean] :wrap (true) When `true`, the formatted hash will
+    #   be wrapped with curly braces.
+    #
+    # @option options [Boolean] :inline (false) When `true` the formatted hash will
+    #   contain no newlines.
+    #
+    # @option options [Boolean] :quote_strings (false) By default, all hash string values
+    #   must contain their own quotes. If you pass `true`, then all hash string
+    #   values will be inspected via `#inspect` which will auto-quote them.
+    #
+    def initialize(options = {})
+      @wrap = options.fetch(:wrap, true)
+      @inline = options.fetch(:inline, false)
+      @quote_strings = options.fetch(:quote_strings, false)
+    end
+
+    def format(obj)
+      result = hash(obj, i:'', inline:@inline)
+      result = unwrap(result, obj.size) if !@wrap
+      result = result.strip if @inline && result.lines.to_a.length == 1
+      result
+    end
+
+    private
+
+    def value(obj, options)
+      i = options.fetch(:i)
+      inline = options.fetch(:inline)
+      case obj
+      when Hash then hash(obj, i:i, inline:inline)
+      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
+      else raise ArgumentError, "unsupported value `#{obj.class}'"
+      end
+    end
+
+    def hash(hash, options)
+      i = options.fetch(:i)
+      inline = options.fetch(:inline)
+      if hash.empty?
+        '{}'
+      elsif inline_hash?(hash, inline)
+        inline_hash(hash)
+      else
+        multiline_hash(hash, i:i)
+      end
+    end
+
+    def inline_hash(hash)
+      "{ #{hash_entry(hash.keys[0], hash.values[0], i:'')} }"
+    end
+
+    def multiline_hash(hash, options)
+      i = options.fetch(:i)
+      str = "{\n"
+      hash.each.with_index do |(key, value), n|
+        str += "#{i}  #{hash_entry(key, value, i:i)}"
+        str += "," unless n == hash.keys.length - 1
+        str += "\n"
+      end
+      str + "#{i}}"
+    end
+
+    def hash_entry(key, value, options)
+      i = options.fetch(:i)
+      value = value(value, i: i + '  ', inline:false)
+      if Symbol === key
+        "#{key}: #{value}"
+      else
+        "#{key.inspect} => #{value}"
+      end
+    end
+
+    def array(array, options)
+      i = options.fetch(:i)
+      if array.empty?
+        '[]'
+      elsif inline_array?(array)
+        "[#{value(array[0], i:i, inline:true)}]"
+      else
+        format_multiline_array(array, i:i)
+      end
+    end
+
+    def format_multiline_array(array, options)
+      i = options.fetch(:i)
+      str = "[\n"
+      array.each.with_index do |value, n|
+        str += "#{i}  #{value(value, i:i + '  ', inline:true)}"
+        str += "," unless n == array.length - 1
+        str += "\n"
+      end
+      str + "#{i}]"
+    end
+
+    def inline_hash?(hash, inline)
+      hash.length == 1 && String === hash.values[0] && inline
+    end
+
+    def inline_array?(array)
+      array.length == 1# && String === array[0]
+    end
+
+    def unwrap(str, size)
+      if @inline || size > 1
+        str[1..-2]
+      else
+        lines = str.lines.to_a
+        lines.shift
+        lines.pop
+        lines = lines.map { |line| line[2..-1] }
+        lines.join.rstrip
+      end
+    end
+
+  end
+end

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

@@ -0,0 +1,215 @@
+require 'kramdown'
+require 'set'
+
+# disable inline attribute lists
+class Kramdown::Converter::Kramdown
+  def ial_for_element(*args)
+    nil
+  end
+end
+
+module AwsSdkCodeGenerator
+  module Helper
+
+    def identifier_type(identifier)
+      case identifier['type']
+      when nil, 'string' then 'String'
+      when 'integer' then 'Integer'
+      else
+        msg = "unsupported identifier type `#{identifier['type']}'"
+        raise ArgumentError, msg
+      end
+    end
+
+    # @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
+    module_function :markdown_table
+
+    def underscore(str)
+      str.split('.').map do |part|
+        Underscore.underscore(part)
+      end.join('.')
+    end
+
+    def structures
+      Enumerator.new do |y|
+        (@api['shapes'] || {}).each do |shape_name, shape|
+          if shape['type'] == 'structure' && !shape['error'] && !shape['exception']
+            y.yield(shape_name, shape)
+          end
+        end
+      end
+    end
+
+    # @option options [Boolean] :nested (false)
+    def ruby_input_type(shape_ref, options = {})
+      nested = options.fetch(:nested, false)
+      shape = @api['shapes'][shape_ref['shape']]
+      case shape['type']
+      when 'byte' then 'Integer<byte>'
+      when 'blob' then 'String, IO'
+      when 'boolean' then 'Boolean'
+      when 'character' then 'String<character>'
+      when 'double' then 'Float'
+      when 'float' then 'Float'
+      when 'integer' then 'Integer'
+      when 'list'
+        if nested
+          "Array"
+        else
+          "Array<#{ruby_input_type(shape['member'], nested:true)}>"
+        end
+      when 'long' then 'Integer'
+      when 'map'
+        if nested
+          "Hash"
+        else
+          "Hash<String,#{ruby_input_type(shape['value'], nested:true)}>"
+        end
+      when 'string' then 'String'
+      when 'structure' then "Types::#{shape_ref['shape']}"
+      when 'timestamp' then 'Time,DateTime,Date,Integer,String'
+      else
+        raise "unhandled type #{shape.type}.inspect"
+      end
+    end
+
+    def ruby_type(shape_ref)
+      shape = @api['shapes'][shape_ref['shape']]
+      case shape['type']
+      when 'blob' then streaming?(shape_ref, shape) ? 'IO' : 'String'
+      when 'boolean' then 'Boolean'
+      when 'byte' then 'Integer<byte>'
+      when 'character' then 'String<character>'
+      when 'double' then 'Float'
+      when 'float' then 'Float'
+      when 'integer' then 'Integer'
+      when 'list' then "Array<#{ruby_type(shape['member'])}>"
+      when 'long' then 'Integer'
+      when 'map' then "Hash<String,#{ruby_type(shape['value'])}>"
+      when 'string' then 'String'
+      when 'structure' then "Types::#{shape_ref['shape']}"
+      when 'timestamp' then 'Time'
+      else
+        raise "unhandled type #{shape['type'].inspect}"
+      end
+    end
+
+    def streaming?(ref, shape)
+      ref['streaming'] || shape['streaming']
+    end
+
+    # @option options [Integer] :line_width (70)
+    def documentation(ref_or_shape, options = {})
+      line_width = options.fetch(:line_width, 70)
+      shape = ref_or_shape.key?('type') ? ref_or_shape : shape(ref_or_shape)
+      docstring = ref_or_shape['documentation'] || shape['documentation'] || ''
+
+      # append boilerplate idempotency docs
+      if ref_or_shape['idempotencyToken']
+        docstring = "#{docstring}<p>**A suitable default value is "
+        docstring += "auto-generated.** You should normally "
+        docstring += "not need to pass this option.</p>"
+        docstring = docstring.strip
+      end
+
+      docstring == '' ? docstring : markdown(docstring, line_width:line_width)
+    end
+
+    def member_shape(shape_name, member_name)
+      shape = @api['shapes'][shape_name]
+      member_ref = shape['members'][member_name]
+      shape(member_ref)
+    end
+
+    def shape(ref)
+      if ref.nil?
+        nil
+      else
+        shape = @api['shapes'][ref['shape']]
+        raise ArgumentError, "no such shape `#{ref['shape']}'" unless shape
+        shape
+      end
+    end
+
+    # @option options [Integer] :line_width (70)
+    def 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 }
+
+        # <important> tag doesn't render well
+        html = html.gsub(/<important>(.+?)<\/important>/){ "<p>#{$1}</p>" }
+
+        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
+
+    def deep_copy(obj)
+      case obj
+      when nil then nil
+      when true then true
+      when false then false
+      when Hash then obj.inject({}) { |h,(k,v)| h[deep_copy(k)] = deep_copy(v); h }
+      when Array then obj.map { |v| deep_copy(v) }
+      else
+        if obj.respond_to?(:dup)
+          obj.dup
+        elsif obj.respond_to?(:clone)
+          obj.clone
+        else
+          obj
+        end
+      end
+    end
+
+  end
+end