rubycious 0.1.0 → 0.1.2

data/LICENSE.rdoc

@@ -0,0 +1,23 @@
+=Copyright (c) <2010> <Ratan Sebastian>
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+  copy, modify, merge, publish, distribute, sublicense, and/or sell
+  copies of the Software, and to permit persons to whom the
+  Software is furnished to do so, subject to the following
+  conditions:
+
+  The above copyright notice and this permission notice shall be
+  included in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+  OTHER DEALINGS IN THE SOFTWARE.
+

data/Manifest

@@ -1,6 +1,9 @@
-Manifest
+LICENSE.rdoc
 README.rdoc
 Rakefile
-config/auth.yml
+lib/client.rb
 lib/client_helper.rb
+lib/errors.rb
 lib/rubycious.rb
+rubycious.gemspec
+Manifest

data/README.rdoc

@@ -1,3 +1,16 @@
 = Rubycious
 
 A Ruby gem wrapper to the del.icio.us API. nuff' said.
+
+== Examples
+
+  require 'rubycious'
+  include Rubycious
+
+  post_client= Client::Post.new(:username => "delicious_username", :password => "delicious_password")
+  post_client.all(:tag => "testing")
+  post_client.recent
+  post_client.get(:tag => "tutorial+ruby")
+
+  tag_client= Rubycious::Client::Tag.new(:username => "delicious_username", :password => "delicious_password")
+  tag_client.all

data/Rakefile

@@ -2,13 +2,13 @@ require 'rubygems'
 require 'rake'  
 require 'echoe'  
 
-Echoe.new('rubycious', '0.1.0') do |p|  
+Echoe.new('rubycious', '0.1.2') do |p|  
   p.description     = "Ruby wrapper to the del.icio.us API"  
-  p.url             = "http://github.com/rjsvlajean/rubycious"  
+  p.url             = "http://github.com/rjsvaljean/rubycious"  
   p.author          = "Ratan Sebastian"  
   p.email           = "rjsvaljean@gmail.com"  
   p.ignore_pattern  = ["tmp/*", "script/*"]  
-  p.development_dependencies = []
+  p.development_dependencies = ["httparty"]
 end  
 
 Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each { |ext| load ext }  

data/lib/client.rb

