aws-sdk 1.8.5 → 1.9.0

data/lib/aws/s3/acl_options.rb

@@ -23,7 +23,7 @@ module AWS
 
       protected
 
-      # @param [Symbol,String,Hash,AccessControlList] acl Accepts an ACL 
+      # @param [Symbol,String,Hash,AccessControlList] acl Accepts an ACL
       #   description in one of the following formats:
       #
       #   ==== Canned ACL
@@ -31,77 +31,75 @@ module AWS
       #   S3 supports a number of canned ACLs for buckets and
       #   objects.  These include:
       #
-      #   * +:private+
-      #   * +:public_read+
-      #   * +:public_read_write+
-      #   * +:authenticated_read+
-      #   * +:bucket_owner_read+ (object-only)
-      #   * +:bucket_owner_full_control+ (object-only)
-      #   * +:log_delivery_write+ (bucket-only)
+      #   * `:private`
+      #   * `:public_read`
+      #   * `:public_read_write`
+      #   * `:authenticated_read`
+      #   * `:bucket_owner_read` (object-only)
+      #   * `:bucket_owner_full_control` (object-only)
+      #   * `:log_delivery_write` (bucket-only)
       #
       #   Here is an example of providing a canned ACL to a bucket:
-      # 
-      #     s3.buckets['bucket-name'].acl = :public_read
+      #
+      #       s3.buckets['bucket-name'].acl = :public_read
       #
       #   ==== ACL Grant Hash
       #
       #   You can provide a hash of grants.  The hash is composed of grants (keys)
       #   and grantees (values).  Accepted grant keys are:
       #
-      #   * +:grant_read+
-      #   * +:grant_write+
-      #   * +:grant_read_acp+
-      #   * +:grant_write_acp+
-      #   * +:grant_full_control+
+      #   * `:grant_read`
+      #   * `:grant_write`
+      #   * `:grant_read_acp`
+      #   * `:grant_write_acp`
+      #   * `:grant_full_control`
       #
-      #   Grantee strings (values) should be formatted like some of the 
+      #   Grantee strings (values) should be formatted like some of the
       #   following examples:
       #
-      #     id="8a6925ce4adf588a4532142d3f74dd8c71fa124b1ddee97f21c32aa379004fef"
-      #     uri="http://acs.amazonaws.com/groups/global/AllUsers"
-      #     emailAddress="xyz@amazon.com"
+      #       id="8a6925ce4adf588a4532142d3f74dd8c71fa124b1ddee97f21c32aa379004fef"
+      #       uri="http://acs.amazonaws.com/groups/global/AllUsers"
+      #       emailAddress="xyz@amazon.com"
       #
       #   You can provide a comma delimited list of multiple grantees in a single
       #   string.  Please note the use of quotes inside the grantee string.
       #   Here is a simple example:
       #
-      #     {
-      #       :grant_full_control => "emailAddress=\"foo@bar.com\", id=\"abc..mno\""
-      #     }
+      #       { :grant_full_control => "emailAddress=\"foo@bar.com\", id=\"abc..mno\"" }
       #
       #   See the S3 API documentation for more information on formatting
       #   grants.
       #
       #   ==== AcessControlList Object
       #
-      #   You can build an ACL using the {AccessControlList} class and 
+      #   You can build an ACL using the {AccessControlList} class and
       #   pass this object.
       #
-      #     acl = AWS::S3::AccessControlList.new
-      #     acl.grant(:full_control).to(:canonical_user_id => "8a6...fef")
-      #     acl #=> this is acceptible
+      #       acl = AWS::S3::AccessControlList.new
+      #       acl.grant(:full_control).to(:canonical_user_id => "8a6...fef")
+      #       acl #=> this is acceptible
       #
       #   ==== ACL XML String
       #
       #   Lastly you can build your own ACL XML document and pass it as a string.
       #
