aws-sdk-core 2.0.48 → 2.1.0

data/lib/aws-sdk-core/api/docs/param_formatter.rb

@@ -0,0 +1,163 @@
+module Aws
+  module Api
+    module Docs
+      class ParamFormatter
+
+        include Utils
+        include Seahorse::Model::Shapes
+
+        def initialize(shape_ref)
+          @shape_ref = shape_ref
+          @recursive_shapes = compute_recursive_shapes(@shape_ref)
+        end
+
+        def format
+          if @shape_ref && @shape_ref.shape.member_names.count > 0
+            ref_value(@shape_ref, '', [])
+          else
+            ''
+          end
+        end
+
+        private
+
+        def ref_value(ref, i, visited)
+          if visited.include?(ref.shape)
+            return "{\n#{i}  # recursive #{ref.shape.name}\n#{i}}"
+          else
+            visited  = visited + [ref.shape]
+          end
+          case ref.shape
+          when StructureShape
+            if ref.shape.name == 'AttributeValue'
+              '"value"'
+            else
+              struct(ref, i, visited)
+            end
+          when BlobShape
+            if ref[:response_target]
+              '"/path/to/file"'
+            elsif ref[:streaming]
+              'source_file'
+            else
+              '"data"'
+            end
+          when ListShape then list(ref, i, visited)
+          when MapShape then map(ref, i, visited)
+          when BooleanShape then "true"
+          when IntegerShape then '1'
+          when FloatShape then '1.0'
+          when StringShape then string(ref)
+          when TimestampShape then 'Time.now'
+          else raise "unsupported shape #{ref.shape.class.name}"
+          end
+        end
+
+        def struct(ref, i, visited)
+          lines = ['{']
+          ref.shape.members.each do |member_name, member_ref|
+            lines << struct_member(member_name, member_ref, i, visited)
+          end
+          lines << "#{i}}"
+          lines.join("\n")
+        end
+
+        def struct_member(member_name, member_ref, i, visited)
+          entry = "#{i}  #{member_name}: #{ref_value(member_ref, i + '  ', visited)},"
+          apply_comments(member_ref, entry)
+        end
+
+        def list(ref, i, visited)
+          if complex?(ref.shape.member)
+            complex_list(ref.shape.member, i, visited)
+          else
+            scalar_list(ref.shape.member, i, visited)
+          end
+        end
+
+        def scalar_list(ref, i, visited)
+          "[#{ref_value(ref, i, visited)}]"
+        end
+
+        def complex_list(ref, i, visited)
+          "[\n#{i}  #{ref_value(ref, i + '  ', visited)},\n#{i}]"
+        end
+
+        def map(ref, i, visited)
+          key = string(ref.shape.key)
+          value = ref_value(ref.shape.value, i + '  ', visited)
+          "{\n#{i}  #{key} => #{value},#{comments(ref.shape.value)}\n#{i}}"
+        end
+
+        def string(ref)
+          if ref.shape.enum
+            ref.shape.enum.first.inspect
+          elsif ref.shape.name
+            ref.shape.name.inspect
+          else
+            '"string"'
+          end
+        end
+
+        def apply_comments(ref, text)
+          lines = text.lines.to_a
+          if lines[0].match(/\n$/)
+            lines[0] = lines[0].sub(/\n$/, comments(ref) + "\n")
+          else
+            lines[0] += comments(ref)
+          end
+          lines.join
+        end
+
+        def comments(ref)
+          comments = []
+          if ref[:response_target]
+            comments << 'where to write response data, file path, or IO object'
+          end
+          if ref[:streaming]
+            comments << 'file/IO object, or string data'
+          end
+          if ref.required
+            comments << 'required'
+          end
+          if enum = enum_values(ref)
+            comments << "accepts #{enum.to_a.join(', ')}"
+          end
+          if ddb_av?(ref)
+            comments << 'value <Hash,Array,String,Numeric,Boolean,IO,Set,nil>'
+          end
+          comments == [] ? '' : " # #{comments.join(', ')}"
+        end
+
+        def recursive?(ref)
+          @recursive_shapes.include?(ref.shape)
+        end
+
+        def enum_values(ref)
+          case ref.shape
+          when ListShape then enum_values(ref.shape.member)
+          when StringShape then ref.shape.enum
+          else nil
+          end
+        end
+
+        def complex?(ref)
+          if StructureShape === ref.shape
+            !ddb_av?(ref)
+          else
+            ListShape === ref.shape || MapShape === ref.shape
+          end
+        end
+
+        def ddb_av?(ref)
+          case ref.shape
+          when ListShape then ddb_av?(ref.shape.member)
+          when StructureShape then ref.shape.name == 'AttributeValue'
+          else false
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-core/api/docs/request_syntax_example.rb