@@ -0,0 +1,168 @@
+# @author Ratan Sebastian
+# The Client module contains the Client classes Post, Tag and Bundle
+module Rubycious::Client
+
+  
+  # The Post Client class that is used to make post related requests
+  class Post
+    include ClientHelper
+
+    base_uri "#{base_uri}/posts"
+
+    # Get the time of the last request
+    # @return [Time] Returns the time of the last request in UTC
+    def self.last_update
+      response= self.new.handle_errors do
+        get('/update')
+      end
+      Time.parse(response["update"]["time"])
+    end
+
+    # Save a URL
+    # DO NOT call this method directly. To create a new URL call Rubycious::Post#save
+    # @param [Hash] options for creating the URL with
+    # @option options [String] :url  |required| http://somelink.com/somepage
+    # @option options [String] :description  |required| This is a really cool link
+    # @option options [String] :dt  |optional| Format: Time#iso8601 filter by date
+    # @option options [String] :hash  |optional| MD5+MD5+....+MD5  Fetch multiple 
+    #                       bookmarks by one or more URL MD5s regardless of date, 
+    #                       separated by URL-encoded spaces (ie. '+').
+    # @option options [String] :extended  |optional| This is some further information
+    # @option options [String] :tags  |optional| space separated list of tags
+    # @option options [String] :replace  |optional| yes/no Replace URL if already exists
+    # @option options [String] :shared  |optional| yes/no Public/Private
+    # @private
+    # @see Rubycious::Post#save
+    def save(options = {})
+      handle_errors { self.class.get('/add', :query => options) }
+    end
+  
+    # Use for getting one or more URLs on a single day matching the arguments
+    # @param [Hash] options for searching for the URL (all optional)
+    # @option options [String] :tag  "ruby+rails+httparty"
+    # @option options [String] :dt  CCYY-MM-DDThh:mm:ssZ Time#iso8601
+    # @option options [String] :url  URL
+    # @option options [String] :hashes  "c0...d+2f970...fe+..+2f...9fe"
+    # @option options [String] :meta  yes/no whether or not to get the meta hash tag
+    # @return [Array<Rubycious::Post>, Rubycious::Post] 
+    # @see Time#iso8601
+    def get(options = {})
+      response= handle_errors { self.class.get('/get', :query => options)}
+      if response["posts"]["post"].is_a?(Hash)
+        Rubycious::Post.new response["posts"]["post"]
+      elsif response["posts"]["post"].is_a?(Array)
+        response["posts"]["post"].collect{|i| Rubycious::Post.new(i)}
+      else
+        nil
+      end
+    end
+
+    # Use for searching all URLs
+    # NOTE: Use Sparingly. Call the update function to see if you need to fetch this at all.
+    # @todo Look into caching these results
+    #       check the last update time before performing
+    # @param [Hash] options for searching for the URL (all optional)
+    # @option options [String] :tag |optional|  "ruby"
+    # @option options [String] :start |optional|  Integer: Start returning posts this 
+    #                                 many results into the set
+    # @option options [String] :results |optional|  Integer: Return these many results 
+    # @option options [String] :fromdt |optional|  Format: Time#iso8601: On this date or later
+    # @option options [String] :todt |optional|  Format: Time#iso8601: On this date or earlier
+    # @option options [String] :meta |optional|  yes/no: Include change detection signatures
+    #                     on each item in a 'meta' attribute. Clients wishing to maintain a 
+    #                     synchronized local store of bookmarks should retain the 
+    #                     value of this attribute - its value will change when any 
+    #                     significant field of the bookmark changes.
+    # @return [Array<Rubycious::Post>]
+    # @see Time#iso8601
+    def all(options = {})
+      response= handle_errors { self.class.get('/all', :query => options)}
+      response["posts"]["post"].collect{|i| Rubycious::Post.new(i)}
+    end
+
+    # Use to get recent URLs
+    # @param [Hash] options to filter recent URLs(all optional)
+    # @option options [String] :tag |optional| "httparty"
+    # @option options [String] :count (15) |optional| Default: 15 Max: 100 
+    # @return [Array<Rubycious::Post>] 
+    def recent(options = {})
+      response= handle_errors { self.class.get('/recent', :query => options)}
+      response["posts"]["post"].collect{|i| Rubycious::Post.new(i)}
+    end
+
+    # Use to get a list of dates and number of posts on that date
+    # @param [Hash] options to filter URLs(all optional)
+    # @option options [String] :tag |optional| "tutorial"
+    # @return [Array<Rubycious::PostDate>] 
+    def dates(options = {})
+      response= handle_errors{ self.class.get('/dates', :query => options)}
+      response["dates"]["date"].collect{|i| Rubycious::PostDate.new(i)}
+    end
+
+    # Use to get a list of Suggested tags for a URL
+    # @param [Hash] options containing the URL
+    # @option options [String] :url =|required| URL
+    # @return [Hash] 
+    # @example Sample returned hash:
+    #     Rubycious::Client::Post.suggest("http://google.com")
+    #     #=> {"recommended"=>["search", "google", "web", "reference", 
+    #                     "internet", "tools", "research", "imported", 
+    #                     "news", "images", "resources"], 
+    #     "popular"=>["search", "google", "searchengine", "engine"],
+    #     "network"=>["google", "searchengineo"]}
+
+    def suggest(options = {})
+      response= handle_errors{ self.class.get('/suggest', :query => options)}
+      response["suggest"]
+    end
+  end
+
+  # The Rubycious::Client::Tag class handles all requests, tag related
+  class Tag
+    include ClientHelper
+
+    base_uri "#{base_uri}/tags"
+
+    # Use to get all tags
+    # @return [Array<Rubycious::Tag>] 
+    def all
+      response= handle_errors{ self.class.get('/get')}
+      response["tags"]["tag"].collect do |tag| 
+        t= Rubycious::Tag.new(tag)
+      end
+    end
+
+    # @param [Hash] options to identify the tag to delete
+    # @option options [String] :tag |required|
+    # @return [TrueClass, FalseClass]
+    def delete(options)
+      response= handle_errors{ self.class.get('/delete', :query => options)}
+      if response["result"] == "done"
+        true
+      else
+        false
+      end
+    end
+
+    # @param [Hash] options of the old and the new name for a tag
+    # @option options [String] :old |required|
+    # @option options [String] :new |required|
+    # @return [TrueClass, FalseClass]
+    def rename(options)
+      response= handle_errors{ self.class.get('/rename', :query => options)}
+      if response["result"] == "done"
+        true
+      else
+        false
+      end
+    end
+  end
+
+  # Will Implement the bundles part of the API when done
+  # @todo To Be Implemented
+  class Bundles
+    include ClientHelper
+
+    base_uri "#{base_uri}/tags/bundles"
+  end
+end