-      #     <<-XML
-      #       <AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
-      #         <Owner>
-      #           <ID>8a6...fef</ID>
-      #           <DisplayName>owner-display-name</DisplayName>
-      #         </Owner>
-      #         <AccessControlList>
-      #           <Grant>
-      #             <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Canonical User">
-      #               <ID>8a6...fef</ID>
-      #               <DisplayName>owner-display-name</DisplayName>
-      #             </Grantee>
-      #             <Permission>FULL_CONTROL</Permission>
-      #           </Grant>
-      #         </AccessControlList>
-      #       </AccessControlPolicy> 
-      #     XML
+      #       <<-XML
+      #         <AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
+      #           <Owner>
+      #             <ID>8a6...fef</ID>
+      #             <DisplayName>owner-display-name</DisplayName>
+      #           </Owner>
+      #           <AccessControlList>
+      #             <Grant>
+      #               <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Canonical User">
+      #                 <ID>8a6...fef</ID>
+      #                 <DisplayName>owner-display-name</DisplayName>
+      #               </Grantee>
+      #               <Permission>FULL_CONTROL</Permission>
+      #             </Grant>
+      #           </AccessControlList>
+      #         </AccessControlPolicy>
+      #       XML
       #
       # @return [Hash] Returns a hash of options suitable for
       #   passing to {Client#put_bucket_acl} and {Client#put_object_acl}
@@ -134,7 +132,7 @@ module AWS
       end
 
       # @param [Hash] acl_hash
