crate_api 0.1.0 → 0.1.1

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/crate_api.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{crate_api}
-  s.version = "0.1.0"
+  s.version = "0.1.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Brian Michel"]
-  s.date = %q{2011-04-23}
+  s.date = %q{2011-04-24}
   s.description = %q{This gem will allow for easy interaction with the Crate API to share your files!}
   s.email = %q{brian.michel@gmail.com}
   s.extra_rdoc_files = [

data/lib/crate_api/base.rb

@@ -1,25 +1,55 @@
 module CrateAPI
+  # NotValidUserError class which is raised due to bad credentials.
   class NotValidUserError < Exception
+    
   end
-  
+
+  # Base class which is used to authenticate user and perform calls.
+  #
   class Base
     include HTTMultiParty
 
+    # @attr [Hash] :auth auth hash.
     attr_accessor :auth
+    # Current API Version.
     API_VERSION = 1
+    # Base URL Endpoint
     BASE_URL = "https://api.letscrate.com/#{API_VERSION}"
+    # Authorization URL Endpoint.
     AUTH_URL = "#{BASE_URL}/users/authenticate.json"
+    # Items URL Endpoint.
     ITEMS_URL = "#{BASE_URL}/files"
+    # Crates URL Endpoint.
     CRATES_URL = "#{BASE_URL}/crates"
+    # Short URL Placeholder String.
     SHORT_URL = "http://lts.cr/%s"
+    
+    # Default initializer for getting a Crates instance.
+    # @return [CrateAPI::Crates] a new Crates instance.
     def crates(); @crates || CrateAPI::Crates.new(); end
+    
+    # Default initializer for getting a Items instance.
+    # @return [CrateAPI::Items] a new Items instance.
     def items(); @items || CrateAPI::Items.new(); end
     
+    # Default initializer for the CrateAPI Client
+    #
+    # @param [String] username username for the Crate user.
+    # @param [String] password password for the Crate user.
+    # @return [CrateAPI::Base] this will return the base class instance.
+    # @raise [NotValidUserError] this will occur if the username/password pair is not valid.
     def initialize(username, password)
       raise NotValidUserError unless CrateAPI::Base.authorized?(username, password)
       @@auth = {:username => username, :password => password}
     end
     
+    
+    # Class method that return the response body of the call.
+    # 
+    # @param [String] url URL endpoint to make the call to.
+    # @param [Symbol] verb HTTP verb used for call.
+    # @param [Optional] params Hash of params used for call.
+    # @return [Object] body object from the response.
     def self.call(url, verb, params={})
       params.merge!({:basic_auth => @@auth})
       resp = nil
@@ -34,6 +64,11 @@ module CrateAPI
       end
     end
     
+    # Class method that will return a boolean whether or not the user is authorized.
+    #
+    # @param [String] username Username to test for authorization.
+    # @param [String] pass Password to test for authorization.
+    # @return [Boolean] whether or not the user is authorized.
     def self.authorized?(user, pass)
       resp = self.get("#{AUTH_URL}", {:basic_auth => {:username => user, :password => pass}})
       if resp.code == 401

data/lib/crate_api/crate.rb

@@ -1,13 +1,17 @@
 module CrateAPI
+  # CrateRenameError class which is raised when there is a problem renaming a given Crate.
   class CrateRenameError < Exception
   end
   
+  # CrateDestroyError class which is raised when there is a problem destroying a given Crate.
   class CrateDestroyError < Exception
   end
   
+  # CrateFileAlreadyExistsError class which is raised when there is a problem uploading a file to a given Crate.
   class CrateFileAlreadyExistsError < Exception
   end
 
+  # Crate object class which is used to manipulate the single Crate object.
   class Crate < CrateObject
       attr_reader :files
       def initialize(hash)
@@ -15,16 +19,26 @@ module CrateAPI
         @files = CrateAPI::Items.from_array(hash["files"])
       end
       
+      # Destroys the given crate object.
+      #
+      # @return [CrateDestroyError, nil] if there is an issue destroying the crate, an error will be raised with the message explaining why. 
       def destroy
         response = JSON.parse(CrateAPI::Base.call("#{CrateAPI::Base::CRATES_URL}/#{CrateAPI::Crates::CRATE_ACTIONS[:destroy] % ["#{self.id}"]}", :post))
         raise CrateDestroyError, response["message"] unless response["status"] != "failure"
       end
       
+      # Renamed the given crate object.
+      #
+      # @return [CrateRenameError, nil] if there is an issue with renaming the crate, an error will be raised with the message explaining why.
       def rename(name)
         response = JSON.parse(CrateAPI::Base.call("#{CrateAPI::Base::CRATES_URL}/#{CrateAPI::Crates::CRATE_ACTIONS[:rename] % ["#{self.id}"]}", :post, {:body => {:name => name}}))
         raise CrateRenameError, response["message"] unless response["status"] != "failure"
       end
       
+      # Add a file to the given crate object.
+      #
+      # @param [String] This is the path to the file that you wish to upload.
+      # @return [CrateFileAlreadyExistsError, nil] if there is an issue uploading the file to the crate, an error will be raised with the message explaining why.
       def add_file(path)
         file = File.new(path)
         response = CrateAPI::Base.call("#{CrateAPI::Base::ITEMS_URL}/#{CrateAPI::Items::ITEM_ACTIONS[:upload]}", :post, {:body => {:file => file, :crate_id => @id}})

data/lib/crate_api/crateobject.rb

@@ -1,13 +1,28 @@
 module CrateAPI
+  # Base class for Crate and Item objects
+  # @abstract Subclass in order to get the basic +:short_code+ , +:name+ , +:id+ params that every object should have.
   class CrateObject
+    # @attr_reader [String] short_code short code for constructing the short url.
+    # @attr_reader [String] name name of the CrateObject that is being accessed.
+    # @attr_reader [Integer] id the numeric id of the CrateObject that is being accessed.
     attr_reader :short_code, :name, :id
-
+    
+    # The default initializer for the CrateObject class
+    #
+    # @param [Hash] a hash of values used to initialize the CrateObject.
+    # @option opts [String] :short_code short code for short url
+    # @option opts [String] :name name of the object
+    # @option opts [Integer] :id id of the object
+    # @return [CrateObject] this will return an initialized CrateObject instance.
     def initialize(hash)
       @short_code = hash["short_code"]
       @name = hash["name"]
       @id = hash["id"]
     end
-
+    
+    # Will return the shortened url of a given object
+    #
+    # @return [String] shortened url string for a given object.
     def short_url
       return "#{CrateAPI::Base::SHORT_URL}" % ["#{@short_code}"]
     end

data/lib/crate_api/crates.rb

@@ -1,8 +1,11 @@
 module CrateAPI
+  # CrateLimitReachedError class which is raised when the user can no longer add a crate to their account due to restriction.
   class CrateLimitReachedError < Exception
   end
 
+  # Crates class which is used to add, list, manipulate the Crates on a given account.
   class Crates
+    # Hash of available actions to take upon the Crates endpoint.
     CRATE_ACTIONS = {
       :add => "add.json",
       :list => "list.json",
@@ -10,21 +13,36 @@ module CrateAPI
       :destroy => "destroy/%s.json"
     }
     
+    # Add a new crate. 
+    # 
+    # @param [String] name of the crate to add.
+    # @return [nil] no output from this method is expected if everything goes right.
     def add(name)
       response = JSON.parse(CrateAPI::Base.call("#{CrateAPI::Base::CRATES_URL}/#{CRATE_ACTIONS[:add]}", :post, {:body => {:name => name}}))
       raise CrateLimitReachedError, response["message"] unless response["status"] != "failure"
     end
 
+    # Get a list of crates (w/o files).
+    # 
+    # @return [Array] an array of crate objects.
+    # @note This will not return crate objects with the files they contain. 
+    # @see Crates#all
     def list
       hash = JSON.parse(CrateAPI::Base.call("#{CrateAPI::Base::CRATES_URL}/#{CRATE_ACTIONS[:list]}", :get))
       return Crates.from_array(hash["crates"])
     end
     
+    # Get a list of crates (w/ files).
+    #
+    # @return [Array] an array of crate objects.
     def all
       hash = JSON.parse(CrateAPI::Base.call("#{CrateAPI::Base::ITEMS_URL}/#{CRATE_ACTIONS[:list]}", :get))
       return Crates.from_array(hash["crates"])
     end
     
+    # Class method to return an array of crate objects.
+    # 
+    # @return [Array] an array of initialized Crate objects.
     def self.from_array(array)
       return [] unless array != nil
       crates = Array.new

data/lib/crate_api/item.rb

@@ -1,13 +1,24 @@
 module CrateAPI
+  # FileDestroyError which is raised when there is an issue destroying the file.
   class FileDestroyError < Exception
   end
+  
+  # Item class which is used to manipulate and represent a file blob which is inside of a Crate.
   class Item < CrateObject
       attr_reader :size
+      # Default initializer for the Item object.
+      #
+      # @param [Hash] hash an item hash.
+      # @return [CrateAPI::Item] a fully initialized Item object.
       def initialize(hash)
         super(hash)
         @size = hash["size"]
       end
       
+      # Will destroy the given file.
+      # 
+      # @return [nil] this method should return nil if there are no issues.
+      # @raise [FileDestroyError] an error and message describing what happened.
       def destroy
         response = JSON.parse(CrateAPI::Base.call("#{CrateAPI::Base::ITEMS_URL}/#{CrateAPI::Items::ITEM_ACTIONS[:destroy] % ["#{self.id}"]}", :post))
         raise FileDestroyError, response["message"] unless response["status"] != "failure"

data/lib/crate_api/items.rb

@@ -1,12 +1,17 @@
 module CrateAPI
+  # Items class which is used to get a set of items from the service.
   class Items
+    # Hash of available actions to take upon the Items endpoint.
     ITEM_ACTIONS = {
       :upload => "upload.json",
       :list => "list.json",
       :show => "show/%s.json",
       :destroy => "destroy/%s.json"
     }
-    
+    # Creates an array of Item objects.
+    #
+    # @param [Array] array to be used as the generation source.
+    # @return [Array] either an empty array if the input array is nil or a fully inialized array of Item objects.
     def self.from_array(array)
       return [] unless array != nil
       files = Array.new

data/lib/crate_api.rb

@@ -5,7 +5,28 @@ require "JSON"
   require File.join(File.dirname(__FILE__), "crate_api", inc)
 end
 
+# The CrateAPI Gem is a lightweight Ruby interface to the Crate file-sharing site.
+# @author Brian Michel
+# A few examples will follow in order to get everyone up to speed.
+#
+# @example Create a new Crate client.
+#   client = CrateAPI.new("username", "password")
+# 
+# @example Retreive all crates for a user.
+#   crates = client.crates.all
+#
+# @example Create a new crate.
+#   client.crate.add("YourNewAwesomeCrateName")
+# 
+# @example Upload a new file to a crate.
+#   crates[0].add_file("/Path/to/your/file")
+#
 module CrateAPI
+  # Default initializer for a new CrateAPI instace
+  #
+  # @param [String] Username for the client.
+  # @param [String] password Password for the client.
+  # @return [CrateAPI::Base] newly initialized CrateAPI::Base instace.
   def self.new(username, password)
     CrateAPI::Base.new(username, password)
   end

metadata

@@ -2,7 +2,7 @@
 name: crate_api
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - Brian Michel
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-23 00:00:00 Z
+date: 2011-04-24 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: shoulda
@@ -118,7 +118,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 1029907823158595725
+      hash: 4422052285909506318
       segments: 
       - 0
       version: "0"