data/lib/errors.rb

@@ -0,0 +1,27 @@
+module Rubycious::Errors
+
+  # Raised whenever there is some sort of failure on the remote end
+  class DeliciousError < StandardError
+  end
+
+  # Raised when del.icio.us returns an access denied
+  class AuthenticationError < StandardError
+  end
+
+  # surrounds all HTTParty#get calls to check for failure or throttling by del.icio.us
+  # @yield The block contains and network calls to the del.icio.us API
+  # @todo Make more stringent and give better error messages
+  # @raise [DeliciousError]
+  def handle_errors
+    response= yield
+    if response.keys.include?("result")
+      if response["result"].match("done")
+        response
+      else
+        raise DeliciousError, response["result"]["code"]
+      end
+    else
+      response
+    end
+  end
+end

data/lib/rubycious.rb

@@ -1,171 +1,53 @@
 require 'httparty'
 
 ROOT_DIR= File.join(File.dirname(__FILE__),'..')
-# load File.join(ROOT_DIR, 'lib', 'errors.rb')
-load File.join(ROOT_DIR, 'lib', 'client_helper.rb')
-# load File.join(ROOT_DIR, 'lib', 'client.rb')
 
 module Rubycious
-
-
-  module Errors
-
-    class DeliciousError < StandardError
-    end
-
-    class AuthenticationError < StandardError
-    end
-
-    def handle_errors
-      response= yield
-      if response.keys.include?("result")
-        if response["result"].match("done")
-          response
-        else
-          raise DeliciousError, response["result"]["code"]
-        end
-      else
-        response
-      end
-    end
-  end
-
-  module Client
-    def self.last_update
-      response= self.new.handle_errors do
-        get('/posts/update')
-      end
-      Time.parse(response["update"]["time"])
-    end
-
-    class Post
-      include ClientHelper
-
-      base_uri "#{base_uri}/posts"
-
-      # Options
-      # :url => (required) http://somelink.com/somepage
-      # :description => (required) This is a really cool link that I found
-      # :dt => (optional) CCYY-MM-DDThh:mm:ssZ filter by date
-      # :hash => (optional) MD5+MD5+....+MD5  Fetch multiple bookmarks by one or more URL MD5s regardless of date, separated by URL-encoded spaces (ie. '+').
-      # :extended => (optional) This is some further information about the link
-      # :tags => (optional) space seporated list of tags
-      # :replace => (optional) yes/no
-      # :shared => (optional) yes/no
-      def save
-        handle_errors { self.class.get('/add', :query => @options) }
-      end
-
-      # Options:
-      # :tag => "ruby+rails+httparty"
-      # :dt => CCYY-MM-DDThh:mm:ssZ
-      # :url => URL
-      # :hashes => "c0238dc0c44f07daedd9a1fd9bbdeebd+2f9704c729e7ed3b41647b7d0ad649fe+..+2f9704c729e7ed3b41647b7d0ad649fe"
-      # :meta => yes/no to indicate whether or not to retreive the meta hash tag
-      # METHOD DEPRECATED due to uselessness
-      def find_latest(options)
-        response= handle_errors { self.class.get('/get', :query => options)}
-        response["posts"]
-      end
-
-      # Options:
-      # :tag =>(optional)  "ruby"
-      # :start =>(optional)  Integer: Start returning posts this many results into the set
-      # :results =>(optional)  Integer: Return these many results 
-      # :fromdt =>(optional)  {Time#iso8601}: On this date or later
-      # :todt =>(optional)  {Time#iso8601}: On this date or earlier
-      # :meta =>(optional)  yes/no: Include change detection signatures on each item in a 'meta' attribute. Clients wishing to maintain a synchronized local store of bookmarks should retain the value of this attribute - its value will change when any significant field of the bookmark changes.
-      # NOTE: Use Sparingly. Call the update function to see if you need to fetch this at all.
-      def find(options)
-        response= handle_errors { self.class.get('/all', :query => options)}
-        response["posts"]["post"].collect{|i| Rubycious::Post.new(i)}
-      end
-
-      # Options:
-      # :tag => (optional) "httparty"
-      # :count => (optional) Integer // Default: 15 Max: 100 
-      def recent(options = nil)
-        response= handle_errors { self.class.get('/recent', :query => options)}
-        response["posts"]["post"].collect{|i| Rubycious::Post.new(i)}
-      end
-
-      # Options:
-      # :tag => (optional) "tutorial"
-      def dates(options = nil)
-        response= handle_errors{ self.class.get('/dates', :query => options)}
-        response["dates"]["date"].collect{|i| Rubycious::PostDate.new(i)}
-      end
-
-      # Options:
-      # :url => (required) URL
-      def suggest(options)
-        response= handle_errors{ self.class.get('/suggest', :query => options)}
-        response["suggest"]
-      end
-    end
-
-    class Tag
-      include ClientHelper
-
-      base_uri "#{base_uri}/tags"
-
-      def all
-        response= handle_errors{ self.class.get('/get')}
-        response["tags"]["tag"].collect do |tag| 
-          t= Rubycious::Tag.new(tag)
-        end
-      end
-      #Options:
-      # :tag => (required)
-      def delete(options)
-        response= handle_errors{ self.class.get('/delete', :query => options)}
-        true if response["result"] == "done"
-      end
-      
-      #Options:
-      # :old => (required)
-      # :new => (required)
-      def rename(options)
-        response= handle_errors{ self.class.get('/rename', :query => options)}
-        true if response["result"] == "done"
-      end
-    end
-
-    class Bundles
-      include ClientHelper
-
-      base_uri "#{base_uri}/tags/bundles"
-    end
-  end
-
+  # This is type for calls to Rubycious::Client::Post#dates
   class PostDate
