jbgutierrez-delicious_api 1.0.0

data/README.textile

@@ -0,0 +1,136 @@
+h1. Delicious_api
+
+h2. Description
+
+delicious_api is a pure Ruby client for the "Delicious API":http://delicious.com/help/api. It provides an easy
+way to read/write bookmarks, tags and bundles to Delicious accounts.
+
+h2. Features
+
+* an object oriented design: @Bookmark@, @Tag@ and @Bundle@ classes
+* 100% covered by tests (check it for yourself!)
+* 100% documented
+* 100% Ruby 1.9 compatibility
+
+h2. Installation
+
+The following gems are required:
+
+<pre>
+sudo gem install activesupport hpricot
+</pre>
+
+and then you can (and should) get it as a gem:
+
+<pre>
+sudo gem install jbgutierrez-delicious_api --source http://gems.github.com
+</pre>
+
+h2. Basic Usage
+
+h3. Set up a DeliciousApi::Wrapper.
+
+<pre>
+DeliciousApi::Base.wrapper = DeliciousApi::Wrapper.new 'account', 'secret'
+</pre>
+
+Optionally, name your client (a.k.a. 'user agent') to something identifiable, such as your app's name.
+
+<pre>
+DeliciousApi::Base.wrapper = DeliciousApi::Wrapper.new 'account', 'secret', :user_agent => 'your-app-name'  
+</pre>
+
+In order not to get throttled, it will be a time gap of 1 second between each inner http request. Change this behaviour at your own risk:
+
+<pre>
+DeliciousApi::Base.wrapper = DeliciousApi::Wrapper.new 'account', 'secret', :waiting_time_gap => 0
+</pre>
+
+h3. Easy examples
+
+h4. Bookmarks retrieval
+
+<pre>
+bookmark = DeliciousApi::Bookmark.find 'http://www.yahoo.com/'
+bookmarks = DeliciousApi::Bookmark.find_by_date Date.now, :tags => %w[yahoo web search] 
+bookmarks = DeliciousApi::Bookmark.find_recent :tag => 'yahoo', :limit => 10
+bookmarks = DeliciousApi::Bookmark.find_all :tag => 'yahoo', :limit => 10
+bookmarks = DeliciousApi::Bookmark.find_all :start_time => 2.days.ago, :end_time => Time.now
+</pre>
+
+h4. Creating a new bookmark
+
+<pre>
+bookmark = DeliciousApi::Bookmark.new 'http://www.yahoo.com/'
+bookmark.save
+</pre>
+
+h4. Deleting a bookmark
+
+<pre>
+bookmark = DeliciousApi::Bookmark.find :url => 'http://www.yahoo.com/'
+bookmark.destroy
+</pre>
+
+h4. Updating a bookmark
+
+<pre>
+bookmark = DeliciousApi::Bookmark.find :url => 'http://www.yahoo.com/'
+
+bookmark.description = 'Yahoo!'
+bookmark.extended    = 'My favorite site ever'
+bookmark.tags        = %w[array of tags]
+
+bookmark.save  # returns false
+bookmark.save! # returns true
+</pre>
+
+h4. Copy Bookmarks between diferent accounts
+
+<pre>
+#!/usr/bin/env ruby -wKU
+require 'rubygems'
+require 'delicious_api'
+DeliciousApi::Base.wrapper = DeliciousApi::Wrapper.new 'source_account', 'secret'
+bookmarks = DeliciousApi::Bookmark.all
+DeliciousApi::Base.wrapper = DeliciousApi::Wrapper.new 'target_account', 'secret'
+bookmarks.each { |b| b.save }
+</pre>
+
+h2. Todo
+
+The following specs are pending:
+
+# should check to see when a user last posted an item. (PENDING: Not Yet Implemented)
+# should list dates on which bookmarks were posted (PENDING: Not Yet Implemented)
+# should fetch a change detection manifest of all items (PENDING: Not Yet Implemented)
+# should set User-Agent to something identifiable (PENDING: Not Yet Implemented)
+
+h2. Author
+
+"Javier Blanco Gutierrez":http://github.com/jbgutierrez
+
+h2. License
+
+See the terms of usage for the "Delicious API":http://delicious.com/help/api
+
+Copyright (c) 2009 by Javier Blanco Gutierrez under the MIT License
+
+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/delicious_api.gemspec