@@ -0,0 +1,22 @@
+module Aws
+  module Api
+    module Docs
+      class RequestSyntaxExample
+
+        include Utils
+        include Seahorse::Model::Shapes
+
+        def initialize(method_name, operation)
+          @method_name = method_name
+          @operation = operation
+        end
+
+        def to_str
+          params = ParamFormatter.new(operation_input_ref(@operation))
+          "resp = client.#{@method_name}(#{params.format})"
+        end
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-core/api/docs/response_structure_example.rb

@@ -0,0 +1,91 @@
+module Aws
+  module Api
+    module Docs
+      class ResponseStructureExample
+
+        include Utils
+        include Seahorse::Model::Shapes
+
+        def initialize(method_name, operation)
+          @method_name = method_name
+          @operation = operation
+          @recursive_shapes = compute_recursive_shapes(@operation.output)
+        end
+
+        def to_str
+          if @operation.output
+            lines = entry(@operation.output, "resp", [])
+            lines.empty? ? nil : lines.join("\n")
+          else
+            nil
+          end
+        end
+
+        private
+
+        def structure(ref, context, visited)
+          lines = []
+          ref.shape.members.each do |member_name, member_ref|
+            lines += entry(member_ref, "#{context}.#{member_name}", visited)
+          end
+          lines
+        end
+
+        def list(ref, context, visited)
+          lines = []
+          lines << "#{context} #=> Array"
+          lines += entry(ref.shape.member, "#{context}[0]", visited)
+          lines
+        end
+
+        def map(ref, context, visited)
+          lines = []
+          lines << "#{context} #=> Hash"
+          lines += entry(ref.shape.value, "#{context}[#{map_key(ref)}]", visited)
+          lines
+        end
+
+        def map_key(ref)
+          (ref.shape.key.shape.name || 'string').inspect
+        end
+
+        def entry(ref, context, visited)
+          if ref.shape.name == 'AttributeValue'
+            return ["#{context} #=> <Hash,Array,String,Numeric,Boolean,IO,Set,nil>"]
+          elsif visited.include?(ref.shape)
+            return ["#{context} #=> Types::#{ref.shape.name}"]
+          else
+            visited  = visited + [ref.shape]
+          end
+          case ref.shape
+          when StructureShape then structure(ref, context, visited)
+          when ListShape then list(ref, context, visited)
+          when MapShape then map(ref, context, visited)
+          else ["#{context} #=> #{value(ref)}"]
+          end
+        end
+
+        def value(ref)
+          case ref.shape
+          when StringShape then string(ref)
+          when IntegerShape then 'Integer'
+          when FloatShape then 'Float'
+          when BooleanShape then 'true/false'
+          when BlobShape then 'IO'
+          when TimestampShape then 'Time'
+          else raise "unhandled shape type #{ref.shape.class.name}"
+          end
+        end
+
+        def string(ref)
+          if ref.shape.enum
+            "String, one of #{ref.shape.enum.map(&:inspect).join(', ')}"
+          else
+            'String'
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-core/api/docs/utils.rb

