#
# = Atmos
#
# This gem is a Ruby library for EMC's Atmos (http://www.emc.com/atmos) REST API.
#
# Logging is done via the <tt>Log4r</tt> package.  The name of the logger is the string +atmos+,
# and the log level is set to <tt>Log4r::FATAL</tt> by default.
#
# == Getting started
#
# You'll need this gem and a URL to your Atmos installation.  
# You'll also need your Atmos authentication credentials.
#
# == Basics
# === XML Parser
#
# The very first thing is that you have to pick your XML parser.  There are two options:
# <tt>nokogiri</tt> for performance or <tt>rexml</tt> for only pure ruby requirements.
# Setting the parser does the require, so make sure you have the gem you want to use installed.
# This gem doesn't require either, since it doesn't know which you plan to use.
#
#    Atmos::Parser::parser = Atmos::Parser::NOKOGIRI
#    Atmos::Parser::parser = Atmos::Parser::REXML
#
#
# === Datastore
#
# The Atmos installation you will be connecting to is your datastore.  You
# can see more detailed information at <tt>Atmos::Store</tt>.
# 
#    store = Atmos::Store.new(:url    => "https://mgmt.atmosonline.com", 
#                             :uid    => <your identifier>, 
#                             :secret => <your secret>)
#
# From your store, you can create and retrieve objects.  Note that objects
# are always retrieved without their data, so a progressive download can 
# be done.
#
#    obj = store.get(id)
#    newobj = store.create(options)
#  
# Now that you have a store, you can iterate through all listable tags, object ids
# by listable tag, and objects by listable tag.  Remember that when an Atmos::Object
# is instantiated, it loads all ACLs and Metadata.
#
#    store.each_listable_tag { |tag| }
#
#    store.each_object_id_by_tag(tag) do |id|
#    end
#
#    store.each_object_by_tag(tag) do |obj|
#    end
#
#
# === Objects
# See <tt>Atmos::Object</tt> for more detailed info on the object API.
#
# ==== Creating Objects
#
# At the very simplest, you can create an object with nothing.  The mimetype 
# will default to <tt>binary/octet-stream</tt>.  The object will be created 
# with no data, no metadata, with permissions set for only the creator to access.
#
#     obj = store.create()
#  
# You can also create an object with (any combination of) more information 
# up front. (See <tt>Atmos::Store.create</tt> for more detailed info on 
# object creation options.)
#
#     obj = store.create(
#                          :user_acl          => {'janet' => :full, 'xavier' => :read},
#                          :group_acl         => {'other' => :read},
#                          :metadata          => {'key' => 'value', 'another_key' => nil},
#                          :listable_metadata => {'lkey' => 'lvalue', 'another_lkey' => nil},
#                          :mimetype          => "video/quicktime",
#                          :data              => open("local/video_file.qt")
#                         )
#
# ===== Reading Objects
#
# You can get the data for an object all at once, which means it all 
# gets read into memory all at once:
#
#    @data = @obj.data
#  
# Or progressively download it by passing a block to <tt>read</tt>:
#
#  @file = open('mydata', 'w')
#  @obj.read do |chunk|
#      @file.write chunk
#  end
#
#
# ===== Object Metadata
#
# An object has system and user metadata.  User metadata can be modified, 
# system metadata cannot.  User metadata is further divided into listable 
# and non-listable metadata.  Listable metadata means the object is indexed 
# on the key value of the metadata key/value pair (also known as a 
# <tt>tag</tt>), and can be retrieved via the tag.
#
# Set or change user metadata, listable or non-listable, keys and values must be Strings:
#
#  @obj.metadata[newkey] = "newvalue"
#
# (See <tt>Atmos::Metadata</tt> for more detailed info.)
#
#
# ===== Object ACL
#
# There are two ACLs on an object: <tt>user_acl</tt> and <tt>group_acl</tt>.
# User and group names are ruby Strings, while the values are one of the
# following symbols: <tt>:none</tt>, <tt>:read</tt>, <tt>:write</tt> ,<tt>:full</tt>.
# They are accessed as Hashes on the object.  All normal Hash functions will work.
#
# When permissions are set to <tt>:none</tt> the pair disappears from the hash.
#
#  @obj.user_acl['user'] = :full
#  @obj.group_acl['other'] = :none
#
# (See <tt>Atmos::ACL</tt> for more detailed info.)
#
#
# ===== Other Object Functionality
#
#  @obj.exists?
#  @obj.delete
# 