@@ -0,0 +1,31 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{delicious_api}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Javier Blanco Gutierrez"]
+  s.date = %q{2009-05-05}
+  s.default_executable = %q{delicious_api}
+  s.description = %q{delicious_api is a pure Ruby client for the "Delicious API" (http://delicious.com/help/api). It provides an easy
+  way to read/write bookmarks, tags and bundles to Delicious accounts.}
+  s.email = %q{jbgutierrez@gmail.com}
+  s.files = ["README.textile", "delicious_api.gemspec", "lib/delicious_api.rb", "lib/delicious_api/base.rb", "lib/delicious_api/bookmark.rb", "lib/delicious_api/bundle.rb", "lib/delicious_api/extensions.rb", "lib/delicious_api/extensions/hash.rb", "lib/delicious_api/tag.rb", "lib/delicious_api/wrapper.rb", "spec/custom_macros.rb", "spec/custom_matchers.rb", "spec/delicious_api_spec.rb", "spec/delicious_api_spec/base_spec.rb", "spec/delicious_api_spec/bookmark_spec.rb", "spec/delicious_api_spec/bundle_spec.rb", "spec/delicious_api_spec/tag_spec.rb", "spec/delicious_api_spec/wrapper_spec.rb", "spec/spec_helper.rb"]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/jbgutierrez/delicious_api}
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{delicious_api is a pure Ruby client for the "Delicious API" (http://delicious.com/help/api). It provides an easy
+  way to read/write bookmarks, tags and bundles to Delicious accounts.}
+  s.test_files = ["spec/delicious_api_spec.rb", "spec/delicious_api_spec/base_spec.rb", "spec/delicious_api_spec/bookmark_spec.rb", "spec/delicious_api_spec/bundle_spec.rb", "spec/delicious_api_spec/tag_spec.rb", "spec/delicious_api_spec/wrapper_spec.rb"]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    s.add_dependency('activesupport', '>= 2.3.2')
+    s.add_dependency('hpricot', '>= 0.8.1')
+    s.add_dependency('rspec', '>= 1.2.6')
+  end
+end

data/lib/delicious_api.rb

@@ -0,0 +1,54 @@
+
+module DeliciousApi
+
+  # Generic Delicious Api exception class.
+  class DeliciousApiError < StandardError; end
+
+  # :stopdoc:
+  NAME = 'DeliciousApi'
+  VERSION = '1.0.0'
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+  # :startdoc:
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    VERSION
+  end
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args )
+    args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args )
+    args.empty? ? PATH : ::File.join(PATH, args.flatten)
+  end
+
+  # Utility method used to require all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+        ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb}
+  end
+
+end  # module DeliciousApi
+
+require 'rubygems'
+DeliciousApi.require_all_libs_relative_to(__FILE__)
+
+# EOF

data/lib/delicious_api/base.rb

