aws-sdk-resources 2.11.549

data/lib/aws-sdk-resources/documenter/data_operation_documenter.rb

@@ -0,0 +1,25 @@
+module Aws
+  module Resources
+    class Documenter
+      class DataOperationDocumenter < BaseOperationDocumenter
+
+        def return_type
+          if plural?
+            "Array<#{path_type}>"
+          else
+            path_type
+          end
+        end
+
+        def return_tag
+          tag("@return [#{return_type}]")
+        end
+
+        def plural?
+          !!@operation.path.match(/\[/)
+        end
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-resources/documenter/has_many_operation_documenter.rb

@@ -0,0 +1,69 @@
+module Aws
+  module Resources
+    class Documenter
+      class HasManyOperationDocumenter < BaseOperationDocumenter
+
+        def docstring
+          super + ' ' + <<-DOCSTRING.lstrip
+Returns a {Resources::Collection Collection} of {#{target_resource_class_name}}
+resources. No API requests are made until you call an enumerable method on the
+collection. {#{called_operation}} will be called multiple times until every
+{#{target_resource_class_name}} has been yielded.
+          DOCSTRING
+        end
+
+        def return_tag
+          tag("@return [Collection<#{target_resource_class_name}>]")
+        end
+
+        def example_tags
+          tags = super
+          tags << enumerate_example_tag
+          tags << enumerate_with_limit_example_tag
+          tags << batch_examples_tag if target_resource_batches?
+          tags
+        end
+
+        def enumerate_example_tag
+          tag(<<-EXAMPLE.strip)
+@example Enumerating {#{target_resource_class_name}} resources.
+  #{variable_name}.#{@operation_name}.each do |#{target_resource_class_name.downcase}|
+    # yields each #{target_resource_class_name.downcase}
+  end
+          EXAMPLE
+        end
+
+        def enumerate_with_limit_example_tag
+          tag(<<-EXAMPLE.strip)
+@example Enumerating {#{target_resource_class_name}} resources with a limit.
+  #{variable_name}.#{@operation_name}.limit(10).each do |#{target_resource_class_name.downcase}|
+    # yields at most 10 #{@operation_name}
+  end
+          EXAMPLE
+        end
+
+        def batch_examples_tag
+          example = []
+          example << "@example Batch operations callable on the returned collection"
+          target_resource_batch_operations.each do |name, operation|
+            if operation.respond_to?(:request)
+              example << ""
+              example << "  # calls Client##{operation.request.method_name} on each batch"
+              example << "  #{variable_name}.#{@operation_name}.#{name}"
+            end
+          end
+          tag(example.join("\n"))
+        end
+
+        def target_resource_batches?
+          target_resource_batch_operations.count > 0
+        end
+
+        def target_resource_batch_operations
+          target_resource_class.batch_operations
+        end
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-resources/documenter/has_operation_documenter.rb

@@ -0,0 +1,66 @@
+module Aws
+  module Resources
+    class Documenter
+      class HasOperationDocumenter < BaseOperationDocumenter
+
+        def return_tag
+          if plural?
+            type = "Array<#{target_resource_class_name}>"
+          else
+            type = target_resource_class_name
+          end
+          type += ',nil' if can_return_nil?
+          tag("@return [#{type}]")
+        end
+
+        def parameters
+          if argument?
+            arguments.map { |arg| [argument_name(arg), nil] }
+          else
+            []
+          end
+        end
+
+        def tags
+          tags = super
+          if argument?
+            arguments.each do |arg|
+              tag = "@param [String] #{argument_name(arg)} "
+              tag << "The {#{target_resource_class_name}##{argument_name(arg)}} "
+              tag << "identifier."
+              tags += YARD::DocstringParser.new.parse(tag).to_docstring.tags
+            end
+          end
+          tags
+        end
+
+        def plural?
+          @operation.builder.plural?
+        end
+
+        def argument?
+          @operation.arity > 0
+        end
+
+        def can_return_nil?
+          data_member
+        end
+
+        def data_member
+          builder.sources.find { |s| BuilderSources::DataMember === s }
+        end
+
+        def arguments
+          builder.sources.select do |source|
+            BuilderSources::Argument === source
+          end
+        end
+
+        def argument_name(argument)
+          argument.target.to_s
+        end
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-resources/documenter/operation_documenter.rb

@@ -0,0 +1,20 @@
+module Aws
+  module Resources
+    class Documenter
+      class OperationDocumenter < BaseOperationDocumenter
+
+        def docstring
+          @api_request.documentation
+        end
+
+        def return_tag
+          @yard_client_operation.tags.each do |tag|
+            return tag if tag.tag_name == 'return'
+          end
+          nil
+        end
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-resources/documenter/resource_operation_documenter.rb

@@ -0,0 +1,53 @@
+module Aws
+  module Resources
+    class Documenter
+      class ResourceOperationDocumenter < BaseOperationDocumenter
+
+        def initialize(*args)
+          super
+          @plural = @operation.builder.plural?
+        end
+
+        # @return [Boolean] Returns `true` if this operation returns an
+        #   array of resource objects. Returns `false` if this method returns
+        #   a single resource object.
+        attr_reader :plural
+
+        alias plural? plural
+
+        def return_tag
+          if plural?
+            tag("@return [Array<#{target_resource_class_name}>]")
+          else
+            tag("@return [#{target_resource_class_name}]")
+          end
+        end
+
+        def example_tags
+          id = target_resource_class.identifiers.last.to_s
+          idv = target_resource_class_name.downcase + '-' + id.gsub('_', '-')
+          example = []
+          example << "@example Basic usage"
+          example << "  #{resp_variable} = #{variable_name}.#{operation_name}(options)"
+          if plural?
+            example << "  #{resp_variable}.map(&:#{id})"
+            example << "  #=> [#{idv.inspect}, ...]"
+          else
+            example << "  #{resp_variable}.#{id}"
+            example << "  #=> #{idv.inspect}"
+          end
+          super + [tag(example.join("\n"))]
+        end
+
+        def resp_variable
+          if plural?
+            target_resource_class_name.downcase + 's'
+          else
+            target_resource_class_name.downcase
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-resources/documenter/waiter_operation_documenter.rb

@@ -0,0 +1,77 @@
+module Aws
+  module Resources
+    class Documenter
+      class WaiterOperationDocumenter < BaseOperationDocumenter
+
+        def docstring
+          super + ' ' + <<-DOCSTRING.lstrip
+Waits until this #{resource_class_name} is #{state}. This method
+waits by polling {Client##{api_request_name}} until successful. An error is
+raised after a configurable number of failed checks.
+
+This waiter uses the following defaults:
+
+| Configuration   | Default                |
+|-----------------|------------------------|
+| `#delay`        | #{waiter.delay}        |
+| `#max_attempts` | #{waiter.max_attempts} |
+
+You can modify defaults and register callbacks by passing a block argument.
+@yieldparam [Waiters::Waiter] waiter
+@raise [Waiters::Errors::WaiterFailed]
+@see Client#wait_until
+          DOCSTRING
+        end
+
+        def return_tag
+          tag("@return [#{resource_class_name}] #{return_message}")
+        end
+
+        def return_message
+          if @operation.path
+            "Returns a copy of this #{resource_class_name} with loaded data."
+          else
+            "Returns a copy of this #{resource_class_name} that is not loaded."
+          end
+        end
+
+        def state
+          operation_name.to_s.sub('wait_until_', '')
+        end
+
+        def waiter
+          @resource_class.client_class.waiters.waiter(@operation.waiter_name)
+        end
+
+        def api_request
+          @resource_class.client_class.api.operation(api_request_name)
+        end
+
+        def api_request_name
+          waiter.poller.operation_name
+        end
+
+        def option_tags
+          []
+        end
+
+        def example_tags
+          example = <<-EXAMPLE.strip
+@example Basic usage
+  #{variable_name}.#{operation_name}
+
+@example Modify default configuration
+  #{variable_name}.#{operation_name} do |w|
+     w.interval = 10
+     w.max_attempts = 100
+     w.before_attempt { |count| ... }
+     w.before_wait do { |count, prev_resp| ... }
+  end
+          EXAMPLE
+          [tag(example)]
+        end
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-resources/errors.rb

@@ -0,0 +1,15 @@
+module Aws
+  module Resources
+    module Errors
+
+      class UnknownOperationError < ArgumentError
+        def initialize(name)
+          super("operation `#{name}' not defined")
+        end
+      end
+
+      class DefinitionError < ArgumentError; end
+
+    end
+  end
+end

data/lib/aws-sdk-resources/operation_methods.rb

@@ -0,0 +1,83 @@
+module Aws
+  module Resources
+    module OperationMethods
+
+      # @param [Symbol] name
+      # @return [Operation] Returns the named operation.
+      # @raise [Errors::UnknownOperationError]
+      def operation(name)
+        @operations[name.to_sym] or
+          raise Errors::UnknownOperationError.new(name)
+      end
+
+      # @param [Symbol] method_name
+      # @param [Operation] operation
+      # @return [void]
+      def add_operation(method_name, operation = nil, &definition)
+        operation = definition if block_given?
+        safe_define_method(method_name) do |*args, &block|
+          operation.call(resource:self, args:args, block:block)
+        end
+        @operations[method_name.to_sym] = operation
+      end
+
+      # @return [Hash]
+      def operations(&block)
+        @operations.dup
+      end
+
+      # @return [Array<Symbol>]
+      def operation_names
+        @operations.keys.sort
+      end
+
+      # @param [Symbol] name
+      # @return [Operation] Returns the named batch operation.
+      # @raise [Errors::UnknownOperationError]
+      def batch_operation(name)
+        @batch_operations[name.to_sym] or
+          raise Errors::UnknownOperationError.new(name)
+      end
+
+      # @param [Symbol] method_name
+      # @param [Operation] operation
+      # @return [void]
+      def add_batch_operation(method_name, operation = nil, &definition)
+        operation = definition if block_given?
+        @batch_operations[method_name.to_sym] = operation
+      end
+
+      # @return [Hash]
+      def batch_operations(&block)
+        @batch_operations.dup
+      end
+
+      # @return [Array<Symbol>]
+      def batch_operation_names
+        @batch_operations.keys.sort
+      end
+
+      # @api private
+      def inherited(subclass)
+        subclass.send(:instance_variable_set, "@operations", {})
+        subclass.send(:instance_variable_set, "@batch_operations", {})
+      end
+
+      private
+
+      def safe_define_method(method_name, &block)
+        if
+          instance_methods.include?(method_name.to_sym) &&
+          ENV['AWS_SDK_SAFE_DEFINE']
+        then
+          msg = "unable to define method #{name}##{method_name}, "
+          msg << "method already exists"
+          raise Errors::DefinitionError, msg
+        else
+          define_method(method_name, &block)
+        end
+      end
+
+    end
+  end
+end

data/lib/aws-sdk-resources/operations.rb

@@ -0,0 +1,280 @@
+module Aws
+  module Resources
+    module Operations
+
+      # Base class for operations. An operation is any object that responds
+      # to `#call` receiving a hash of options including:
+      #
+      # * `:resource` - The resource object the operation is invoked against.
+      # * `:args` - An array of arguments given by the caller
+      # * `:block` - An optional block argument
+      #
+      class Base
+
+        include Options
+
+        def initialize(options = {})
+          @source = options[:source]
+        end
+
+        # @return [Source, nil]
+        attr_reader :source
+
+      end
+
+      # Makes an API request using the resource client, returning the client
+      # response.  Most operation classes extend this basic operation.
+      class Operation < Base
+
+        # @option options [required, Request] :request
+        def initialize(options = {})
+          @request = option(:request, options)
+          super
+        end
+
+        # @return [Request]
+        attr_reader :request
+
+        # @option (see Base#call)
+        # @return [Seahorse::Client::Response]
+        def call(options)
+          @request.call(options)
+        end
+
+      end
+
+      class LoadOperation < Operation
+
+        # @option options [required, Request] :request
+        # @option options [required, String<JMESPath>] :path
+        def initialize(options = {})
+          @path = option(:path, options)
+          super
+        end
+
+        # @return [String<JMESPath>]
+        attr_reader :path
+
+        # @option (see Base#call)
+        # @return [Object] Returns the value resolved to by {#path}.
+        def call(options)
+          extract(super)
+        end
+
+        private
+
+        def extract(resp)
+          JMESPath.search(@path, resp.data)
+        end
+
+      end
+
+      class ResourceOperation < Operation
+
+        # @option options [required, Request] :request
+        # @option options [required, Builder] :builder
+        def initialize(options = {})
+          @builder = option(:builder, options)
+          super
+        end
+
+        # @return [Builder]
+        attr_reader :builder
+
+        # @option (see Base#call)
+        # @return [Resource, Array<Resource>]
+        def call(options)
+          @builder.build(options.merge(response:super))
+        end
+
+      end
+
+      class HasManyOperation < ResourceOperation
+
+        # @option options [required, Request] :request
+        # @option options [required, Builder] :builder
+        # @option options [Symbol] :limit_key
+        def initialize(options)
+          @limit_key = options[:limit_key]
+          super
+        end
+
+        # @return [Builder]
+        attr_reader :builder
+
+        # @return [Symbol, nil]
+        attr_reader :limit_key
+
+        # @option (see Base#call)
+        # @return [Collection]
+        def call(options)
+          validate_args!(options)
+          Collection.new(self, options)
+        end
+
+        # @api private
+        # @return [Enumerator<Batch>]
+        def batches(options, &block)
+          if options[:limit]
+            enum_for(:limited_batches, options[:limit], options, &block)
+          else
+            enum_for(:all_batches, options, &block)
+          end
+        end
+
+        private
+
+        def validate_args!(options)
+          args = options[:args]
+          unless args.count == 0 || args.count == 1
+            msg = "wrong number of arguments (given #{args.count}, expected 0..1)"
+            raise ArgumentError, msg
+          end
+          unless args[0].nil? || Hash === args[0]
+            raise ArgumentError, "expected Hash, got #{args[0].class}"
+          end
+        end
+
+        def all_batches(options, &block)
+          resp = @request.call(options)
+          if resp.respond_to?(:each)
+            resp.each do |response|
+              yield(@builder.build(options.merge(response:response)))
+            end
+          else
+            yield(@builder.build(options.merge(response:resp)))
+          end
+        end
+
+        def limited_batches(limit, options, &block)
+          remaining = limit
+          all_batches(options) do |batch|
+            if batch.size < remaining
+              yield(batch)
+              remaining -= batch.size
+            else
+              yield(batch.first(remaining))
+              return
+            end
+          end
+        end
+
+      end
+
+      class HasOperation < Base
+
+        # @option options [required, Builder] :builder
+        def initialize(options = {})
+          @builder = option(:builder, options)
+          super
+        end
+
+        # @return [Builder]
+        attr_reader :builder
+
+        # @option (see Base#call)
+        # @return [Resource]
+        def call(options)
+          if argc(options) == arity
+            @builder.build(options)
+          else
+            msg = "wrong number of arguments (#{argc(options)} for #{arity})"
+            raise ArgumentError, msg
+          end
+        end
+
+        def arity
+          @builder.sources.count { |s| BuilderSources::Argument === s }
+        end
+
+        private
+
+        def argc(options)
+          (options[:args] || []).count
+        end
+
+      end
+
+      class WaiterOperation < Base
+
+        include Options
+
+        def initialize(options = {})
+          @waiter_name = option(:waiter_name, options)
+          @waiter_params = option(:waiter_params, options)
+          @path = options[:path]
+          super
+        end
+
+        # @return [Symbol]
+        attr_reader :waiter_name
+
+        # @return [Array<RequestParams::Base>]
+        attr_reader :waiter_params
+
+        # @return [String<JMESPathExpression>, nil]
+        attr_reader :path
+
+        # @option options [required,Resource] :resource
+        # @option options [required,Array<Mixed>] :args
+        def call(options)
+
+          resource = options[:resource]
+
+          params_hash = options[:args].first || {}
+          @waiter_params.each do |param|
+            param.apply(params_hash, options)
+          end
+
+          resp = resource.client.wait_until(@waiter_name, params_hash, &options[:block])
+
+          resource_opts = resource.identifiers.dup
+          if @path && resp.respond_to?(:data)
+            resource_opts[:data] = JMESPath.search(@path, resp.data)
+          end
+          resource_opts[:client] = resource.client
+          resource.class.new(resource_opts)
+        end
+
+      end
+
+      # @api private
+      class DeprecatedOperation
+
+        def initialize(options = {})
+          @name = options[:name]
+          @deprecated_name = options[:deprecated_name]
+          @resource_class = options[:resource_class]
+          @operation = @resource_class.batch_operation(@name)
+          @warned = false
+        end
+
+        def call(*args)
+          unless @warned
+            @warned = true
+            warn(deprecation_warning)
+          end
+          @operation.call(*args)
+        end
+
+        private
+
+        def deprecation_warning
+          "DEPRECATION WARNING: called deprecated batch method " +
+          "`##{@deprecated_name}` on a batch of `#{@resource_class.name}` " +
+          "objects; use `##{@name}` instead"
+        end
+
+        class << self
+
+          def define(options = {})
+            klass = options[:resource_class]
+            deprecated_name = options[:deprecated_name]
+            klass.add_batch_operation(deprecated_name, new(options))
+          end
+
+        end
+      end
+    end
+  end
+end