-    # Attributes:
-    # date: Date
-    # count: Integer
 
-    attr_accessor :date, :count
+    # @return [Date]
+    attr_accessor :date
+    # @return [Integer]
+    attr_accessor :count
 
+    # @param [Hash] options to create the PostDate
+    # @option options [String] Format: "yyyy-mm-dd"
+    # @option options [String] Integer as a string
     def initialize(options)
       @date= Date.parse(options["date"])
       @count= options["count"].to_i
     end
   end
 
+  # This is the class that will model an URL returned by the API
   class Post
-    # Attributes
-    # :href => (required) http://somelink.com/somepage
-    # :description => (required) This is a really cool link that I found
-    # :time => (optional) CCYY-MM-DDThh:mm:ssZ filter by date
-    # :hash => (optional) (only for find) MD5+MD5+....+MD5  Fetch multiple bookmarks by one or more URL MD5s regardless of date, separated by URL-encoded spaces (ie. '+').
-    # :extended => (optional) This is some further information about the link
-    # :tag => (optional) space seporated list of tags
-    # :meta => (optional) meta hash
 
+    # The methods [:href, :description, :time, :hash, :extended, :tag, :meta]
+    # can be called on a Post object
+    # @param [Hash] options to create the Post
+    # @option options [String] :href |required for #save| http://somelink.com/somepage
+    # @option options [String] :description |required for #save| This is a really cool link that I found
+    # @option options [String] :time  |optional| CCYY-MM-DDThh:mm:ssZ filter by date
+    # @option options [String] :hash  |optional| (only for find) MD5+MD5+....+MD5  
+    #                                Fetch multiple bookmarks by one or more URL MD5s 
+    #                                regardless of date, separated by URL-encoded spaces (ie. '+').
+    # @option options [String] :extended  |optional| This is some further information about the link
+    # @option options [String] :tag  |optional| space seporated list of tags
+    # @option options [String] :meta  |optional| meta hash
     def initialize(params = nil)
       @params= params
       @attributes= [:href, :description, :time, :hash, :extended, :tag, :meta]
     end
 
+    # Use to create a new URL
+    # @todo check for url and description before saving and raise errors
+    def save
+      Rubycious::Client::Post.new.save(@params)
+    end
+
+    # The methods [:href, :description, :time, :hash, :extended, :tag, :meta]
+    # can be called on a Post object
     def method_missing(name, *args, &block)
       if @attributes.include?(name)
         if name == :time
@@ -179,22 +61,36 @@ module Rubycious
     end
   end
 
+  # Models Tags returned by the API
   class Tag
-    attr_accessor :name, :count
-    
+
+    # @return [String] name of the tag
+    # @return [Integer] number of times the tag has been used
+    attr_accessor :name
+    attr_accessor :count
+   
+    # @param [Hash] options for creating the Tag
+    # @option options [String] "tag" |required| The name of the tag
+    # @option options [String] "count" |optional| The number of times the tag has been used
     def initialize(options = {"tag" => nil})
       @name=  options["tag"]