-      # @return [Boolean] Retursn +true+ if this hash is a hash of grants.
+      # @return [Boolean] Retursn `true` if this hash is a hash of grants.
       def grant_hash? acl_hash
         grant_keys = [
           :grant_read,
@@ -147,7 +145,7 @@ module AWS
       end
 
       # @param [String] acl_string
-      # @return [Boolean] Returns +true+ if this string is an xml document.
+      # @return [Boolean] Returns `true` if this string is an xml document.
       def xml? acl_string
         begin
           REXML::Document.new(acl_string).has_elements?
@@ -179,14 +177,16 @@ module AWS
           end
 
           # A granee hash looks like:
-          #   { :id => 'abc...fec' }
-          #   { :uri => 'http://abc.com/foo' }
-          #   { :email_address => 'xyz@amazon.com }
+          #
+          #     { :id => 'abc...fec' }
+          #     { :uri => 'http://abc.com/foo' }
+          #     { :email_address => 'xyz@amazon.com }
           #
           # It needs to look like
-          #   'id="abc...fec"'
-          #   'uri="http://abc.com/foo"'
-          #   'emailAddress="xyz@amazon.com"'
+          #
+          #     'id="abc...fec"'
+          #     'uri="http://abc.com/foo"'
+          #     'emailAddress="xyz@amazon.com"'
           type, token = grantee.to_a.flatten
           type = type.to_s.split('_').map{|part| ucfirst(part) }.join
           "#{type[0,1].downcase}#{type[1..-1]}=\"#{token}\""

data/lib/aws/s3/bucket.rb

@@ -16,63 +16,63 @@ module AWS
 
     # Represents a bucket in S3.
     #
-    # = Creating Buckets
+    # # Creating Buckets
     #
     # You create a bucket by name.  Bucket names must be globally unique
     # and must be DNS compatible.
     #
-    #   s3 = AWS::S3.new
-    #   bucket = s3.buckets.create('dns-compat-bucket-name')
+    #     s3 = AWS::S3.new
+    #     bucket = s3.buckets.create('dns-compat-bucket-name')
     #
-    # = Getting a Bucket
+    # # Getting a Bucket
     #
     # You can create a reference to a bucket, given its name.
     #
-    #   bucket = s3.buckets['bucket-name'] # makes no request
-    #   bucket.exists? #=> returns true/false
+    #     bucket = s3.buckets['bucket-name'] # makes no request
+    #     bucket.exists? #=> returns true/false
     #
-    # = Enumerating Buckets
+    # # Enumerating Buckets
     #
     # The {BucketCollection} class is enumerable.
     #
-    #   s3.buckets.each do |bucket|
-    #     puts bucket.name
-    #   end
+    #     s3.buckets.each do |bucket|
+    #       puts bucket.name
+    #     end
     #
-    # = Deleting a Bucket
+    # # Deleting a Bucket
     #
     # You can delete an empty bucket you own.
     #
-    #   bucket = s3.buckets.create('my-temp-bucket')
-    #   bucket.objects['abc'].write('xyz')
+    #     bucket = s3.buckets.create('my-temp-bucket')
+    #     bucket.objects['abc'].write('xyz')
     #
-    #   bucket.clear! # deletes all object versions in batches
-    #   bucket.delete
+    #     bucket.clear! # deletes all object versions in batches
+    #     bucket.delete
     #
     # You can alternatively call {#delete!} which will clear
     # the bucket for your first.
     #
-    #   bucket.delete!
+    #     bucket.delete!
     #
-    # = Objects
+    # # Objects
     #
     # Given a bucket you can access its objects, either by key or by
     # enumeration.
     #
-    #   bucket.objects['key'] #=> makes no request, returns an S3Object
+    #     bucket.objects['key'] #=> makes no request, returns an S3Object
     #
-    #   bucket.objects.each do |obj|
-    #     puts obj.key
-    #   end
+    #     bucket.objects.each do |obj|
+    #       puts obj.key
+    #     end
     #
     # See {ObjectCollection} and {S3Object} for more information on working
     # with objects.
     #
-    # = Website Configuration
+    # # Website Configuration
     #
     # It is easy to enable website hosting for a bucket.
     #
-    #   bucket.configure_website
+    #     bucket.configure_website
     #
     # You can specify the index and error documents by passing a block.
     # If your bucket is already configured as a website, the current
@@ -80,136 +80,136 @@ module AWS
     # configured as a website, a new configuration will be yielded
     # with default values.
     #
-    #   bucket.configure_website do |cfg|
-    #     cfg.index_document_suffix = 'index.html'
-    #     cfg.error_document_key = 'error.html'
-    #   end
+    #     bucket.configure_website do |cfg|
+    #       cfg.index_document_suffix = 'index.html'
+    #       cfg.error_document_key = 'error.html'
+    #     end
     #
     # You can disable website hosting two ways:
     #
-    #   bucket.remove_website_configuration
-    #   bucket.website_configuration = nil
+    #     bucket.remove_website_configuration
+    #     bucket.website_configuration = nil
     #
     # You can use {#website_configuration=} to copy a website configuration
     # from one bucket to another.
     #
-    #   bucket.website_configuration = other_bucket.website_configuration
+    #     bucket.website_configuration = other_bucket.website_configuration
     #
-    # = Bucket Policies and ACLs
+    # # Bucket Policies and ACLs
     #
     # You can control access to your bucket and its contents a number
     # of ways.  You can specify a bucket ACL (access control list)
     # or a bucket policy.
     #
-    # == ACLs
+    # ## ACLs
     #
     # ACLs control access to your bucket and its contents via a list of
     # grants and grantees.
     #
-    # === Canned ACLs
+    # ### Canned ACLs
     #
     # The simplest way to specify an ACL is to use one of Amazon's "canned"
     # ACLs.  Amazon accepts the following canned ACLs:
     #
-    # * +:private+
-    # * +:public_read+
-    # * +:public_read_write+
-    # * +:authenticated_read+
-    # * +:bucket_owner_read+
-    # * +:bucket_owner_full_control+
+    # * `:private`
+    # * `:public_read`
+    # * `:public_read_write`
+    # * `:authenticated_read`
+    # * `:bucket_owner_read`
+    # * `:bucket_owner_full_control`
     #
     # You can specify a the ACL at bucket creation or later update a bucket.
     #
-    #   # at create time, defaults to :private when not specified
-    #   bucket = s3.buckets.create('name', :acl => :public_read)
+    #     # at create time, defaults to :private when not specified
+    #     bucket = s3.buckets.create('name', :acl => :public_read)
     #
-    #   # replacing an existing bucket ACL
-    #   bucket.acl = :private
+    #     # replacing an existing bucket ACL
+    #     bucket.acl = :private
     #
-    # === Grants
+    # ### Grants
     #
     # Alternatively you can specify a hash of grants.  Each entry in the
-    # +:grant+ hash has a grant (key) and a list of grantees (values).
+    # `:grant` hash has a grant (key) and a list of grantees (values).
     # Valid grant keys are:
     #
-    # * +:grant_read+
-    # * +:grant_write+
-    # * +:grant_read_acp+
-    # * +:grant_write_acp+
-    # * +:grant_full_control+
+    # * `:grant_read`
+    # * `:grant_write`
+    # * `:grant_read_acp`
+    # * `:grant_write_acp`
+    # * `:grant_full_control`
     #
     # Each grantee can be a String, Hash or array of strings or hashes.
     # The following example uses grants to provide public read
     # to everyone while providing full control to a user by email address
     # and to another by their account id (cannonical user id).
     #
-    #   bucket = s3.buckets.create('name', :grants => {
-    #     :grant_read => [
-    #       { :uri => "http://acs.amazonaws.com/groups/global/AllUsers" },
-    #     ],
-    #     :grant_full_control => [
-    #       { :id => 'abc...mno' }               # cannonical user id
-    #       { :email_address => 'foo@bar.com' }, # email address
-    #     ]
-    #   })
+    #     bucket = s3.buckets.create('name', :grants => {
+    #       :grant_read => [
+    #         { :uri => "http://acs.amazonaws.com/groups/global/AllUsers" },
+    #       ],
+    #       :grant_full_control => [
+    #         { :id => 'abc...mno' }               # cannonical user id
+    #         { :email_address => 'foo@bar.com' }, # email address
+    #       ]
+    #     })
     #
-    # === ACL Object
+    # ### ACL Object
     #
     # Lastly, you can build an ACL object and use a Ruby DSL to specify grants
     # and grantees.  See {ACLObject} for more information.
     #
-    #   # updating an existing bucket acl using ACLObject
-    #   bucket.acl.change do |acl|
-    #     acl.grants.reject! do |g|
-    #       g.grantee.canonical_user_id != bucket.owner.id
+    #     # updating an existing bucket acl using ACLObject
+    #     bucket.acl.change do |acl|
+    #       acl.grants.reject! do |g|
+    #         g.grantee.canonical_user_id != bucket.owner.id
+    #       end
     #     end
-    #   end
     #
-    # == Policies
+    # ## Policies
     #
     # You can also work with bucket policies.
     #
-    #   policy = AWS::S3::Policy.new
-    #   policy.allow(
-    #     :actions => [:put_object, :get_object]
-    #     :resources => [bucket]
-    #     :principals => :any)
+    #     policy = AWS::S3::Policy.new
+    #     policy.allow(
+    #       :actions => [:put_object, :get_object]
+    #       :resources => [bucket]
+    #       :principals => :any)
     #
-    #   bucket.policy = policy
+    #     bucket.policy = policy
     #
     # See {Core::Policy} and {S3::Policy} for more information on build
     # policy objects.
     #
-    # = Versioned Buckets
+    # # Versioned Buckets
     #
     # You can enable versioning on a bucket you control.  When versioning
     # is enabled, S3 will keep track of each version of each object you
     # write to the bucket (even deletions).
     #
-    #   bucket.versioning_enabled? #=> false
-    #   bucket.enable_versioning
-    #   # there is also a #suspend_versioning method
-    #
-    #   obj = bucket.objects['my-obj']
-    #   obj.write('a')
-    #   obj.write('b')
-    #   obj.delete
-    #   obj.write('c')
-    #
-    #   obj.versions.each do |obj_version|
-    #     if obj_version.delete_marker?
-    #       puts obj_version.read
-    #     else
-    #       puts "- DELETE MARKER"
+    #     bucket.versioning_enabled? #=> false
+    #     bucket.enable_versioning
+    #     # there is also a #suspend_versioning method
+    #
+    #     obj = bucket.objects['my-obj']
+    #     obj.write('a')
+    #     obj.write('b')
+    #     obj.delete
+    #     obj.write('c')
+    #
+    #     obj.versions.each do |obj_version|
+    #         if obj_version.delete_marker?
+    #         puts obj_version.read
+    #       else
+    #         puts "- DELETE MARKER"
+    #       end
     #     end
-    #   end
     #
     # Alternatively you can enumerate all versions of all objects in your
     # bucket.
     #
-    #   bucket.versions.each do |obj_version|
-    #     puts obj_version.key + " : " + obj_version.version_id
-    #   end
+    #     bucket.versions.each do |obj_version|
+    #       puts obj_version.key ` " : " ` obj_version.version_id
+    #     end
     #
     # See {BucketVersionCollection}, {ObjectVersionCollection} and
     # {ObjectVersion} for more information on working with objects in
@@ -260,24 +260,24 @@ module AWS
 
       # Configure the current bucket as a website.
       #
-      #   bucket.configure_website
+      #     bucket.configure_website
       #
       # If you pass a block, the website configuration object
       # will be yielded.  You can modify it before it is saved.
       #
-      #   bucket.configure_website do |cfg|
-      #     cfg.index_document_suffix = 'index.html'
-      #     cfg.error_document_key = 'error.html'
-      #   end
+      #     bucket.configure_website do |cfg|
+      #       cfg.index_document_suffix = 'index.html'
+      #       cfg.error_document_key = 'error.html'
+      #     end
       #
       # If the bucket already has a website configuration, it will be loaded
       # and yielded.  This makes it possible to modify an existing
       # configuration.
       #
-      #   # only rename the error document
-      #   bucket.configure_website do |cfg|
-      #     cfg.error_document_key = 'oops.html'
-      #   end
+      #     # only rename the error document
+      #     bucket.configure_website do |cfg|
+      #       cfg.error_document_key = 'oops.html'
+      #     end
       #
       # @yieldparam [WebsiteConfiguration] website_config
       # @return [WebsiteConfiguration]
@@ -292,7 +292,7 @@ module AWS
         self.website_configuration = website_config
       end
 
-      # Returns the bucket website configuration. Returns +nil+ if the bucket
+      # Returns the bucket website configuration. Returns `nil` if the bucket
       # is not configured as a website.
       # @return [WebsiteConfiguration,nil]
       # @see #configure_website
@@ -307,7 +307,7 @@ module AWS
       end
 
       # Sets the website configuration.  Deletes the configuration if
-      # +nil+ is passed.
+      # `nil` is passed.
       # @param [WebsiteConfiguration,nil] website_configuration
       # @see #configure_website
       # @see #website_configuration
@@ -334,7 +334,7 @@ module AWS
         nil
       end
 
-      # @return [Boolean] Returns +true+ if this bucket is configured as
+      # @return [Boolean] Returns `true` if this bucket is configured as
       #   a website.
       # @see #configure_website
       # @see #website_configuration
@@ -346,20 +346,20 @@ module AWS
 
       # Returns the tags for this bucket.
       #
-      #   tags = bucket.tags
-      #   #=> <AWS::S3::BucketTagCollection>
+      #     tags = bucket.tags
+      #     #=> <AWS::S3::BucketTagCollection>
       #
-      #   # adds a tag to the bucket
-      #   tags['foo'] = 'abc'
+      #     # adds a tag to the bucket
+      #     tags['foo'] = 'abc'
       #
-      #   # replaces all tags
-      #   tags.set('new' => 'tags')
+      #     # replaces all tags
+      #     tags.set('new' => 'tags')
       #
-      #   # removes all tags from the bucket
-      #   tags.clear
+      #     # removes all tags from the bucket
+      #     tags.clear
       #
-      #   # returns tags as a hash
-      #   tags.to_h
+      #     # returns tags as a hash
+      #     tags.to_h
       #
       # @return [BucketTagCollection] Returns a collection that represents
       #   the tags for this bucket.
@@ -370,14 +370,14 @@ module AWS
 
       # Sets the tags for this bucket.
       #
-      #   bucket.tags = { 'contents' => 'photots' }
+      #     bucket.tags = { 'contents' => 'photots' }
       #
       # You can remove all tags for the bucket by passing an empty
-      # hash or +nil+.
+      # hash or `nil`.
       #
-      #   bucket.tags = nil # {} also deletes all tags
-      #   bucket.tags
-      #   #=> {}
+      #     bucket.tags = nil # {} also deletes all tags
+      #     bucket.tags
+      #     #=> {}
       #
       # @param [Hash,nil] tags The tags to set on this bucket.
       #
@@ -438,7 +438,7 @@ module AWS
         nil
       end
 
-      # @return [Boolean] returns +true+ if version is enabled on this bucket.
+      # @return [Boolean] returns `true` if version is enabled on this bucket.
       def versioning_enabled?
         versioning_state == :enabled
       end
@@ -446,9 +446,9 @@ module AWS
 
       # Returns the versioning status for this bucket.  States include:
       #
-      # * +:enabled+ - currently enabled
-      # * +:suspended+ - currently suspended
-      # * +:unversioned+ - versioning has never been enabled
+      # * `:enabled` - currently enabled
+      # * `:suspended` - currently suspended
+      # * `:unversioned` - versioning has never been enabled
       #
       # @return [Symbol] the versioning state
       def versioning_state
@@ -510,7 +510,7 @@ module AWS
           true
         rescue Errors::NoSuchBucket => e
           false # bucket does not exist
-        rescue Errors::ClientError => e
+        rescue Errors::AccessDenied => e
           true # bucket exists
         end
       end
@@ -546,14 +546,14 @@ module AWS
       end
 
       # Returns the bucket's access control list.  This will be an
-      # instance of AccessControlList, plus an additional +change+
+      # instance of AccessControlList, plus an additional `change`
       # method:
       #
-      #   bucket.acl.change do |acl|
-      #     acl.grants.reject! do |g|
-      #       g.grantee.canonical_user_id != bucket.owner.id
+      #     bucket.acl.change do |acl|
+      #       acl.grants.reject! do |g|
+      #         g.grantee.canonical_user_id != bucket.owner.id
+      #       end
       #     end
-      #   end
       #
       # @return [AccessControlList]
       def acl
@@ -597,15 +597,15 @@ module AWS
       # PolicyProxy mixed in, so you can use it to change the
       # current policy or delete it, for example:
       #
-      #  if policy = bucket.policy
-      #    # add a statement
-      #    policy.change do |p|
-      #      p.allow(...)
-      #    end
+      #     if policy = bucket.policy
+      #       # add a statement
+      #       policy.change do |p|
+      #         p.allow(...)
+      #       end
       #
-      #    # delete the policy
-      #    policy.delete
-      #  end
+      #       # delete the policy
+      #       policy.delete
+      #     end
       #
       # Note that changing the policy is not an atomic operation; it
       # fetches the current policy, yields it to the block, and then
@@ -614,7 +614,7 @@ module AWS
       # method.
       #
       # @return [Policy,nil] Returns the bucket policy (if it has one),
-      #   or it returns +nil+ otherwise.
+      #   or it returns `nil` otherwise.
       def policy
         resp = client.get_bucket_policy(:bucket_name => name)
         policy = Policy.from_json(resp.data[:policy])
@@ -629,7 +629,7 @@ module AWS
       #
       # @param policy The new policy.  This can be a string (which
       #   is assumed to contain a valid policy expressed in JSON), a
-      #   Policy object or any object that responds to +to_json+.
+      #   Policy object or any object that responds to `to_json`.
       # @see Policy
       # @return [nil]
       def policy=(policy)
@@ -660,16 +660,16 @@ module AWS
       # You can call this method if you prefer to build your own
       # lifecycle configuration.
       #
-      #   bucket.lifecycle_configuration = <<-XML
-      #     <LifecycleConfiguration>
-      #       ...
-      #     </LifecycleConfiguration>
-      #   XML
+      #     bucket.lifecycle_configuration = <<-XML
+      #       <LifecycleConfiguration>
+      #         ...
+      #       </LifecycleConfiguration>
+      #     XML
       #
       # You can also use this method to copy a lifecycle configuration
       # from another bucket.
       #
-      #   bucket.lifecycle_configuration = other_bucket.lifecycle_configuration
+      #     bucket.lifecycle_configuration = other_bucket.lifecycle_configuration
       #
       # If you call this method, passing nil, the lifecycle configuration
       # for this bucket will be deleted.
@@ -713,7 +713,7 @@ module AWS
       # @see Tree
       # @param [Hash] options
       # @option options [String] :prefix (nil) Set prefix to choose where
-      #   the top of the tree will be.  A value of +nil+ means
+      #   the top of the tree will be.  A value of `nil` means
       #   that the tree will include all objects in the collection.
       #
       # @option options [String] :delimiter ('/') The string that separates