lgs-www-delicious 0.2.1

data/CHANGELOG.rdoc

@@ -0,0 +1,52 @@
+= Changelog
+
+
+== development
+
+* FIXED: Compatibility fixes for Ruby 1.9. WWW::Delicious is now 100% compatible with 1.9. You should remember to define the proper content encoding with magic comments when working with UTF-8/MultiByte XML or Ruby files, see http://redmine.ruby-lang.org/wiki/ruby-19/ScriptEncoding (closes #142).
+
+* CHANGED: Don't use File.dirname(__FILE__) in require statement to prevent recursive inclusions.
+
+== Release 0.2.1 by Luca G.Soave
+
+* ADDED: plugin install ability : ruby ./script/plugin install git://github.com/lgs/www-delicious.git 
+* FIXED: Error installing ideaoforder-www-delicious gem : ideaoforder-www-delicious requires RubyGems version = 1.2
+
+== Release 0.2.0
+
+* ADDED: :base_uri initialization option allows to create a new instance specifying a custom base_uri for all API calls. This is useful, for example, if you want to use ma.gno.lia Mirror'd APIs (http://wiki.ma.gnolia.com/Mirror%27d_API) instead the del.icio.us one (thanks to Jörg Battermann).
+
+* ADDED: two new REXML::Element core extension elements to enhance interaction with node elements.
+
+* FIXED: a wrong indentation in README file causes all list items to be rendered as source code.
+
+* FIXED: Missing WWW::Delicious::Bundle#to_s method causes a class ID representation to be returned.
+
+* FIXED: Missing unit tests for post_ calls (closes #18).
+
+* FIXED: Added test for `shared` Post attribute and fixed an issue with duplicate `replace` method definition (closes #11).
+
+* CHANGED: improved documentation and added more examples (closes #21).
+
+* CHANGED: REXML::Element#attribute_value core extension has been renamed to REXML::Element#if_attribute_value.
+
+* CHANGED: Renamed TESTCASE_PATH to TESTCASES_PATH.
+
+* CHANGED: WWW::Delicious::Tag, WWW::Delicious::Bundle, WWW::Delicious::Post now extend WWW::Delicious::Element. Simplified classes.
+
+* CHANGED: WWW::Delicious::Tag#to_s always returns a string even if name is nil.
+
+* CHANGED: WWW::Delicious::Tag :count attribute is now stored and returned as Fixnum instead of String.
+
+* CHANGED: Unit test reorganization (closes #22).
+
+* CHANGED: Simplified and tidyfied test system with Mocha (closes #19).
+
+* CHANGED: Various internal API methods have been renamed for coherence with their new scope.
+
+* CHANGED: Integrated Echoe, cleaned Rakefile (closes #23).
+
+
+== Release 0.1.0 (2008-05-11)
+
+* Initial public release.

data/LICENSE.rdoc

@@ -0,0 +1,25 @@
+= License
+
+(The MIT License)
+
+Copyright (c) 2008 Simone Carletti <weppos@weppos.net>
+
+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

@@ -0,0 +1,48 @@
+lib/www/delicious/bundle.rb
+lib/www/delicious/tag.rb
+lib/www/delicious/element.rb
+lib/www/delicious/version.rb
+lib/www/delicious/post.rb
+lib/www/delicious/errors.rb
+lib/www/delicious.rb
+test/post_test.rb
+test/test_all.rb
+test/fixtures/net_response_success.yml
+test/fixtures/net_response_invalid_account.yml
+test/delicious_test.rb
+test/online_test.rb
+test/test_helper.rb
+test/bundle_test.rb
+test/tag_test.rb
+test/testcases/response/posts_get_with_tag.xml
+test/testcases/response/tags_get_empty.xml
+test/testcases/response/update.xml
+test/testcases/response/bundles_set.xml
+test/testcases/response/bundles_delete.xml
+test/testcases/response/posts_get.xml
+test/testcases/response/posts_add.xml
+test/testcases/response/bundles_set_error.xml
+test/testcases/response/posts_all.xml
+test/testcases/response/posts_dates_with_tag.xml
+test/testcases/response/posts_dates.xml
+test/testcases/response/bundles_all.xml
+test/testcases/response/posts_delete.xml
+test/testcases/response/posts_recent_with_tag.xml
+test/testcases/response/tags_get.xml
+test/testcases/response/bundles_all_empty.xml
+test/testcases/response/posts_recent.xml
+test/testcases/response/update.delicious1.xml
+test/testcases/response/tags_rename.xml
+test/testcases/element/invalid_root.xml
+test/testcases/element/tag.xml
+test/testcases/element/post.xml
+test/testcases/element/bundle.xml
+test/testcases/element/post_unshared.xml
+Manifest
+Rakefile
+LICENSE.rdoc
+CHANGELOG.rdoc
+www-delicious.gemspec
+setup.rb
+README.rdoc
+init.rb

data/README.rdoc

@@ -0,0 +1,206 @@
+= WWW::Delicious
+
+WWW::Delicious is a Ruby client for http://del.icio.us XML API.
+
+It provides both read and write functionality. You can read user Posts, Tags
+and Bundles but you can create new Posts, Tags and Bundles as well.
+
+
+== Overview
+
+WWW::Delicious maps all the original del.icio.us API calls and provides some
+additional convenient methods to perform common tasks.
+Please read the official documentation (http://del.icio.us/help/api/)
+to learn more about del.icio.us API.
+
+WWW::Delicious is 100% compatible with all del.icio.us API constraints,
+including the requirement to set a valid user agent or wait at least
+one second between queries.
+Basically, the main benefit from using this library is that you don't need
+to take care of all these low level details, if you don't want:
+WWW::Delicious will try to give you the most with less efforts.
+
+
+== Dependencies
+
+* Ruby >= 1.8.6 (not tested with previous versions)
+
+
+== Download and Installation
+
+RubyGems[http://rubyforge.org/projects/rubygems/] is the preferred install method.
+To get the latest version, simply type the following instruction into your command prompt:
+
+  $ sudo gem install www-delicious
+  
+Depending on your system, you might need su privileges.
+
+To install the library manually, downlad the latest version from 
+navigate to the root library directory and enter:
+
+  $ sudo ruby setup.rb
+
+If you need the latest development version you can download the source code
+from one of the GIT repositories listed above.
+Beware that the code might not be as stable as the official release.
+
+== Plugin installation on Rails
+
+Since the version 0.2.1 WWW::Delicious can be installed via plugin,
+running the following command :
+
+  $ ruby ./script/plugin install git://github.com/lgs/www-delicious.git
+
+== Getting Started
+
+In order to use this library you need a valid del.icio.us account.
+Go to http://del.icio.us/ and register for a new account if you don't already have one.
+
+Then create a valid instance of WWW::Delicious providing your account credentials.
+
+  require 'www/delicious'
+  
+  # create a new instance with given username and password
+  d = WWW::Delicious.new('username', 'password')
+  
+Now you can use your instance to interact with the API interface.
+
+
+=== Last account update
+
+The following example show you how to get the last account update Time.
+
+  require 'www/delicious'
+  d = WWW::Delicious.new('username', 'password')
+  
+  time = d.update # => Fri May 02 18:02:48 UTC 2008
+
+
+=== Reading Posts
+
+You can fetch your posts in 3 different ways:
+
+  require 'www/delicious'
+  d = WWW::Delicious.new('username', 'password')
+
+  # 1. get all posts
+  posts = d.posts_all
+  
+  # 2. get recent posts
+  posts = d.posts_recent
+  
+  # 3. get a single post (the latest one if no criteria is given)
+  posts = d.posts_get(:tag => 'ruby')
+
+Each post call accepts some options to refine your search.
+For example, you can always search for posts matching a specific tag.
+
+  posts = d.posts_all(:tag => 'ruby')
+  posts = d.posts_recent(:tag => 'ruby')
+  posts = d.posts_get(:tag => 'ruby')
+
+
+=== Creating a new Post
+
+  require 'www/delicious'
+  d = WWW::Delicious.new('username', 'password')
+  
+  # add a post from options
+  d.posts_add(:url => 'http://www.simonecarletti.com/', :title => 'Cool site!')
+  
+  # add a post from WWW::Delicious::Post
+  d.posts_add(WWW::Delicious::Post.new(:url => 'http://www.simonecarletti.com/', :title => 'Cool site!'))
+
+
+=== Deleting a Posts
+
+  require 'www/delicious'
+  d = WWW::Delicious.new('username', 'password')
+  
+  # delete given post (the URL can be either a string or an URI)
+  d.posts_delete('http://www.foobar.com/')
+
+Note. Actually you cannot delete a post from a WWW::Delicious::Post instance.
+It means, the following example doesn't work as some ActiveRecord user might expect.
+
+  post = WWW::Delicious::Post.new(:url => 'http://www.foobar.com/')
+  post.delete
+
+This feature is already in the TODO list. For now, use the following workaround
+to delete a given Post.
+
+  # delete a post from an existing post = WWW::Delicious::Post
+  d.posts_delete(post.url)
+
+
+=== Tags
+
+Working with tags it's really easy. You can get all your tags or rename an existing tag.
+
+  require 'www/delicious'
+  d = WWW::Delicious.new('username', 'password')
+  
+  # get all tags
+  tags = d.tags_get
+  
+  # print all tag names
+  tags.each { |t| puts t.name }
+  
+  # rename the tag gems to gem
+  d.tags_rename('gems', 'gem')
+
+
+=== Bundles
+
+WWW::Delicious enables you to get all bundles from given account.
+
+  require 'www/delicious'
+  d = WWW::Delicious.new('username', 'password')
+  
+  # get all bundles
+  bundles = d.bundles_all
+  
+  # print all bundle names
+  bundles.each { |b| puts b.name } 
+
+You can also create new bundles or delete existing ones.
+
+  require 'www/delicious'
+  d = WWW::Delicious.new('username', 'password')
+  
+  # set a new bundle for tags ruby, rails and gem
+  d.bundles_set('MyBundle', %w(ruby rails gem))
+  
+  # delete the old bundle
+  d.bundles_delete('OldBundle')
+
+
+== Author
+
+{Simone Carletti}[http://www.simonecarletti.com/] <weppos@weppos.net>
+
+
+== Resources
+
+* {Homepage}[http://code.simonecarletti.com/www-delicious]
+* {API}[http://www-delicious.rubyforge.org/]
+* {GitHub}[http://github.com/weppos/www-delicious/]
+* {RubyForge}[http://rubyforge.org/projects/www-delicious/]
+
+
+== FeedBack and Bug reports
+
+Feel free to email {Simone Carletti}[mailto:weppos@weppos.net] with any questions or feedback.
+
+Please use the {Ticket System}[http://code.simonecarletti.com/projects/show/www-delicious] to submit bug reports or feature request.
+
+
+== Changelog
+
+See the CHANGELOG.rdoc file for details.
+
+
+== License
+
+Copyright (c) 2008 Simone Carletti, WWW::Delicious is released under the MIT license. 
+

data/Rakefile

@@ -0,0 +1,55 @@
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+$:.unshift(File.dirname(__FILE__) + "/lib")
+require 'www/delicious'
+
+
+# Common package properties
+PKG_NAME    = ENV['PKG_NAME'] || WWW::Delicious::GEM
+PKG_VERSION = ENV['PKG_VERSION'] || WWW::Delicious::VERSION
+PKG_SUMMARY = "Ruby client for del.icio.us API."
+PKG_FILES = FileList.new("{lib,test}/**/*.rb") do |files|
+  files.include %w(README.rdoc CHANGELOG.rdoc LICENSE.rdoc)
+  files.include %w(Rakefile setup.rb)
+end
+RUBYFORGE_PROJECT = 'www-delicious'
+ 
+if ENV['SNAPSHOT'].to_i == 1
+  PKG_VERSION << "." << Time.now.utc.strftime("%Y%m%d%H%M%S")
+end
+ 
+ 
+Echoe.new(PKG_NAME, PKG_VERSION) do |p|
+  p.author        = "Simone Carletti"
+  p.email         = "weppos@weppos.net"
+  p.summary       = PKG_SUMMARY
+  p.description   = <<-EOF
+    WWW::Delicious is a del.icio.us API client implemented in Ruby. \
+    It provides access to all available del.icio.us API queries \
+    and returns the original XML response as a friendly Ruby object.
+  EOF
+  p.url           = "http://code.simonecarletti.com/www-delicious"
+  p.project       = RUBYFORGE_PROJECT
+
+  p.need_zip      = true
+  p.rcov_options  = ["--main << README.rdoc -x Rakefile -x mocha -x rcov"]
+  p.rdoc_pattern  = /^(lib|CHANGELOG.rdoc|README.rdoc)/
+
+  p.development_dependencies += ["rake  >=0.8",
+                                 "echoe >=3.0",
+                                 "mocha >=0.9"]
+end
+
+
+begin
+  require 'code_statistics'
+  desc "Show library's code statistics"
+  task :stats do
+    CodeStatistics.new(["WWW::Delicious", "lib"],
+                       ["Tests", "test"]).to_s
+  end
+rescue LoadError
+  puts "CodeStatistics (Rails) is not available"
+end

data/init.rb

@@ -0,0 +1 @@
+require 'www/delicious'

data/lib/www/delicious.rb

@@ -0,0 +1,942 @@
+# 
+# = WWW::Delicious
+#
+# Ruby client for del.icio.us API.
+# 
+#
+# Category::    WWW
+# Package::     WWW::Delicious
+# Author::      Simone Carletti <weppos@weppos.net>
+# License::     MIT License
+#
+#--
+# SVN: $Id$
+#++
+
+
+require 'rubygems'
+require 'net/https'
+require 'rexml/document'
+require 'time'
+require 'www/delicious/bundle'
+require 'www/delicious/post'
+require 'www/delicious/tag'
+require 'www/delicious/errors'
+require 'www/delicious/version'
+
+
+module WWW #:nodoc:
+
+
+  #
+  # = WWW::Delicious
+  # 
+  # WWW::Delicious is a Ruby client for http://del.icio.us XML API.
+  # 
+  # It provides both read and write functionalities. 
+  # You can read user Posts, Tags and Bundles 
+  # but you can create new Posts, Tags and Bundles as well.
+  #
+  #
+  # == Basic Usage
+  # 
+  # The following is just a basic demonstration of the main features.
+  # See the README file for a deeper explanation about how to get the best
+  # from WWW::Delicious library.
+  # 
+  # The examples in this page make the following assumptions
+  # * you have a valid del.icio.us account
+  # * +username+ is your account username
+  # * +password+ is your account password
+  # 
+  # In order to make a query you first need to create
+  # a new WWW::Delicious instance as follows:
+  #
+  #   require 'www/delicious'
+  # 
+  #   username = 'my delicious username'
+  #   password = 'my delicious password'
+  #
+  #   d = WWW::Delicious.new(username, password)
+  # 
+  # The constructor accepts some additional options.
+  # For instance, if you want to customize the user agent:
+  # 
+  #   d = WWW::Delicious.new(username, password, :user_agent => 'FooAgent')
+  #   
+  # Now you can use any of the API methods available.
+  # 
+  # For example, you may want to know when your account was last updated
+  # to check whether someone else made some changes on behalf of you:
+  # 
+  #   datetime = d.update # => Wed Mar 12 08:41:20 UTC 2008
+  #   
+  # Because the answer is a valid +Time+ instance, you can format it with +strftime+.
+  #   
+  #   datetime = d.update # => Wed Mar 12 08:41:20 UTC 2008
+  #   datetime.strftime('%Y') # => 2008
+  #
+  class Delicious
+    
+    NAME            = 'WWW::Delicious'
+    GEM             = 'www-delicious'
+    AUTHOR          = 'Simone Carletti <weppos@weppos.net>'
+    
+    # del.icio.us account username
+    attr_reader :username
+    
+    # del.icio.us account password
+    attr_reader :password
+    
+    # base URI for del.icio.us API
+    attr_reader :base_uri
+
+    
+    # API Base URL
+    API_BASE_URI    = 'https://api.del.icio.us'
+
+    # API Path Update
+    API_PATH_UPDATE         = '/v1/posts/update';
+
+    # API Path All Bundles
+    API_PATH_BUNDLES_ALL    = '/v1/tags/bundles/all';
+    # API Path Set Bundle
+    API_PATH_BUNDLES_SET    = '/v1/tags/bundles/set';
+    # API Path Delete Bundle
+    API_PATH_BUNDLES_DELETE = '/v1/tags/bundles/delete';
+
+    # API Path Get Tags
+    API_PATH_TAGS_GET       = '/v1/tags/get';
+    # API Path Rename Tag
+    API_PATH_TAGS_RENAME    = '/v1/tags/rename';
+
+    # API Path Get Posts
+    API_PATH_POSTS_GET      = '/v1/posts/get';
+    # API Path Recent Posts
+    API_PATH_POSTS_RECENT   = '/v1/posts/recent';
+    # API Path All Posts
+    API_PATH_POSTS_ALL      = '/v1/posts/all';
+    # API Path Posts by Dates
+    API_PATH_POSTS_DATES    = '/v1/posts/dates';
+    # API Path Add Post
+    API_PATH_POSTS_ADD      = '/v1/posts/add';
+    # API Path Delete Post
+    API_PATH_POSTS_DELETE   = '/v1/posts/delete';
+    
+    # Time to wait before sending a new request, in seconds
+    SECONDS_BEFORE_NEW_REQUEST = 1
+    
+    # Time converter converts a Time instance into the format
+    # requested by Delicious API
+    TIME_CONVERTER = lambda { |time| time.iso8601() }
+    
+    
+    # 
+    # Constructs a new <tt>WWW::Delicious</tt> object 
+    # with given +username+ and +password+.
+    #   
+    #   # create a new object with username 'user' and password 'psw
+    #   obj = WWW::Delicious('user', 'psw')
+    #   # => self
+    # 
+    # If a block is given, the instance is passed to the block
+    # but this method always returns the instance itself.
+    # 
+    #   WWW::Delicious('user', 'psw') do |d|
+    #     d.update() # => Fri May 02 18:02:48 UTC 2008
+    #   end
+    #   # => self
+    # 
+    # You can also specify some additional options, including a custom user agent
+    # or the base URI for del.icio.us API.
+    # 
+    #   WWW::Delicious('user', 'psw', :base_uri => 'https://ma.gnolia.com/api/mirrord') do |d|
+    #     # the following call is mirrored by ma.gnolia
+    #     d.update() # => Fri May 02 18:02:48 UTC 2008
+    #   end
+    #   # => self
+    #   
+    # === Options
+    # This class accepts a Hash with additional options.
+    # Here's the list of valid keys:
+    #
+    # <tt>:user_agent</tt>:: User agent to display in HTTP requests.
+    # <tt>:base_uri</tt>:: The base URI to del.icio.us API.
+    # 
+    def initialize(username, password, options = {}, &block) #  :yields: delicious
+      @username, @password = username.to_s, password.to_s
+      
+      # set API base URI
+      @base_uri = URI.parse(options[:base_uri] || API_BASE_URI)
+      
+      init_user_agent(options)
+      init_http_client(options)
+      
+      yield self if block_given?
+      self # ensure to always return self even if block is given
+    end
+    
+    
+    # 
+    # Returns the reference to current <tt>@http_client</tt>.
+    # The http is always valid unless it has been previously set to +nil+.
+    # 
+    #   # nil client
+    #   obj.http_client # => nil
+    #   
+    #   # valid client
+    #   obj.http_client # => Net::HTTP
+    # 
+    def http_client()
+      return @http_client
+    end
+
+    # 
+    # Sets the internal <tt>@http_client</tt> to +client+.
+    # 
+    #   # nil client
+    #   obj.http_client = nil
+    # 
+    #   # http client
+    #   obj.http_client = Net::HTTP.new()
+    # 
+    #   # invalid client
+    #   obj.http_client = 'foo' # => ArgumentError
+    # 
+    def http_client=(client)
+      unless client.kind_of?(Net::HTTP) or client.nil?
+        raise ArgumentError, "`client` expected to be a kind of `Net::HTTP`, `#{client.class}` given"
+      end
+      @http_client = client
+    end
+    
+    # Returns current user agent string.
+    def user_agent()
+      return @headers['User-Agent']
+    end
+    
+    
+    # 
+    # Returns true if given account credentials are valid.
+    # 
+    #   d = WWW::Delicious.new('username', 'password')
+    #   d.valid_account? # => true
+    # 
+    #   d = WWW::Delicious.new('username', 'invalid_password')
+    #   d.valid_account? # => false
+    # 
+    # This method is not "exception safe".
+    # It doesn't return false if an HTTP error or any kind of other error occurs,
+    # it raises back the exception to the caller instead.
+    # 
+    # 
+    # Raises::  WWW::Delicious::Error
+    # Raises::  WWW::Delicious::HTTPError
+    # Raises::  WWW::Delicious::ResponseError
+    # 
+    def valid_account?
+      update()
+      return true
+    rescue HTTPError => e
+      return false if e.message =~ /invalid username or password/i
+      raise 
+    end
+
+    # 
+    # Checks to see when a user last posted an item
+    # and returns the last update +Time+ for the user.
+    # 
+    #   d.update() # => Fri May 02 18:02:48 UTC 2008
+    # 
+    # 
+    # Raises::  WWW::Delicious::Error
+    # Raises::  WWW::Delicious::HTTPError
+    # Raises::  WWW::Delicious::ResponseError
+    # 
+    def update()
+      response = request(API_PATH_UPDATE)
+      return parse_update_response(response.body)
+    end
+    
+    # 
+    # Retrieves all of a user's bundles
+    # and returns an array of <tt>WWW::Delicious::Bundle</tt>.
+    # 
+    #   d.bundles_all() # => [#<WWW::Delicious::Bundle>, #<WWW::Delicious::Bundle>, ...]
+    #   d.bundles_all() # => []
+    # 
+    # 
+    # Raises::  WWW::Delicious::Error
+    # Raises::  WWW::Delicious::HTTPError
+    # Raises::  WWW::Delicious::ResponseError
+    # 
+    def bundles_all()
+      response = request(API_PATH_BUNDLES_ALL)
+      return parse_bundle_collection(response.body)
+    end
+    
+    # 
+    # Assignes a set of tags to a single bundle, 
+    # wipes away previous settings for bundle.
+    # 
+    #   # create from a bundle
+    #   d.bundles_set(WWW::Delicious::Bundle.new('MyBundle'), %w(foo bar))
+    # 
+    #   # create from a string
+    #   d.bundles_set('MyBundle', %w(foo bar))
+    # 
+    # 
+    # Raises::  WWW::Delicious::Error
+    # Raises::  WWW::Delicious::HTTPError
+    # Raises::  WWW::Delicious::ResponseError
+    # 
+    def bundles_set(bundle_or_name, tags = [])
+      params = prepare_bundles_set_params(bundle_or_name, tags)
+      response = request(API_PATH_BUNDLES_SET, params)
+      return parse_and_eval_execution_response(response.body)
+    end
+    
+    # 
+    # Deletes +bundle_or_name+ bundle from del.icio.us.
+    # +bundle_or_name+ can be either a WWW::Delicious::Bundle instance 
+    # or a string with the name of the bundle.
+    # 
+    # This method doesn't care whether the exists.
+    # If not, the execution will silently return without rising any error.
+    # 
+    #   # delete from a bundle
+    #   d.bundles_delete(WWW::Delicious::Bundle.new('MyBundle'))
+    # 
+    #   # delete from a string
+    #   d.bundles_delete('MyBundle', %w(foo bar))
+    # 
+    # 
+    # Raises::  WWW::Delicious::Error
+    # Raises::  WWW::Delicious::HTTPError
+    # Raises::  WWW::Delicious::ResponseError
+    # 
+    def bundles_delete(bundle_or_name)
+      params = prepare_bundles_delete_params(bundle_or_name)
+      response = request(API_PATH_BUNDLES_DELETE, params)
+      return parse_and_eval_execution_response(response.body)
+    end
+    
+    # 
+    # Retrieves the list of tags and number of times used by the user
+    # and returns an array of <tt>WWW::Delicious::Tag</tt>.
+    # 
+    #   d.tags_get() # => [#<WWW::Delicious::Tag>, #<WWW::Delicious::Tag>, ...]
+    #   d.tags_get() # => []
+    # 
+    # 
+    # Raises::  WWW::Delicious::Error
+    # Raises::  WWW::Delicious::HTTPError
+    # Raises::  WWW::Delicious::ResponseError
+    # 
+    def tags_get()
+      response = request(API_PATH_TAGS_GET)
+      return parse_tag_collection(response.body)
+    end
+    
+    # 
+    # Renames an existing tag with a new tag name.
+    # 
+    #   # rename from a tag
+    #   d.bundles_set(WWW::Delicious::Tag.new('old'), WWW::Delicious::Tag.new('new'))
+    # 
+    #   # rename from a string
+    #   d.bundles_set('old', 'new')
+    # 
+    # 
+    # Raises::  WWW::Delicious::Error
+    # Raises::  WWW::Delicious::HTTPError
+    # Raises::  WWW::Delicious::ResponseError
+    # 
+    def tags_rename(from_name_or_tag, to_name_or_tag)
+      params = prepare_tags_rename_params(from_name_or_tag, to_name_or_tag)
+      response = request(API_PATH_TAGS_RENAME, params)
+      return parse_and_eval_execution_response(response.body)
+    end
+    
+    # 
+    # Returns an array of <tt>WWW::Delicious::Post</tt> matching +options+.
+    # If no option is given, the last post is returned.
+    # If no date or url is given, most recent date will be used.
+    # 
+    #   d.posts_get() # => [#<WWW::Delicious::Post>, #<WWW::Delicious::Post>, ...]
+    #   d.posts_get() # => []
+    # 
+    #   # get all posts tagged with ruby
+    #   d.posts_get(:tag => WWW::Delicious::Tag.new('ruby))
+    # 
+    #   # get all posts matching URL 'http://www.simonecarletti.com'
+    #   d.posts_get(:url => URI.parse('http://www.simonecarletti.com'))
+    # 
+    #   # get all posts tagged with ruby and matching URL 'http://www.simonecarletti.com'
+    #   d.posts_get(:tag => WWW::Delicious::Tag.new('ruby),
+    #               :url => URI.parse('http://www.simonecarletti.com'))
+    # 
+    # 
+    # === Options
+    # <tt>:tag</tt>:: a tag to filter by. It can be either a <tt>WWW::Delicious::Tag</tt> or a +String+.
+    # <tt>:dt</tt>::  a +Time+ with a date to filter by.
+    # <tt>:url</tt>:: a valid URI to filter by. It can be either an instance of +URI+ or a +String+.
+    # 
+    # Raises::  WWW::Delicious::Error
+    # Raises::  WWW::Delicious::HTTPError
+    # Raises::  WWW::Delicious::ResponseError
+    # 
+    def posts_get(options = {})
+      params = prepare_posts_params(options.clone, [:dt, :tag, :url])
+      response = request(API_PATH_POSTS_GET, params)
+      return parse_post_collection(response.body)
+    end
+
+    # 
+    # Returns a list of the most recent posts, filtered by argument.
+    # 
+    #   # get the most recent posts
+    #   d.posts_recent()
+    # 
+    #   # get the 10 most recent posts
+    #   d.posts_recent(:count => 10)
+    # 
+    # 
+    # === Options
+    # <tt>:tag</tt>::   a tag to filter by. It can be either a <tt>WWW::Delicious::Tag</tt> or a +String+.
+    # <tt>:count</tt>:: number of items to retrieve. (default: 15, maximum: 100).
+    # 
+    def posts_recent(options = {})
+      params = prepare_posts_params(options.clone, [:count, :tag])
+      response = request(API_PATH_POSTS_RECENT, params)
+      return parse_post_collection(response.body)
+    end
+    
+    # 
+    # Returns a list of all posts, filtered by argument.
+    # 
+    #   # get all (this is a very expensive query)
+    #   d.posts_all
+    # 
+    #   # get all posts matching ruby
+    #   d.posts_all(:tag => WWW::Delicious::Tag.new('ruby'))
+    # 
+    # 
+    # === Options
+    # <tt>:tag</tt>:: a tag to filter by. It can be either a <tt>WWW::Delicious::Tag</tt> or a +String+.
+    #
+    def posts_all(options = {})
+      params = prepare_posts_params(options.clone, [:tag])
+      response = request(API_PATH_POSTS_ALL, params)
+      return parse_post_collection(response.body)
+    end
+
+    #
+    # Returns a list of dates with the number of posts at each date.
+    # 
+    #   # get number of posts per date
+    #   d.posts_dates
+    #   # => { '2008-05-05' => 12, '2008-05-06' => 3, ... }
+    # 
+    #   # get number posts per date tagged as ruby
+    #   d.posts_dates(:tag => WWW::Delicious::Tag.new('ruby'))
+    #   # => { '2008-05-05' => 10, '2008-05-06' => 3, ... }
+    # 
+    # 
+    # === Options
+    # <tt>:tag</tt>:: a tag to filter by. It can be either a <tt>WWW::Delicious::Tag</tt> or a +String+.
+    #
+    def posts_dates(options = {})
+      params = prepare_posts_params(options.clone, [:tag])
+      response = request(API_PATH_POSTS_DATES, params)
+      return parse_posts_dates_response(response.body)
+    end
+
+    #
+    # Add a post to del.icio.us.
+    # +post_or_values+ can be either a +WWW::Delicious::Post+ instance
+    # or a Hash of params. This method accepts all params available
+    # to initialize a new +WWW::Delicious::Post+.
+    # 
+    #   # add a post from WWW::Delicious::Post
+    #   d.posts_add(WWW::Delicious::Post.new(:url => 'http://www.foobar.com', :title => 'Hello world!'))
+    # 
+    #   # add a post from values
+    #   d.posts_add(:url => 'http://www.foobar.com', :title => 'Hello world!')
+    # 
+    #
+    def posts_add(post_or_values)
+      params = prepare_param_post(post_or_values).to_params
+      response = request(API_PATH_POSTS_ADD, params)
+      return parse_and_eval_execution_response(response.body)
+    end
+
+    #
+    # Deletes the post matching given +url+ from del.icio.us.
+    # +url+ can be either an URI instance or a string representation of a valid URL.
+    # 
+    # This method doesn't care whether a post with given +url+ exists.
+    # If not, the execution will silently return without rising any error.
+    # 
+    #   # delete a post from URI
+    #   d.post_delete(URI.parse('http://www.foobar.com/'))
+    # 
+    #   # delete a post from a string
+    #   d.post_delete('http://www.foobar.com/')
+    # 
+    #
+    def posts_delete(url)
+      params = prepare_posts_params({:url => url}, [:url])
+      response = request(API_PATH_POSTS_DELETE, params)
+      return parse_and_eval_execution_response(response.body)
+    end
+
+    
+    protected
+    
+      # Initializes the HTTP client.
+      # It automatically enable +use_ssl+ flag according to +@base_uri+ scheme.
+      def init_http_client(options)
+        http = Net::HTTP.new(@base_uri.host, 443)
+        http.use_ssl = true if @base_uri.scheme == "https"
+        http.verify_mode = OpenSSL::SSL::VERIFY_NONE # FIXME: not 100% supported
+        self.http_client = http
+      end
+      
+      # Initializes user agent value for HTTP requests.
+      def init_user_agent(options)
+        user_agent = options[:user_agent] || default_user_agent()
+        @headers ||= {}
+        @headers['User-Agent'] = user_agent
+      end
+      
+      # 
+      # Creates and returns the default user agent string.
+      # 
+      # By default, the user agent is composed by the following schema:
+      # <tt>NAME/VERSION (Ruby/RUBY_VERSION)</tt>
+      # 
+      # * +NAME+ is the constant representing this library name
+      # * +VERSION+ is the constant representing current library version
+      # * +RUBY_VERSION+ is the version of Ruby interpreter the library is interpreted by
+      # 
+      #   default_user_agent
+      #   # => WWW::Delicious/0.1.0 (Ruby/1.8.6)
+      # 
+      def default_user_agent
+        return "#{NAME}/#{VERSION} (Ruby/#{RUBY_VERSION})"
+      end
+      
+      
+      # 
+      # Composes an HTTP query string from an hash of +options+.
+      # The result is URI encoded.
+      # 
+      #   http_build_query(:foo => 'baa', :bar => 'boo')
+      #   # => foo=baa&bar=boo
+      # 
+      def http_build_query(params = {})
+        return params.collect do |k,v| 
+          "#{URI.encode(k.to_s)}=#{URI.encode(v.to_s)}" unless v.nil?
+        end.compact.join('&')
+      end
+      
+      # 
+      # Sends an HTTP GET request to +path+ and appends given +params+.
+      # 
+      # This method is 100% compliant with Delicious API reference.
+      # It waits at least 1 second between each HTTP request and
+      # provides an identifiable user agent by default,
+      # or the custom user agent set by +user_agent+ option 
+      # when this istance has been created.
+      # 
+      #   request('/v1/api/path', :foo => 1, :bar => 2)
+      #   # => sends a GET request to /v1/api/path?foo=1&bar=2
+      # 
+      def request(path, params = {})
+        raise Error, 'Invalid HTTP Client' unless http_client
+        wait_before_new_request
+      
+        uri = @base_uri.merge(path)
+        uri.query = http_build_query(params) unless params.empty?
+      
+        begin
+          @last_request = Time.now  # see #wait_before_new_request
+          @last_request_uri = uri   # useful for debug
+          response = make_request(uri)
+        rescue => e # catch EOFError, SocketError and more
+          raise HTTPError, e.message
+        end
+      
+        case response
+          when Net::HTTPSuccess
+            return response
+          when Net::HTTPUnauthorized        # 401
+            raise HTTPError, 'Invalid username or password'
+          when Net::HTTPServiceUnavailable  # 503
+            raise HTTPError, 'You have been throttled.' +
+              'Please ensure you are waiting at least one second before each request.'
+          else
+            raise HTTPError, "HTTP #{response.code}: #{response.message}"
+        end
+      end
+      
+      # Makes the real HTTP request to given +uri+ and returns the +response+.
+      # This method exists basically to simplify unit testing with mocha.
+      def make_request(uri)
+        http_client.start do |http|
+          req = Net::HTTP::Get.new(uri.request_uri, @headers)
+          req.basic_auth(@username, @password)
+          http.request(req)
+        end
+      end
+      
+      # 
+      # Delicious API reference requests to wait AT LEAST ONE SECOND 
+      # between queries or the client is likely to get automatically throttled.
+      # 
+      # This method calculates the difference between current time
+      # and the last request time and wait for the necessary time to meet
+      # SECONDS_BEFORE_NEW_REQUEST requirement.
+      # 
+      # The difference is not rounded. If you only have to wait for 0.034 seconds
+      # then your don't have to wait 0 or 1 seconds, but 0.034 seconds!
+      # 
+      def wait_before_new_request
+        return unless @last_request # this is the first request
+        # puts "Last request at #{TIME_CONVERTER.call(@last_request)}" if debug?
+        diff = Time.now - @last_request
+        if diff < SECONDS_BEFORE_NEW_REQUEST
+          # puts "Sleeping for #{diff} before new request..." if debug?
+          sleep(SECONDS_BEFORE_NEW_REQUEST - diff) 
+        end
+      end
+      
+      
+      # 
+      # Parses the response <tt>body</tt> and runs a common set of validators.
+      # Returns <tt>body</tt> as parsed REXML::Document on success.
+      # 
+      # Raises::  WWW::Delicious::ResponseError in case of invalid response.
+      # 
+      def parse_and_validate_response(body, options = {})
+        dom = REXML::Document.new(body)
+        
+        if (value = options[:root_name]) && dom.root.name != value
+          raise ResponseError, "Invalid response, root node is not `#{value}`"
+        end
+        if (value = options[:root_text]) && dom.root.text != value
+          raise ResponseError, value
+        end
+        
+        return dom
+      end
+      
+      # 
+      # Parses and evaluates the response returned by an execution,
+      # usually an update/delete/insert operation.
+      # 
+      # Raises::  WWW::Delicious::ResponseError in case of invalid response
+      # Raises::  WWW::Delicious::Error in case of execution error
+      # 
+      def parse_and_eval_execution_response(body)
+        dom = parse_and_validate_response(body, :root_name => 'result')
+        response = dom.root.if_attribute_value(:code)
+        response = dom.root.text if response.nil?
+        raise Error, "Invalid response, #{response}" unless %w(done ok).include?(response)
+        true
+      end
+      
+      # Parses the response of an Update request
+      # and returns the update Timestamp.
+      def parse_update_response(body)
+        dom = parse_and_validate_response(body, :root_name => 'update')
+        dom.root.if_attribute_value(:time) { |v| Time.parse(v) }
+      end
+      
+      # Parses a response containing a collection of Bundles
+      # and returns an array of <tt>WWW::Delicious::Bundle</tt>.
+      def parse_bundle_collection(body)
+        dom = parse_and_validate_response(body, :root_name => 'bundles')
+        dom.root.elements.collect('bundle') { |xml| Bundle.from_rexml(xml) }
+      end
+      
+      # Parses a response containing a collection of Tags
+      # and returns an array of <tt>WWW::Delicious::Tag</tt>.
+      def parse_tag_collection(body)
+        dom  = parse_and_validate_response(body, :root_name => 'tags')
+        dom.root.elements.collect('tag') { |xml| Tag.from_rexml(xml) }
+      end
+      
+      # Parses a response containing a collection of Posts
+      # and returns an array of <tt>WWW::Delicious::Post</tt>.
+      def parse_post_collection(body)
+        dom  = parse_and_validate_response(body, :root_name => 'posts')
+        dom.root.elements.collect('post') { |xml| Post.from_rexml(xml) }
+      end
+      
+      # Parses the response of a <tt>posts_dates</tt> request
+      # and returns a +Hash+ of date => count.
+      def parse_posts_dates_response(body)
+        dom  = parse_and_validate_response(body, :root_name => 'dates')
+        return dom.root.get_elements('date').inject({}) do |collection, xml|
+          date  = xml.if_attribute_value(:date) 
+          count = xml.if_attribute_value(:count)
+          collection.merge({ date => count })
+        end
+      end
+      
+      
+      # 
+      # Prepares the params for a `bundles_set` call
+      # and returns a Hash with the params ready for the HTTP request.
+      # 
+      # Raises::  WWW::Delicious::Error
+      # 
+      def prepare_bundles_set_params(name_or_bundle, tags = [])
+        bundle = prepare_param_bundle(name_or_bundle, tags) do |b|
+          raise Error, "Bundle name is empty" if b.name.empty?
+          raise Error, "Bundle must contain at least one tag" if b.tags.empty?
+        end
+        return { :bundle => bundle.name, :tags => bundle.tags.join(' ') }
+      end
+      
+      # 
+      # Prepares the params for a `bundles_set` call
+      # and returns a Hash with the params ready for the HTTP request.
+      # 
+      # Raises::  WWW::Delicious::Error
+      # 
+      def prepare_bundles_delete_params(name_or_bundle)
+        bundle = prepare_param_bundle(name_or_bundle) do |b|
+          raise Error, "Bundle name is empty" if b.name.empty?
+        end
+        return { :bundle => bundle.name }
+      end
+      
+      # 
+      # Prepares the params for a `tags_rename` call
+      # and returns a Hash with the params ready for the HTTP request.
+      # 
+      # Raises::  WWW::Delicious::Error
+      # 
+      def prepare_tags_rename_params(from_name_or_tag, to_name_or_tag)
+        from, to = [from_name_or_tag, to_name_or_tag].collect do |v|
+          prepare_param_tag(v)
+        end
+        return { :old => from, :new => to }
+      end
+      
+      # 
+      # Prepares the params for a `post_*` call
+      # and returns a Hash with the params ready for the HTTP request.
+      # 
+      # Raises::  WWW::Delicious::Error
+      # 
+      def prepare_posts_params(params, allowed_params = [])
+        compare_params(params, allowed_params)
+        
+        # we don't need to check whether the following parameters
+        # are valid for this request because compare_params
+        # would raise if an invalid param is supplied
+        
+        params[:tag]    = prepare_param_tag(params[:tag])  if params[:tag]
+        params[:dt]     = TIME_CONVERTER.call(params[:dt]) if params[:dt]
+        params[:url]    = URI.parse(params[:url])          if params[:url]
+        params[:count]  = if value = params[:count]
+          raise Error, 'Expected `count` <= 100' if value.to_i() > 100 # requirement
+          value.to_i
+        else
+          15 # default value
+        end
+        
+        return params
+      end
+      
+      
+      # 
+      # Prepares the +post+ param for an API request.
+      # 
+      # Creates and returns a <tt>WWW::Delicious::Post</tt> instance from <tt>post_or_values</tt>.
+      # <tt>post_or_values</tt> can be either an Hash with post attributes
+      # or a <tt>WWW::Delicious::Post</tt> instance.
+      # 
+      def prepare_param_post(post_or_values, &block)
+        post = case post_or_values
+          when WWW::Delicious::Post
+            post_or_values
+          when Hash
+            Post.new(post_or_values)
+          else
+            raise ArgumentError, 'Expected `args` to be `WWW::Delicious::Post` or `Hash`'
+          end
+          
+        yield(post) if block_given?
+        # TODO: validate post with post.validate!
+        raise ArgumentError, 'Both `url` and `title` are required' unless post.api_valid?
+        post
+      end
+      
+      # 
+      # Prepares the +bundle+ param for an API request.
+      # 
+      # Creates and returns a <tt>WWW::Delicious::Bundle</tt> instance from <tt>name_or_bundle</tt>.
+      # <tt>name_or_bundle</tt> can be either a string holding bundle name
+      # or a <tt>WWW::Delicious::Bundle</tt> instance.
+      # 
+      def prepare_param_bundle(name_or_bundle, tags = [], &block) #  :yields: bundle
+        bundle = case name_or_bundle
+          when WWW::Delicious::Bundle
+            name_or_bundle
+          else
+            Bundle.new(:name => name_or_bundle, :tags => tags)
+          end
+        
+        yield(bundle) if block_given?
+        # TODO: validate bundle with bundle.validate!
+        bundle
+      end
+      
+      # 
+      # Prepares the +tag+ param for an API request.
+      # 
+      # Creates and returns a <tt>WWW::Delicious::Tag</tt> instance from <tt>name_or_tag</tt>.
+      # <tt>name_or_tag</tt> can be either a string holding tag name
+      # or a <tt>WWW::Delicious::Tag</tt> instance.
+      # 
+      def prepare_param_tag(name_or_tag, &block) #  :yields: tag
+        tag = case name_or_tag
+          when WWW::Delicious::Tag
+            name_or_tag
+          else
+            Tag.new(:name => name_or_tag.to_s)
+          end
+        
+        yield(tag) if block_given?
+        # TODO: validate tag with tag.validate!
+        raise "Invalid `tag` value supplied" unless tag.api_valid?
+        tag
+      end
+      
+      # 
+      # Checks whether user given +params+ are valid against a defined collection of +valid_params+.
+      # 
+      # === Examples
+      # 
+      #   params = {:foo => 1, :bar => 2}
+      #
+      #   compare_params(params, [:foo, :bar])
+      #   # => valid
+      # 
+      #   compare_params(params, [:foo, :bar, :baz])
+      #   # => raises
+      # 
+      #   compare_params(params, [:foo])
+      #   # => raises
+      # 
+      # Raises::  WWW::Delicious::Error
+      # 
+      def compare_params(params, valid_params)
+        raise ArgumentError, "Expected `params` to be a kind of `Hash`" unless params.kind_of?(Hash)
+        raise ArgumentError, "Expected `valid_params` to be a kind of `Array`" unless valid_params.kind_of?(Array)
+      
+        # compute options difference
+        difference = params.keys - valid_params
+        raise Error, "Invalid params: `#{difference.join('`, `')}`" unless difference.empty?
+      end
+    
+    
+    module XMLUtils #:nodoc:
+      
+      #
+      # Returns the +xmlattr+ attribute value for current <tt>REXML::Element</tt>.
+      # 
+      # If block is given and attribute value is not nil,
+      # the content of the block is executed.
+      # 
+      # === Examples
+      # 
+      #   dom = REXML::Document.new('<a name="1"><b>foo</b><b>bar</b></a>')
+      # 
+      #   dom.root.if_attribute_value(:name)
+      #   # => "1"
+      # 
+      #   dom.root.if_attribute_value(:name) { |v| v.to_i }
+      #   # => 1
+      # 
+      #   dom.root.if_attribute_value(:foo)
+      #   # => nil
+      # 
+      #   dom.root.if_attribute_value(:name) { |v| v.to_i }
+      #   # => nil
+      #
+      def if_attribute_value(xmlattr, &block) #:nodoc:
+        value = if attr = self.attribute(xmlattr.to_s)
+            attr.value
+          else
+            nil
+          end
+        value = yield value if !value.nil? and block_given?
+        value
+      end
+      
+      #
+      # Returns the value of +expression+ child of this element, if it exists.
+      # If blog is given, block is called on +expression+ element value
+      # and the result is returned.
+      #
+      def if_element_value(expression, &block)
+        if_element(expression) do |element|
+          value = element.text
+          value = yield value if block_given?
+          value
+        end
+      end
+      
+      #
+      # Executes the content of +block+ on +expression+
+      # child of this element, if it exists.
+      # Returns the result or +nil+ if +xmlelement+ doesn't exist.
+      #
+      def if_element(expression, &block)
+        raise LocalJumpError, "no block given" unless block_given?
+        if element = self.elements[expression.to_s]
+          yield element
+        else
+          nil
+        end
+      end
+    
+    end # XMLUtils
+
+  end
+end
+
+
+class Object
+  
+  # An object is blank if it's false, empty, or a whitespace string.
+  # For example, "", "   ", +nil+, [], and {} are blank.
+  # 
+  # This simplifies
+  # 
+  #   if !address.nil? && !address.empty?
+  # 
+  # to
+  # 
+  #   if !address.blank?
+  #
+  # Object#blank? comes from the GEM ActiveSupport 2.1.
+  # 
+  def blank? 
+    respond_to?(:empty?) ? empty? : !self
+  end unless Object.method_defined? :blanks?
+  
+end
+
+
+module REXML # :nodoc:
+  class Element < Parent # :nodoc:
+    include WWW::Delicious::XMLUtils
+  end
+end