@@ -0,0 +1,67 @@
+module DeliciousApi
+
+  # Raised when the 'wrapper' has not been specified
+  class WrapperNotInitialized < DeliciousApiError; end
+
+  # Raised when you've trying to use the 'wrapper' with incorrect parameters.
+  class MissingAttributeError < DeliciousApiError; end
+
+  # Raised when something goes wrong at the 'wrapper'
+  class OperationFailed < DeliciousApiError; end
+
+  class Base
+
+    class << self
+
+      @@wrapper = nil
+
+      def wrapper=(wrapper) #:nodoc:
+        @@wrapper = wrapper
+      end
+
+      def wrapper #:nodoc:
+        raise WrapperNotInitialized, "Must initialize the 'wrapper' attribute first" if @@wrapper.nil?
+        @@wrapper
+      end
+
+    end
+
+    # Accepts an instance of a wrapper class, which will be used as a proxy of 
+    # the methods provided by the subclases.
+    # This attribute can be both set and retrieved both at class and instance level by calling +wrapper+.
+    attr_accessor :wrapper
+
+    def wrapper #:nodoc:
+      @wrapper || Base.wrapper
+    end
+
+    protected
+
+    # Assign the values of the Hash +params+ to the attributes of +self+ with the same key name 
+    def assign(params) #:nodoc:
+      params.each_pair do |key, value|
+        self.send("#{key}=", value) rescue self.instance_eval("@#{key}=value") rescue next
+      end
+    end
+
+    def self.before_assign(attribute, filter) #:nodoc:
+      alias_method "old_#{attribute}=", "#{attribute}="
+
+      module_eval <<-STR
+        def #{attribute}=(#{attribute})
+          self.old_#{attribute} = #{filter} #{attribute}
+        end
+      STR
+    end
+
+    def validate_presence_of(*attributes) #:nodoc:
+      missing_attributes = []
+      attributes.each do |attribute|
+        value = self.send(attribute)
+        missing_attributes << attribute if value.nil? || value.instance_of?(String) && value.empty?
+      end
+      raise(MissingAttributeError, "Missing required attribute(s): #{missing_attributes.join(", ")}") unless missing_attributes.empty?
+    end
+
+  end
+end

data/lib/delicious_api/bookmark.rb