@@ -0,0 +1,133 @@
+require 'set'
+
+module Aws
+  module Api
+    module Docs
+      module Utils
+
+        include Seahorse::Model
+        include Seahorse::Model::Shapes
+
+        def tag(string)
+          YARD::DocstringParser.new.parse(string).to_docstring.tags.first
+        end
+
+        def summary(string)
+          if string
+            YARD::DocstringParser.new.parse(string).to_docstring.summary
+          else
+            nil
+          end
+        end
+
+        def operation_input_ref(operation, options = {})
+          struct = StructureShape.new
+
+          # add the response target input member if the operation is streaming
+          if
+            operation.output &&
+            operation.output[:payload] &&
+            operation.output[:payload_member][:streaming]
+          then
+            target = ShapeRef.new(shape: BlobShape.new)
+            target[:response_target] = true
+            target.documentation = "Specifies where to stream response data. You can provide the path where a file will be created on disk, or you can provide an IO object. If omitted, the response data will be loaded into memory and written to a StringIO object."
+            struct.add_member(:response_target, target)
+          end
+
+          # copy existing input members
+          skip = options[:without] || Set.new
+          if operation.input
+            operation.input.shape.members.each do |member_name, member_ref|
+              unless skip.include?(member_name.to_s)
+                struct.add_member(member_name, member_ref)
+              end
+            end
+          end
+
+          ShapeRef.new(shape: struct)
+        end
+
+        # Given a shape reference, this function returns a Set of all
+        # of the recursive shapes found in tree.
+        def compute_recursive_shapes(ref, stack = [], recursive = Set.new)
+          if ref && !stack.include?(ref.shape)
+            stack.push(ref.shape)
+            case ref.shape
+            when StructureShape
+              ref.shape.members.each do |_, member_ref|
+                compute_recursive_shapes(member_ref, stack, recursive)
+              end
+            when ListShape
+              compute_recursive_shapes(ref.shape.member, stack, recursive)
+            when MapShape
+              compute_recursive_shapes(ref.shape.value, stack, recursive)
+            end
+            stack.pop
+          elsif ref
+            recursive << ref.shape
+          end
+          recursive
+        end
+
+        # Given a shape ref, returns the type accepted when given as input.
+        def input_type(ref, link = false)
+          if BlobShape === ref.shape
+            'IO,String'
+          else
+            output_type(ref, link)
+          end
+        end
+
+        # Given a shape ref, returns the type returned in output.
+        def output_type(ref, link = false)
+          case ref.shape
+          when StructureShape
+            type = "Types::" + ref.shape.name
+            link ? "{#{type}}" : type
+          when ListShape
+            "Array<#{output_type(ref.shape.member, link)}>"
+          when MapShape
+            "Hash<String,#{output_type(ref.shape.value, link)}>"
+          when BlobShape
+            ref[:streaming] ? 'IO,File' : 'String'
+          when BooleanShape then 'Boolean'
+          when FloatShape then 'Float'
+          when IntegerShape then 'Integer'
+          when StringShape then 'String'
+          when TimestampShape then 'Time'
+          else raise "unsupported shape #{ref.shape.class.name}"
+          end
+        end
+
+        # Documents a structure member as a attribute method
+        def document_struct_member(yard_class, member_name, ref, read_write = true)
+          m = YARD::CodeObjects::MethodObject.new(yard_class, member_name)
+          m.scope = :instance
+          m.docstring = struct_member_docstring(ref.documentation, ref)
+          returns = "@return [#{output_type(ref)}] #{summary(ref.documentation)}"
+          m.add_tag(tag(returns))
+          yard_class.instance_attributes[member_name] = read_write ?
+            { :read => m, :write => m } :
+            { :read => m }
+        end
+
+        def struct_member_docstring(docs, ref)
+          if
+            Seahorse::Model::Shapes::StringShape === ref.shape &&
+            ref.shape.enum
+          then
+            docs = "#{docs}<p>Possible values:</p><ul>"
+            docs += ref.shape.enum.map { |v| "<li><tt>#{v}</tt></li>" }.join
+            docs += "</ul>"
+            docs
+          else
+            docs
+          end
+        end
+
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-core/api/shape_map.rb

