queue.rb in cloud_powers-1.1.0

- old
+ new

@@ -82,19 +82,72 @@
         def board_name(arg)
           base_name = to_snake(arg.to_s.split('/').last)
           %r{_board$} =~ base_name ? base_name : "#{base_name}_board"
         end
 
+        # Build a Smash::CloudPowers::Synapse::Queue and the getter and setter
+        # methods.  This method uses the Creatable and Resource interface for
+        # consistency throughout CloudPowers.
+        #
+        # Parameters
+        # * +:name+ +String+ - the name of the Queue will be used to create
+        #   a getter and setter.  Please see <tt>CloudPowers::Creatable</tt>
+        # * +type+ +String+|+Symbol+ - Default is
+        #   <tt>Smash::CloudPowers::Synapse::Queue::Board</tt>.  As long as the
+        #   type you request exists, you can use it but only the Classes that
+        #   use <tt>CloudPowers::Creatable</tt> and extend from
+        #   <tt>CloudPowers::Resource</tt> are supported.  Please see
+        #   <tt>CloudPowers::Creatable</tt> and <tt>CloudPowers::Resource</tt>
+        # * config +KeywordArgument+s - any config you want to pass along.
+        #
+        # Returns
+        # <tt>Smash::CloudPowers::Synapse::Queue[::?]</tt>
+        #
+        # Notes:
+        # * See <tt>create_queue</tt> to create the real object; e.g. an
+        #   <tt>AWS::SQS::Queue</tt>.  This method just creates a representation
+        #   of that object in memory.  It can be linked up to a real Object or
+        #   left as is and used later.
+        # * See <tt>CloudPowers::Creatable</tt>
+        # * See <tt>CloudPowers::Resource</tt>
         def build_queue(name:, type: :board, **config)
           build_method_name = "build_#{type}"
           if self.respond_to? build_method_name
             self.public_send build_method_name, name: name, **config
           else
             build_board(name: name, **config)
           end
         end
 
+        # Create a <tt>Smash::CloudPowers::Synapse::Queue</tt>, the getter
+        # and setter methods and the real object, either out in the wild or right
+        # here, on disk; e.g. create an <tt>Aws::SQS::Queue</tt> in AWS and the
+        # appropriately mapped <tt>Smash::CloudPowers::Synapse::Queue[::?]</tt>
+        # object, locally to use in other methods, etc.  This method uses the
+        # Creatable and Resource interface for consistency throughout CloudPowers.
+        #
+        # Parameters
+        # * +:name+ +String+ - the name of the Queue will be used to create
+        #   a getter and setter.  Please see <tt>CloudPowers::Creatable</tt>
+        # * +type+ +String+|+Symbol+ - Default is
+        #   <tt>Smash::CloudPowers::Synapse::Queue::Board</tt>.  As long as the
+        #   type you request exists, you can use it but only the Classes that
+        #   use <tt>CloudPowers::Creatable</tt> and extend from
+        #   <tt>CloudPowers::Resource</tt> are supported.  Please see
+        #   <tt>CloudPowers::Creatable</tt> and <tt>CloudPowers::Resource</tt>
+        # * config +KeywordArgument+s - any config you want to pass along.
+        #
+        # Returns
+        # <tt>Smash::CloudPowers::Synapse::Queue[::?]</tt>
+        #
+        # Notes:
+        # * See <tt>build_queue</tt> to create the real object; e.g. an
+        #   <tt>AWS::SQS::Queue</tt>.  This method just creates a representation
+        #   of that object in memory.  It can be linked up to a real Object or
+        #   left as is and used later.
+        # * See <tt>CloudPowers::Creatable</tt>
+        # * See <tt>CloudPowers::Resource</tt>
         def create_queue(name:, type: :board, **config)
           create_method_name = "build_#{type}"
           if self.respond_to? create_method_name
             self.public_send create_method_name, name: name, **config
           else
@@ -116,11 +169,11 @@
         #   queue_object = build_queue('exampleQueue')
         #   queue_object.address
         #   => https://sqs.us-west-2.amazonaws.com/81234567/exampleQueue
         def build_board(name:, client: sqs, **config)
           board_resource = Smash::CloudPowers::Synapse::Queue::Board.build(
-            name: to_camel(name), client: sqs
+            name: to_camel(name), client: client, **config
           )
 
           attr_map(board_resource.call_name => board_resource) do |attribute, resource|
             instance_attr_accessor attribute
             resource
@@ -322,9 +375,13 @@
         # Example
         #     results = queue_search('exampleQueue') # returns related URLs
         #     results.first =~ /exampleQueue/ # regex match against the URL
         def queue_search(name)
           urls = sqs.list_queues(queue_name_prefix: name).queue_urls
+          # TODO: allow a collection of blocks to be itterated through. Each one
+          # would be able to further scope down a set of previous results then
+          # pass it to the next.  When there are no scoping blocks left, build
+          # the boards and return them.  Saves a TON on memory and time
           urls.map do |url|
             build_board(name: queue_name(url), client: sqs) do |board|
               board.instance_attr_accessor :url
               board.url = url
               board