.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::Amazon::S3::Bucket 3pm"
.TH Net::Amazon::S3::Bucket 3pm "2011-12-18" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::Amazon::S3::Bucket \- convenience object for working with Amazon S3 buckets
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Net::Amazon::S3;
\&
\&  my $bucket = $s3\->bucket("foo");
\&
\&  ok($bucket\->add_key("key", "data"));
\&  ok($bucket\->add_key("key", "data", {
\&     content_type => "text/html",
\&    \*(Aqx\-amz\-meta\-colour\*(Aq => \*(Aqorange\*(Aq,
\&  });
\&
\&  # the err and errstr methods just proxy up to the Net::Amazon::S3\*(Aqs
\&  # objects err/errstr methods.
\&  $bucket\->add_key("bar", "baz") or
\&      die $bucket\->err . $bucket\->errstr;
\&
\&  # fetch a key
\&  $val = $bucket\->get_key("key");
\&  is( $val\->{value},               \*(Aqdata\*(Aq );
\&  is( $val\->{content_type},        \*(Aqtext/html\*(Aq );
\&  is( $val\->{etag},                \*(Aqb9ece18c950afbfa6b0fdbfa4ff731d3\*(Aq );
\&  is( $val\->{\*(Aqx\-amz\-meta\-colour\*(Aq}, \*(Aqorange\*(Aq );
\&
\&  # returns undef on missing or on error (check $bucket\->err)
\&  is(undef, $bucket\->get_key("non\-existing\-key"));
\&  die $bucket\->errstr if $bucket\->err;
\&
\&  # fetch a key\*(Aqs metadata
\&  $val = $bucket\->head_key("key");
\&  is( $val\->{value},               \*(Aq\*(Aq );
\&  is( $val\->{content_type},        \*(Aqtext/html\*(Aq );
\&  is( $val\->{etag},                \*(Aqb9ece18c950afbfa6b0fdbfa4ff731d3\*(Aq );
\&  is( $val\->{\*(Aqx\-amz\-meta\-colour\*(Aq}, \*(Aqorange\*(Aq );
\&
\&  # delete a key
\&  ok($bucket\->delete_key($key_name));
\&  ok(! $bucket\->delete_key("non\-exist\-key"));
\&
\&  # delete the entire bucket (Amazon requires it first be empty)
\&  $bucket\->delete_bucket;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module represents an S3 bucket.  You get a bucket object
from the Net::Amazon::S3 object.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
Create a new bucket object. Expects a hash containing these two arguments:
.IP "bucket" 4
.IX Item "bucket"
.PD 0
.IP "account" 4
.IX Item "account"
.PD
.SS "add_key"
.IX Subsection "add_key"
Takes three positional parameters:
.IP "key" 4
.IX Item "key"
.PD 0
.IP "value" 4
.IX Item "value"
.IP "configuration" 4
.IX Item "configuration"
.PD
A hash of configuration data for this key. (See synopsis);
.PP
Returns a boolean.
.SS "add_key_filename"
.IX Subsection "add_key_filename"
Use this to upload a large file to S3. Takes three positional parameters:
.IP "key" 4
.IX Item "key"
.PD 0
.IP "filename" 4
.IX Item "filename"
.IP "configuration" 4
.IX Item "configuration"
.PD
A hash of configuration data for this key. (See synopsis);
.PP
Returns a boolean.
.SS "copy_key"
.IX Subsection "copy_key"
Creates (or replaces) a key, copying its contents from another key elsewhere in S3.
Takes the following parameters:
.IP "key" 4
.IX Item "key"
The key to (over)write
.IP "source" 4
.IX Item "source"
Where to copy the key from. Should be in the form \f(CW\*(C`/\f(CIbucketname\f(CW/\f(CIkeyname\f(CW\*(C'\fR/.
.IP "conf" 4
.IX Item "conf"
Optional configuration hash. If present and defined, the configuration (\s-1ACL\s0
and headers) there will be used for the new key; otherwise it will be copied
from the source key.
.SS "edit_metadata"
.IX Subsection "edit_metadata"
Changes the metadata associated with an existing key. Arguments:
.IP "key" 4
.IX Item "key"
The key to edit
.IP "conf" 4
.IX Item "conf"
The new configuration hash to use
.SS "head_key \s-1KEY\s0"
.IX Subsection "head_key KEY"
Takes the name of a key in this bucket and returns its configuration hash
.ie n .SS "get_key $key_name [$method]"
.el .SS "get_key \f(CW$key_name\fP [$method]"
.IX Subsection "get_key $key_name [$method]"
Takes a key name and an optional \s-1HTTP\s0 method (which defaults to \f(CW\*(C`GET\*(C'\fR.
Fetches the key from \s-1AWS\s0.
.PP
On failure:
.PP
Returns undef on missing content, throws an exception (dies) on server errors.
.PP
On success:
.PP
Returns a hashref of { content_type, etag, value, \f(CW@meta\fR } on success. Other
values from the server are there too, with the key being lowercased.
.ie n .SS "get_key_filename $key_name $method $filename"
.el .SS "get_key_filename \f(CW$key_name\fP \f(CW$method\fP \f(CW$filename\fP"
.IX Subsection "get_key_filename $key_name $method $filename"
Use this to download large files from S3. Takes a key name and an optional 
\&\s-1HTTP\s0 method (which defaults to \f(CW\*(C`GET\*(C'\fR. Fetches the key from \s-1AWS\s0 and writes
it to the filename. THe value returned will be empty.
.PP
On failure:
.PP
Returns undef on missing content, throws an exception (dies) on server errors.
.PP
On success:
.PP
Returns a hashref of { content_type, etag, value, \f(CW@meta\fR } on success
.ie n .SS "delete_key $key_name"
.el .SS "delete_key \f(CW$key_name\fP"
.IX Subsection "delete_key $key_name"
Removes \f(CW$key\fR from the bucket. Forever. It's gone after this.
.PP
Returns true on success and false on failure
.SS "delete_bucket"
.IX Subsection "delete_bucket"
Delete the current bucket object from the server. Takes no arguments.
.PP
Fails if the bucket has anything in it.
.PP
This is an alias for \f(CW\*(C`$s3\->delete_bucket($bucket)\*(C'\fR
.SS "list"
.IX Subsection "list"
List all keys in this bucket.
.PP
see \*(L"list_bucket\*(R" in Net::Amazon::S3 for documentation of this method.
.SS "list_all"
.IX Subsection "list_all"
List all keys in this bucket without having to worry about
\&'marker'. This may make multiple requests to S3 under the hood.
.PP
see \*(L"list_bucket_all\*(R" in Net::Amazon::S3 for documentation of this method.
.SS "get_acl"
.IX Subsection "get_acl"
Takes one optional positional parameter
.IP "key (optional)" 4
.IX Item "key (optional)"
If no key is specified, it returns the acl for the bucket.
.PP
Returns an acl in \s-1XML\s0 format.
.SS "set_acl"
.IX Subsection "set_acl"
Takes a configuration hash_ref containing:
.IP "acl_xml (cannot be used in conjunction with acl_short)" 4
.IX Item "acl_xml (cannot be used in conjunction with acl_short)"
An \s-1XML\s0 string which contains access control information which matches
Amazon's published schema.  There is an example of one of these \s-1XML\s0 strings
in the tests for this module.
.IP "acl_short (cannot be used in conjunction with acl_xml)" 4
.IX Item "acl_short (cannot be used in conjunction with acl_xml)"
You can use the shorthand notation instead of specifying \s-1XML\s0 for
certain 'canned' types of acls.
.Sp
(from the Amazon \s-1API\s0 documentation)
.Sp
private: Owner gets \s-1FULL_CONTROL\s0. No one else has any access rights.
This is the default.
.Sp
public\-read:Owner gets \s-1FULL_CONTROL\s0 and the anonymous principal is granted
\&\s-1READ\s0 access. If this policy is used on an object, it can be read from a
browser with no authentication.
.Sp
public\-read\-write:Owner gets \s-1FULL_CONTROL\s0, the anonymous principal is
granted \s-1READ\s0 and \s-1WRITE\s0 access. This is a useful policy to apply to a bucket,
if you intend for any anonymous user to \s-1PUT\s0 objects into the bucket.
.Sp
authenticated\-read:Owner gets \s-1FULL_CONTROL\s0, and any principal authenticated
as a registered Amazon S3 user is granted \s-1READ\s0 access.
.IP "key (optional)" 4
.IX Item "key (optional)"
If the key is not set, it will apply the acl to the bucket.
.PP
Returns a boolean.
.SS "get_location_constraint"
.IX Subsection "get_location_constraint"
Retrieves the location constraint set when the bucket was created. Returns a
string (eg, '\s-1EU\s0'), or undef if no location constraint was set.
.SS "err"
.IX Subsection "err"
The S3 error code for the last error the object ran into
.SS "errstr"
.IX Subsection "errstr"
A human readable error string for the last error the object ran into
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Net::Amazon::S3