@@ -0,0 +1,162 @@
+require File.dirname(__FILE__) + '/base'
+require 'time'
+
+module DeliciousApi
+  class Bookmark < Base
+
+    # The url of the bookmark
+    attr_accessor :href
+
+    # The description of the bookmark
+    attr_accessor :description
+
+    # Notes for the bookmark
+    attr_accessor :extended
+
+    # URL MD5
+    attr_reader :hash
+
+    # Change detection signature
+    attr_reader :meta
+
+    # TODO: Comment!!
+    attr_reader :others
+
+    # <tt>Array</tt> of tags for the bookmark
+    attr_accessor :tags
+
+    # A <tt>Time</tt> object determining the datestamp for the bookmark
+    attr_accessor :time
+
+    # A <tt>boolean</tt> determining whether the bookmark should be marked privated or shared
+    attr_accessor :shared
+
+    before_assign :tags, :filter_tags
+    before_assign :time, :filter_time
+
+    ##
+    # Bookmark initialize method
+    # ==== Parameters
+    # * <tt>href</tt> - The url of the bookmark
+    # * <tt>params</tt> - An optional <tt>Hash</tt> containing any combination of the instance attributes
+    # ==== Result
+    # An new instance of the current class
+    def initialize(href, params = {})
+      params.symbolize_keys!.assert_valid_keys(:href, :description, :extended, :hash, :meta, :others, :tags, :tag, :time, :shared)
+      params.reverse_merge!(:href => href, :tags => params[:tag], :shared => true)
+      assign params
+    end
+
+    # Saves the bookmark in del.icio.us
+    # ==== Parameters
+    # * <tt>replace</tt> - A <tt>boolean</tt> determining whether the bookmark should be replaced when it has already been posted
+    def save(replace=false)
+      validate_presence_of :href, :description
+      options = pack_save_options.merge(:replace => replace ? 'yes' : 'no' )
+      wrapper.add_bookmark(@href, @description, options)
+    end
+
+    # Saves the bookmark in Delicious. If it has already been posted, forces replacement 
+    # of the existing bookmark contents. (Same behaviour as save(true))
+    def save!
+      save(true) || raise(OperationFailed)
+    end
+
+    # Deletes the bookmark from Delicious
+    def destroy
+      validate_presence_of :href
+      wrapper.delete_bookmark @href || raise(OperationFailed)
+    end
+
+    # Retrieves an <tt>Array</tt> of suggested tag names from Delicious
+    def suggested_tags
+      validate_presence_of :href
+      wrapper.get_suggested_tags_for_url @href
+    end
+
+    # Returns one bookmark
+    def self.find(url)
+      Base.wrapper.get_bookmark_by_url(url)
+    end
+
+    ##
+    # Returns one or more bookmarks on a single day matching the arguments. If no date is given, most recent date will be used.
+    # ==== Parameters
+    # * <tt>options</tt> - A <tt>Hash</tt> containing any of the following:
+    #   - <tt>tags</tt>
+    #   - <tt>hashes</tt>
+    # ==== Result
+    # An <tt>Array</tt> of <tt>Bookmarks</tt> matching the criteria
+    def self.find_by_date(date, options = {})
+      options.assert_valid_keys(:tags, :hashes)
+      date = date.iso8601 unless date.nil?
+      Base.wrapper.get_bookmarks_by_date date, pack_find_options(options)
+    end
+
+    ##
+    # Returns a list of the most recent bookmarks, filtered by argument. Maximum 100.
+    # ==== Parameters
+    # * <tt>options</tt> - A <tt>Hash</tt> containing any of the following:
+    #   - <tt>limit</tt>
+    #   - <tt>tag</tt>
+    # ==== Result
+    # An <tt>Array</tt> of <tt>Bookmarks</tt> matching the criteria
+    def self.find_recent(options = {})
+      options.assert_valid_keys(:tag, :limit)
+      options.reverse_merge!(:limit => 10)
+      Base.wrapper.get_recent_bookmarks options
+    end
+
+    ##
+    # Returns a list with all the bookmarks, filtered by argument.
+    # ==== Parameters
+    # * <tt>options</tt> - A <tt>Hash</tt> containing any of the following:
+    #   - <tt>tag</tt>
+    #   - <tt>limit</tt>
+    #   - <tt>start_time</tt>
+    #   - <tt>end_time</tt>
+    # ==== Result
+    # An <tt>Array</tt> of <tt>Bookmarks</tt> matching the criteria
+    def self.find_all(options = {})
+      options.assert_valid_keys(:tag, :limit, :start_time, :end_time)
+      wrapper.get_all_bookmarks pack_all_options(options)
+    end
+
+    protected
+
+    def filter_tags(tags) #:nodoc:
+      tags.instance_of?(String) ? tags.split : tags
+    end
+
+    def filter_time(time) #:nodoc:
+      time.instance_of?(String) ? Time.xmlschema(time) : time
+    end
+
+    def pack_save_options #:nodoc:
+      opt = {}
+      opt[:tags]     = @tags.nil? ? '' : @tags.join(' ')
+      opt[:extended] = @extended               unless @extended.nil?
+      opt[:dt]       = @time.iso8601           unless @time.nil?
+      opt[:shared]   = @shared ? 'yes' : 'no'  unless @shared.nil?
+      opt
+    end
+
+    def self.pack_find_options(options) #:nodoc:
+      opt = {}
+      opt[:tag]    = options[:tags].join(' ')      unless options[:tags].nil?
+      opt[:hashes] = options[:hashes].join(' ')    unless options[:hashes].nil?
+      opt[:meta]   = 'yes'
+      opt
+    end
+
+    def self.pack_all_options(options) #:nodoc:
+      opt = {}
+      opt[:tag]    = options[:tag]                  unless options[:tag].nil?
+      opt[:limit]  = options[:limit]                unless options[:limit].nil?
+      opt[:fromdt] = options[:start_time].iso8601   unless options[:start_time].nil?
+      opt[:todt]   = options[:end_time].iso8601     unless options[:end_time].nil?
+      opt
+    end
+
+  end
+end