@@ -0,0 +1,140 @@
+module Aws
+  module Api
+    class ShapeMap
+
+      include Seahorse::Model::Shapes
+
+      EMPTY_REF = begin
+        shape = StructureShape.new
+        shape[:struct_class] = Aws::EmptyStructure
+        ShapeRef.new(shape: shape)
+      end
+
+      SHAPE_CLASSES = {
+        'blob' => BlobShape,
+        'byte' => StringShape,
+        'boolean' => BooleanShape,
+        'character' => StringShape,
+        'double' => FloatShape,
+        'float' => FloatShape,
+        'integer' => IntegerShape,
+        'list' => ListShape,
+        'long' => IntegerShape,
+        'map' => MapShape,
+        'string' => StringShape,
+        'structure' => StructureShape,
+        'timestamp' => TimestampShape,
+      }
+
+      # @param [Hash] shape_definitions
+      # @option options [DocstringProvider] :docs (NullDocstringProvider)
+      def initialize(shape_definitions, options = {})
+        @shapes = {}
+        @docs = options[:docs] || Docs::NullDocstringProvider.new
+        build_shapes(shape_definitions)
+      end
+
+      def [](shape_name)
+        if shape = @shapes[shape_name]
+          shape
+        else
+          raise ArgumentError, "unknown shape #{shape_name.inspect}"
+        end
+      end
+
+      def each_structure
+        @shapes.each do |_, shape|
+          if StructureShape === shape && !shape[:error] && !shape[:exception]
+            yield(shape)
+          end
+        end
+      end
+
+      def shape_ref(definition, options = {})
+        if definition
+
+          meta = definition.dup
+
+          shape = self[meta.delete('shape')]
+          location = meta.delete('location')
+          location_name = meta.delete('locationName')
+          location_name ||= options[:member_name] unless location == 'headers'
+          documentation = @docs.shape_ref_docs(shape.name, options[:target])
+
+          ShapeRef.new(
+            shape: shape,
+            location: location,
+            location_name: location_name,
+            required: !!options[:required],
+            deprecated: !!(meta.delete('deprecated') || shape[:deprecated]),
+            documentation: documentation,
+            metadata: meta)
+        else
+          EMPTY_REF
+        end
+      end
+
+      private
+
+      def build_shapes(definitions)
+        definitions.each do |name, definition|
+          shape = SHAPE_CLASSES[definition['type']].new
+          shape.name = name
+          @shapes[name] = shape
+        end
+        definitions.each do |name, definition|
+          traits = definition.dup
+          shape = @shapes[name]
+          apply_shape_refs(shape, traits)
+          apply_shape_traits(shape, traits)
+        end
+      end
+
+      def apply_shape_refs(shape, traits)
+        case shape
+        when StructureShape
+          required = Set.new(traits.delete('required') || [])
+          (traits.delete('members') || {}).each do |member_name, ref|
+            name = underscore(member_name)
+            shape.add_member(name, shape_ref(ref,
+              member_name: member_name,
+              required: required.include?(member_name),
+              target: "#{shape.name}$#{member_name}",
+            ))
+          end
+          shape[:struct_class] = Structure.new(*shape.member_names)
+        when ListShape
+          shape.member = shape_ref(
+            traits.delete('member'),
+            target: "#{shape.name}$member")
+        when MapShape
+          shape.key = shape_ref(
+            traits.delete('key'),
+            target: "#{shape.name}$key")
+          shape.value = shape_ref(
+            traits.delete('value'),
+            target: "#{shape.name}$value")
+        end
+      end
+
+      def apply_shape_traits(shape, traits)
+        shape.enum = Set.new(traits.delete('enum')) if traits.key?('enum')
+        shape.min = traits.delete('min') if traits.key?('min')
+        shape.max = traits.delete('max') if traits.key?('max')
+        shape.documentation = @docs.shape_docs(shape.name)
+        if payload = traits.delete('payload')
+          shape[:payload] = underscore(payload)
+          shape[:payload_member] = shape.member(shape[:payload])
+        end
+        traits.each do |key, value|
+          shape[key] = value
+        end
+      end
+
+      def underscore(str)
+        Seahorse::Util.underscore(str).to_sym
+      end
+
+    end
+  end
+end