www-delicious 0.1.0 → 0.2.0

data/CHANGELOG.rdoc

@@ -0,0 +1,41 @@
+= Changelog
+
+
+== 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/Manifest

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

data/{README → README.rdoc}

@@ -23,7 +23,7 @@ WWW::Delicious will try to give you the most with less efforts.
 
 == Dependencies
 
-  * Ruby 1.8.6
+* Ruby 1.8.6
 
 
 == Source
@@ -176,15 +176,22 @@ You can also create new bundles or delete existing ones.
 
 == Documentation
 
-Visit the website[http://code.simonecarletti.com/] for the full documentation
+Visit the website[http://code.simonecarletti.com/www-delicious] for the full documentation
 and more examples.
 
 
+== Author
+
+* {Simone Carletti}[http://www.simonecarletti.com/] <weppos@weppos.net>
+
+If you like this software, please {recommend me}[http://www.workingwithrails.com/person/11967-simone-carletti] at Working with Rails.
+
+
 == Website and Project Home
 
-  * {Project Homepage}[http://code.simonecarletti.com/]
-  * {At GitHub}[http://github.com/weppos/www-delicious/]
-  * {At RubyForge}[http://rubyforge.org/projects/www-delicious/]
+* {Project Homepage}[http://code.simonecarletti.com/www-delicious]
+* {At GitHub}[http://github.com/weppos/www-delicious/]
+* {At RubyForge}[http://rubyforge.org/projects/www-delicious/]
 
 
 == FeedBack and Bug reports
@@ -193,15 +200,7 @@ Feel free to email {Simone Carletti}[mailto:weppos@weppos.net]
 with any questions or feedback.
 
 Please submit your bug reports to the Redmine installation for WWW::Delicious
-available at http://code.simonecarletti.com/.
-
-
-== TODO
-
-  * allow Tags and Bundles to be passed as params for API calls
-  * allow Tags, Bundles and Posts to be used for API call (no longer readonly)
-  * improve the way new posts are created and updated
-  * more (see issue tracker on the website)
+available at http://code.simonecarletti.com/www-delicious.
 
 
 == Changelog

data/Rakefile

@@ -1,137 +1,55 @@
 require 'rubygems'
-require 'rake/gempackagetask'
-require 'rake/testtask'
-require 'rake/rdoctask'
+require 'echoe'
 
 $LOAD_PATH.unshift(File.dirname(__FILE__) + "/lib")
 require 'www/delicious'
 
-
+ 
 # Common package properties
-PKG_NAME    = ENV['PKG_NAME'] || WWW::Delicious::GEM
+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 |fl|
+PKG_FILES = FileList.new("{lib,test}/**/*.rb") do |fl|
   fl.exclude 'TODO'
-  fl.include %w(README CHANGELOG MIT-LICENSE)
+  fl.include %w(README.rdoc CHANGELOG.rdoc MIT-LICENSE.rdoc)
   fl.include %w(Rakefile setup.rb)
 end
 RUBYFORGE_PROJECT = 'www-delicious'
-
-
-# 
-# task::
-#   :test
-# desc::
-#   Run all the tests.
-#
-desc "Run all the tests"
-Rake::TestTask.new(:test) do |t|
-  t.test_files  = FileList["test/unit/*.rb"]
-  t.verbose     = true
+ 
+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  = ["-x Rakefile -x mocha -x rcov"]
+  p.rdoc_pattern  = /^(lib|CHANGELOG.rdoc|README.rdoc)/
+
+  p.development_dependencies = ["rake  >=0.8",
+                                "echoe >=3",
+                                "mocha >=0.9"]
 end
 
 
-# 
-# task::
-#   :rcov
-# desc::
-#   Create code coverage report.
-#
 begin
-  require 'rcov/rcovtask'
-
-  desc "Create code coverage report"
-  Rcov::RcovTask.new(:rcov) do |t|
-    t.rcov_opts   = ["-xRakefile"]
-    t.test_files  = FileList["test/unit/*.rb"]
-    t.output_dir  = "coverage"
-    t.verbose     = true
+  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 "RCov is not available"
-end
-
-
-# 
-# task::
-#   :rdoc
-# desc::
-#   Generate RDoc documentation.
-#
-desc "Generate RDoc documentation"
-Rake::RDocTask.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir   = 'doc'
-  rdoc.title      = "#{PKG_NAME} -- #{PKG_SUMMARY}"
-  rdoc.main       = "README"
-  rdoc.options   << "--inline-source" << "--line-numbers"
-  rdoc.options   << '--charset' << 'utf-8'
-  rdoc.rdoc_files.include("README", "CHANGELOG", "MIT-LICENSE")
-  rdoc.rdoc_files.include("lib/**/*.rb")
-end
-
-
-unless defined?(Gem)
-  puts "Package Target requires RubyGEMs"
-else
-
-  # Package requirements
-  GEM_SPEC = Gem::Specification.new do |s|
-
-    s.name        = PKG_NAME
-    s.version     = PKG_VERSION
-    s.summary     = PKG_SUMMARY
-    s.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
-    s.platform    = Gem::Platform::RUBY
-    s.rubyforge_project = RUBYFORGE_PROJECT
-
-    s.required_ruby_version = '>= 1.8.6'
-    s.add_dependency('rake', '>= 0.7.3')
-
-    s.files = PKG_FILES.to_a()
-
-    s.has_rdoc = true
-    s.rdoc_options << "--title" << "#{s.name} -- #{s.summary}"
-    s.rdoc_options << "--inline-source" << "--line-numbers"
-    s.rdoc_options << "--main" << "README"
-    s.rdoc_options << '--charset' << 'utf-8'
-    s.extra_rdoc_files = %w(README CHANGELOG MIT-LICENSE)
-
-    s.test_files    = FileList["test/unit/*.rb"]
-
-    s.author    = "Simone Carletti"
-    s.email     = "weppos@weppos.net"
-    s.homepage  = "http://code.simonecarletti.com/www-delicious"
-
-  end
-  
-  # 
-  # task::
-  #   :gem
-  # desc::
-  #   Generate the GEM package and all stuff.
-  #
-  Rake::GemPackageTask.new(GEM_SPEC) do |p|
-    p.gem_spec = GEM_SPEC
-    p.need_tar = true
-    p.need_zip = true
-  end
-end
-
-
-# 
-# task::
-#   :clean
-# desc::
-#   Clean up generated directories and files.
-#
-desc "Clean up generated directories and files"
-task :clean do
-  rm_rf "pkg"
-  rm_rf "doc"
-  rm_rf "coverage"
+  puts "CodeStatistics (Rails) is not available"
 end

data/TODO

@@ -0,0 +1,4 @@
+== tags_delete(foo)
+
+This method should fetch all posts with :tag => foo and update them deleting the foo tag.
+

data/lib/www/delicious.rb

@@ -94,6 +94,9 @@ module WWW #:nodoc:
     
     # del.icio.us account password
     attr_reader :password
+    
+    # base URI for del.icio.us API
+    attr_reader :base_uri
 
     
     # API Base URL
@@ -135,8 +138,7 @@ module WWW #:nodoc:
     TIME_CONVERTER = lambda { |time| time.iso8601() }
     
     
-    public
-    #
+    # 
     # Constructs a new <tt>WWW::Delicious</tt> object 
     # with given +username+ and +password+.
     #   
@@ -151,19 +153,29 @@ module WWW #:nodoc:
     #     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 an Hash with additional 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(API_BASE_URI)
-
+      @base_uri = URI.parse(options[:base_uri] || API_BASE_URI)
+      
       init_user_agent(options)
       init_http_client(options)
       
@@ -171,9 +183,8 @@ module WWW #:nodoc:
       self # ensure to always return self even if block is given
     end
     
-
-    public
-    #
+    
+    # 
     # Returns the reference to current <tt>@http_client</tt>.
     # The http is always valid unless it has been previously set to +nil+.
     # 
@@ -182,15 +193,14 @@ module WWW #:nodoc:
     #   
     #   # valid client
     #   obj.http_client # => Net::HTTP
-    #
+    # 
     def http_client()
       return @http_client
     end
 
-    public
-    #
+    # 
     # Sets the internal <tt>@http_client</tt> to +client+.
-    #
+    # 
     #   # nil client
     #   obj.http_client = nil
     # 
@@ -206,18 +216,14 @@ module WWW #:nodoc:
       end
       @http_client = client
     end
-
-    public
-    #
+    
     # Returns current user agent string.
-    #
     def user_agent()
       return @headers['User-Agent']
     end
     
     
-    public
-    #
+    # 
     # Returns true if given account credentials are valid.
     # 
     #   d = WWW::Delicious.new('username', 'password')
@@ -230,10 +236,11 @@ module WWW #:nodoc:
     # 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
@@ -242,8 +249,7 @@ module WWW #:nodoc:
       raise 
     end
 
-    public
-    #
+    # 
     # Checks to see when a user last posted an item
     # and returns the last update +Time+ for the user.
     # 
@@ -253,14 +259,13 @@ module WWW #:nodoc:
     # 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
     
-    public
-    #
+    # 
     # Retrieves all of a user's bundles
     # and returns an array of <tt>WWW::Delicious::Bundle</tt>.
     # 
@@ -271,14 +276,13 @@ module WWW #:nodoc:
     # Raises::  WWW::Delicious::Error
     # Raises::  WWW::Delicious::HTTPError
     # Raises::  WWW::Delicious::ResponseError
-    #
+    # 
     def bundles_all()
       response = request(API_PATH_BUNDLES_ALL)
-      return parse_bundles_all_response(response.body)
+      return parse_bundle_collection(response.body)
     end
     
-    public
-    #
+    # 
     # Assignes a set of tags to a single bundle, 
     # wipes away previous settings for bundle.
     # 
@@ -292,16 +296,20 @@ module WWW #:nodoc:
     # 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
     
-    public
-    #
-    # Deletes a bundle.
+    # 
+    # 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'))
@@ -313,47 +321,69 @@ module WWW #:nodoc:
     # 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
     
-    public
-    #
+    # 
     # 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_tags_get_response(response.body)
+      return parse_tag_collection(response.body)
     end
     
-    public
-    #
+    # 
     # 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
     
-    public
-    #
+    # 
     # 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.
@@ -362,30 +392,42 @@ module WWW #:nodoc:
     # 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_posts_response(response.body)
+      return parse_post_collection(response.body)
     end
 
-    public
-    #
+    # 
     # 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_posts_response(response.body)
+      return parse_post_collection(response.body)
     end
-
-    public
-    #
-    # Returns a list of the most recent posts, filtered by argument.
+    
+    # 
+    # 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+.
@@ -393,13 +435,21 @@ module WWW #:nodoc:
     def posts_all(options = {})
       params = prepare_posts_params(options.clone, [:tag])
       response = request(API_PATH_POSTS_ALL, params)
-      return parse_posts_response(response.body)
+      return parse_post_collection(response.body)
     end
 
-    public
     #
     # 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+.
     #
@@ -409,24 +459,38 @@ module WWW #:nodoc:
       return parse_posts_dates_response(response.body)
     end
 
-    public
     #
     # 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_posts_add_params(post_or_values.clone)
+      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
 
-    public
     #
-    # Deletes a post from del.icio.us.
+    # 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/')
     # 
-    # === Params
-    # url::
-    #   the url of the item.
-    #   It can be either an +URI+ or a +String+.
     #
     def posts_delete(url)
       params = prepare_posts_params({:url => url}, [:url])
@@ -436,431 +500,448 @@ module WWW #:nodoc:
 
     
     protected
-    #
-    # Initializes HTTP client.
-    #
-    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
-    
-    protected
-    #
-    # 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
-    
-    protected
-    #
-    # 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
-    #
-    def default_user_agent()
-      return "#{NAME}/#{VERSION} (Ruby/#{RUBY_VERSION})"
-    end
-    
-    
-    protected
-    #
-    # Composes an HTTP query string from an hash of +options+.
-    #
-    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
     
-    protected
-    #
-    # 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.
-    #
-    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 = http_client.start do |http|
+      # 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
-      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}"
+      
+      # 
+      # 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
-    end
-    
-    protected
-    #
-    # 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) 
+      
+      
+      # 
+      # 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
-    end
-    
-    
-    protected
-    #
-    # Parses the response +body+ and runs a common set of validators.
-    #
-    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}`"
+      # 
+      # 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
-      if (value = options[:root_text]) && dom.root.text != value
-        raise ResponseError, value
+      
+      # 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
-
-      return dom
-    end
-    
-    protected
-    #
-    # Parses and evaluates the response returned by an execution,
-    # usually an update/delete/insert operation.
-    #
-    def parse_and_eval_execution_response(body)
-      dom = parse_and_validate_response(body, :root_name => 'result')
-
-      rsp = dom.root.attribute_value(:code)
-      rsp = dom.root.text if rsp.nil?
-      raise Error, "Invalid response, #{rsp}" unless %w(done ok).include?(rsp)
-    end
-    
-    protected
-    #
-    # Parses the response of an 'update' request.
-    #
-    def parse_update_response(body)
-      dom = parse_and_validate_response(body, :root_name => 'update')
-      return dom.root.attribute_value(:time) { |v| Time.parse(v) }
-    end
-    
-    protected
-    #
-    # Parses the response of a 'bundles_all' request
-    # and returns an array of <tt>WWW::Delicious::Bundle</tt>.
-    #
-    def parse_bundles_all_response(body)
-      dom = parse_and_validate_response(body, :root_name => 'bundles')
-      bundles = []
       
-      dom.root.elements.each('bundle') { |xml| bundles << Bundle.from_rexml(xml) }
-      return bundles
-    end
-    
-    protected
-    #
-    # Parses the response of a 'tags_get' request
-    # and returns an array of <tt>WWW::Delicious::Tag</tt>.
-    #
-    def parse_tags_get_response(body)
-      dom = parse_and_validate_response(body, :root_name => 'tags')
-      tags = []
+      # 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
       
-      dom.root.elements.each('tag') { |xml| tags << Tag.new(xml) }
-      return tags
-    end
-    
-    protected
-    #
-    # Parses a response containing a list of Posts
-    # and returns an array of <tt>WWW::Delicious::Post</tt>.
-    #
-    def parse_posts_response(body)
-      dom = parse_and_validate_response(body, :root_name => 'posts')
-      posts = []
+      # 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
       
-      dom.root.elements.each('post') { |xml| posts << Post.new(xml) }
-      return posts
-    end
-    
-    protected
-    #
-    # Parses the response of a 'posts_dates' request
-    # and returns an +Hash+ of date => count.
-    #
-    def parse_posts_dates_response(body)
-      dom = parse_and_validate_response(body, :root_name => 'dates')
-      results = {}
-      
-      dom.root.elements.each('date') do |xml|
-        date  = xml.attribute_value(:date) 
-        count = xml.attribute_value(:count).to_i()
-        results[date] = count
+      # 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
-      return results
-    end
-    
-    
-    protected
-    #
-    # Prepares the params for a `bundles_set` request.
-    # 
-    # === Returns
-    # An +Hash+ with params to supply to the HTTP request.
-    # 
-    # Raises::
-    #
-    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?
+      
+      # 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
-
-      return {
-        :bundle => bundle.name,
-        :tags   => bundle.tags.join(' '),
-      }
-    end
-    
-    protected
-    #
-    # Prepares the params for a `bundles_set` request.
-    # 
-    # === Returns
-    # An +Hash+ with params to supply to the HTTP request.
-    # 
-    # Raises::
-    #
-    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?
+      
+      
+      # 
+      # 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
-      return { :bundle => bundle.name }
-    end
-    
-    protected
-    #
-    # Prepares the params for a `tags_rename` request.
-    # 
-    # === Returns
-    # An +Hash+ with params to supply to the HTTP request.
-    # 
-    # Raises::
-    #
-    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)
+      
+      # 
+      # 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
-      return { :old => from, :new => to }
-    end
-    
-    protected
-    #
-    # Prepares the params for a `post_*` request.
-    # 
-    # === Returns
-    # An +Hash+ with params to supply to the HTTP request.
-    # 
-    # Raises::
-    #
-    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
+      
+      # 
+      # 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
       
-      return params
-    end
-    
-    protected
-    #
-    # Prepares the params for a `post_add` request.
-    # 
-    # === Returns
-    # An +Hash+ with params to supply to the HTTP request.
-    # 
-    # Raises::
-    #
-    def prepare_posts_add_params(post_or_values)
-      post = case post_or_values
-      when WWW::Delicious::Post
-        post_or_values
-      when Hash
-        value = Post.new(post_or_values)
-        raise ArgumentError, 'Both `url` and `title` are required' unless value.api_valid?
-        value
-      else
-        raise ArgumentError, 'Expected `args` to be `WWW::Delicious::Post` or `Hash`'
+      # 
+      # 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
-      return post.to_params()
-    end
-    
-    protected
-    #
-    # Prepares the +bundle+ params.
-    # 
-    # If +name_or_bundle+ is a string,
-    # creates a new <tt>WWW::Delicious::Bundle</tt> with
-    # +name_or_bundle+ as name and a collection of +tags+.
-    # If +name_or_bundle+, +tags+ is ignored.
-    #
-    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_or_bundle.to_s(), tags)
+      
+      
+      # 
+      # 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
-      yield(bundle) if block_given?
-      return bundle
-    end
-    
-    protected
-    #
-    # Prepares the +tag+ params.
-    # 
-    # If +name_or_tag+ is a string,
-    # it creates a new <tt>WWW::Delicious::Tag</tt> with
-    # +name_or_tag+ as name.
-    #
-    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())
+      
+      # 
+      # 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
       
-      yield(tag) if block_given?
-      raise "Invalid `tag` value supplied" unless tag.api_valid?
-
-      return tag
-    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
     
-    protected
-    #
-    # Checks whether user given params are valid against valid params.
-    # 
-    # === Params
-    # params::
-    #   an +Hash+ with user given params to validate
-    # valid_params::
-    #   an +Array+ of valid params keys to check against
-    #   
-    # === 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:
-
-      public
+      
       #
-      # Returns the +xmlattr+ attribute value for given +node+.
+      # Returns the +xmlattr+ attribute value for current <tt>REXML::Element</tt>.
       # 
-      # If block is given and attrivute value is not nil
+      # If block is given and attribute value is not nil,
       # the content of the block is executed.
       # 
-      # === Params
-      # node::
-      #   The REXML::Element node context
-      # xmlattr::
-      #   A String corresponding to the name of the XML attribute to search for
-      #   
-      # === Return
-      # The value of the +xmlattr+ if the attribute exists for given +node+,
-      # +nil+ otherwise.
+      # === 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 attribute_value(xmlattr, &block) #:nodoc:
-        value = if attr = self.attribute(xmlattr.to_s())
-            attr.value()
+      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?
-        return value
+        value
       end
-
-    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