-      @count= options["count"]
+      @count= options["count"].to_i
+      @client= Rubycious::Client::Tag.new
     end
 
+    # @return [TrueClass, FalseClass]
     def delete
-      client= Rubycious::Client::Tag.new
       client.delete(:tag => @name)
     end
 
+    # @param [String] The new name of the tag
+    # @return [TrueClass, FalseClass]
     def rename(new_name)
-      client= Rubycious::Client::Tag.new
       client.rename(:old => @name, :new => new_name)
     end
   end
 end
+
+load File.join(ROOT_DIR, 'lib', 'errors.rb')
+load File.join(ROOT_DIR, 'lib', 'client_helper.rb')
+load File.join(ROOT_DIR, 'lib', 'client.rb')

data/rubycious.gemspec

@@ -2,29 +2,32 @@
 
 Gem::Specification.new do |s|
   s.name = %q{rubycious}
-  s.version = "0.1.0"
+  s.version = "0.1.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Ratan Sebastian"]
-  s.date = %q{2010-05-12}
+  s.date = %q{2010-06-15}
   s.description = %q{Ruby wrapper to the del.icio.us API}
   s.email = %q{rjsvaljean@gmail.com}
-  s.extra_rdoc_files = ["README.rdoc", "lib/client_helper.rb", "lib/rubycious.rb"]
-  s.files = ["Manifest", "README.rdoc", "Rakefile", "config/auth.yml", "lib/client_helper.rb", "lib/rubycious.rb", "rubycious.gemspec"]
-  s.homepage = %q{http://github.com/rjsvlajean/rubycious}
+  s.extra_rdoc_files = ["LICENSE.rdoc", "README.rdoc", "lib/client.rb", "lib/client_helper.rb", "lib/errors.rb", "lib/rubycious.rb"]
+  s.files = ["LICENSE.rdoc", "README.rdoc", "Rakefile", "lib/client.rb", "lib/client_helper.rb", "lib/errors.rb", "lib/rubycious.rb", "rubycious.gemspec", "Manifest"]
+  s.homepage = %q{http://github.com/rjsvaljean/rubycious}
   s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Rubycious", "--main", "README.rdoc"]
   s.require_paths = ["lib"]
   s.rubyforge_project = %q{rubycious}
-  s.rubygems_version = %q{1.3.5}
+  s.rubygems_version = %q{1.3.7}
   s.summary = %q{Ruby wrapper to the del.icio.us API}
 
   if s.respond_to? :specification_version then
     current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<httparty>, [">= 0"])
     else
+      s.add_dependency(%q<httparty>, [">= 0"])
     end
   else
+    s.add_dependency(%q<httparty>, [">= 0"])
   end
 end

metadata

@@ -1,7 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rubycious
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  hash: 31
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 2
+  version: 0.1.2
 platform: ruby
 authors: 
 - Ratan Sebastian
@@ -9,10 +15,23 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-12 00:00:00 +05:30
+date: 2010-06-15 00:00:00 +05:30
 default_executable: 
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: httparty
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
 description: Ruby wrapper to the del.icio.us API
 email: rjsvaljean@gmail.com
 executables: []
@@ -20,19 +39,24 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
+- LICENSE.rdoc
 - README.rdoc
+- lib/client.rb
 - lib/client_helper.rb
+- lib/errors.rb
 - lib/rubycious.rb
 files: 
-- Manifest
+- LICENSE.rdoc
 - README.rdoc
 - Rakefile
-- config/auth.yml
+- lib/client.rb
 - lib/client_helper.rb
+- lib/errors.rb
 - lib/rubycious.rb
 - rubycious.gemspec
+- Manifest
 has_rdoc: true
-homepage: http://github.com/rjsvlajean/rubycious
+homepage: http://github.com/rjsvaljean/rubycious
 licenses: []
 
 post_install_message: 
@@ -46,21 +70,28 @@ rdoc_options:
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 11
+      segments: 
+      - 1
+      - 2
       version: "1.2"
-  version: 
 requirements: []
 
 rubyforge_project: rubycious
-rubygems_version: 1.3.5
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: Ruby wrapper to the del.icio.us API

data/config/auth.yml

@@ -1,2 +0,0 @@
-username: arjayes
-password: ./haq764