NAME
    Net::Mosso::CloudFiles - Interface to Mosso CloudFiles service

SYNOPSIS
      use Net::Mosso::CloudFiles;
      use Perl6::Say;

      my $cloudfiles = Net::Mosso::CloudFiles->new(
          user => 'myusername',
          key  => 'mysecretkey',
      );

      # list all containers
      my @containers = $cloudfiles->containers;
      foreach my $container (@containers) {
          say 'have container ' . $container->name;
      }

      # create a new container
      my $container = $cloudfiles->create_container(name => 'testing');

      # use an existing container
      my $existing_container = $cloudfiles->container(name => 'testing');

      my $total_bytes_used = $cloudfiles->total_bytes_used;
      say "used $total_bytes_used";

      my $object_count = $container->object_count;
      say "$object_count objects";

      my $bytes_used = $container->bytes_used;
      say "$bytes_used bytes";

      # returns a Data::Stream::Bulk object
      # as it may have to make multiple HTTP requests
      my @objects = $container->objects->all;
      foreach my $object (@objects) {
          say 'have object ' . $object->name;
          # also size, etag, content_type, last_modified
      }
      my @objects2 = $container->objects(prefix => 'dir/')->all;

      # To create a new object
      my $xxx = $container->object( name => 'XXX' );
      $xxx->put('this is the value');

      # To set metadata of an object:
      $xxx->object_metadata({
          description => 'this is a description',
          useful_number => 17
      });
	  
      # To create a new object with the contents of a local file
      my $yyy = $container->object( name => 'YYY', content_type => 'text/plain' );
      $yyy->put_filename('README');

      # To fetch an object:
      my $xxx2 = $container->object( name => 'XXX' );
      my $value = $xxx2->get;
      say 'has name ' . $xxx2->name;
      say 'has md5 ' . $xxx2->etag;
      say 'has size ' . $xxx2->size;
      say 'has content type ' . $xxx2->content_type;
      say 'has last_modified ' . $xxx2->last_modified;

      # To fetch metadata of an object:
      say 'metadata description ' . $xxx2->object_metadata->{'description'};
      say 'metadata useful_number ' . $xxx2->object_metadata->{'useful_number'};
	  
      # To download an object to a local file
      $yyy->get_filename('README.downloaded');

      $object->delete;

      $container->delete;

DESCRIPTION
    This module provides a simple interface to the Mosso Cloud Files
    service. "Cloud Files is reliable, scalable and affordable web-based
    storage for backing up and archiving all your static content". Find out
    more at <http://www.mosso.com/cloudfiles.jsp>.

    To use this module you will need to sign up to Mosso Cloud Files and
    provide a "user" and "key". If you use this module, you will incurr
    costs as specified by Mosso. Please check the costs. If you use this
    module with your user and key you will be responsible for these costs.

    I highly recommend reading all about Cloud Files, but in a nutshell data
    is stored in objects. Objects are referenced by names and objects are
    stored in containers.

METHODS
  new
    The constructor logs you into Cloud Files:

      my $cloudfiles = Net::Mosso::CloudFiles->new(
          user => 'myusername',
          key  => 'mysecretkey',
      );

  containers
    List all the containers and return them as
    Net::Mosso::CloudFiles::Container objects:

      my @containers = $cloudfiles->containers;

  create_container
    Create a new container and return it as a
    Net::Mosso::CloudFiles::Container object:

      my $container = $cloudfiles->create_container(name => 'testing');

  container
    Use an existing container and return it as a
    Net::Mosso::CloudFiles::Container object:

      my $existing_container = $cloudfiles->container(name => 'testing');

  total_bytes_used
    Returns the total amount of bytes used in your Cloud Files account:

      my $total_bytes_used = $cloudfiles->total_bytes_used;

TESTING
    Testing CloudFiles is a tricky thing. Mosso charges you a bit of money
    each time you use their service. And yes, testing counts as using.
    Because of this, this module's test suite skips testing unless you set
    the following three environment variables, along the lines of:

      CLOUDFILES_EXPENSIVE_TESTS=1 CLOUDFILES_USER=username CLOUDFILES_KEY=15bf43... perl t/simple.t

SEE ALSO
    Net::Mosso::CloudFiles::Container, Net::Mosso::CloudFiles::Object.

AUTHOR
    Leon Brocard <acme@astray.com>.

COPYRIGHT
    Copyright (C) 2008-9, Leon Brocard

LICENSE
    This module is free software; you can redistribute it or modify it under
    the same terms as Perl itself.