ideaoforder-www-delicious 0.2.0

data/CHANGELOG.rdoc

@@ -0,0 +1,46 @@
+= Changelog
+
+
+== development
+
+* CHANGED: Don't use File.dirname(__FILE__) in require statement to prevent recursive inclusions.
+
+
+== 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
+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.rdoc

@@ -0,0 +1,209 @@
+= WWW::Delicious
+
+  http://www-delicious.rubyforge.org/
+  http://code.simonecarletti.com/www-delicious
+
+
+== Description
+
+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.
+
+
+== Authors
+
+* {Simone Carletti}[http://www.simonecarletti.com/] <weppos@weppos.net>
+  If you like this software, consider to {recommend me}[http://www.workingwithrails.com/person/11967-simone-carletti] at Working with Rails.
+
+
+== Website
+
+* {Homepage}[http://code.simonecarletti.com/www-delicious]
+* {API}[http://www-delicious.rubyforge.org/]
+
+
+== Source
+
+* {at GitHub}[http://github.com/weppos/www-delicious/]
+* {at RubyForge}[http://rubyforge.org/projects/www-delicious/]
+
+
+== 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.
+
+
+== 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.
+
+
+== Usage
+
+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 with the 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 delicious instance to call on of the API methods available.
+
+
+=== 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')
+
+
+== FeedBack and Bug reports
+
+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/www-delicious.
+
+
+== Changelog
+
+See CHANGELOG for details.
+

data/Rakefile

@@ -0,0 +1,55 @@
+require 'rubygems'
+require 'echoe'
+
+$LOAD_PATH.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 |fl|
+  fl.exclude 'TODO'
+  fl.include %w(README.rdoc CHANGELOG.rdoc LICENSE.rdoc)
+  fl.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  = ["-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
+
+
+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/lib/www/delicious/bundle.rb

@@ -0,0 +1,73 @@
+# 
+# = 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 'www/delicious/element'
+
+
+module WWW
+  class Delicious
+
+    #
+    # = Delicious Bundle
+    # 
+    # Represents a single Bundle element.
+    #
+    class Bundle < Element
+      
+      # The name of the bundle.
+      attr_accessor :name
+      
+      # The collection of <tt>WWW::Delicious::Tags</tt>.
+      attr_accessor :tags
+      
+      
+      # Returns value for <tt>name</tt> attribute.
+      # Value is always normalized as lower string.
+      def name
+        @name.to_s.strip unless @name.nil?
+      end
+      
+      #
+      # Returns a string representation of this Bundle.
+      # In case name is nil this method will return an empty string.
+      #
+      def to_s
+        name.to_s
+      end
+      
+      
+      class << self
+
+        # 
+        # Creates and returns new instance from a REXML +element+.
+        # 
+        # Implements Element#from_rexml.
+        # 
+        def from_rexml(element)
+          raise ArgumentError, "`element` expected to be a `REXML::Element`" unless element.kind_of? REXML::Element
+          self.new do |instance|
+            instance.name  = element.if_attribute_value(:name)
+            # FIXME: value must be converted to array of Tag
+            instance.tags  = element.if_attribute_value(:tags) { |value| value.split(' ') }
+          end
+        end
+
+      end
+
+    end
+
+  end
+end

data/lib/www/delicious/element.rb

@@ -0,0 +1,73 @@
+# 
+# = 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$
+#++
+
+
+module WWW
+  class Delicious
+
+    # 
+    # = Abstract structure
+    # 
+    # Represent the most basic structure all Struc(s) must inherith from.
+    # 
+    class Element
+      
+      #
+      # Initializes a new instance and populate attributes from +attrs+.
+      # 
+      #   class User < Element
+      #     attr_accessor :first_name
+      #     attr_accessor :last_name
+      #   end
+      # 
+      #   User.new
+      #   User.new(:first_name => 'foo')
+      #   User.new(:first_name => 'John', :last_name => 'Doe')
+      # 
+      # You can even use a block.
+      # The following statements are equals:
+      # 
+      #   User.new(:first_name => 'John', :last_name => 'Doe')
+      # 
+      #   User.new do |user|
+      #     user.first_name => 'John'
+      #     user.last_name  => 'Doe'
+      #   end
+      # 
+      # Warning. In order to set an attribute a valid attribute writer must be available,
+      # otherwise this method will raise an exception.
+      #
+      def initialize(attrs = {}, &block)
+        attrs.each { |key, value| self.send("#{key}=".to_sym, value) }
+        yield self if block_given?
+        self
+      end
+      
+      
+      class << self
+        
+        # 
+        # Creates and returns new instance from a REXML +element+.
+        # 
+        def from_rexml(element, options)
+          raise NotImplementedError
+        end
+        
+      end
+      
+    end
+    
+  end
+end

data/lib/www/delicious/errors.rb

@@ -0,0 +1,46 @@
+# 
+# = 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$
+#++
+
+
+module WWW
+  class Delicious
+
+    
+    #
+    # = WWW::Delicious::Error
+    # 
+    # Base exception for all WWW::Delicious errors.
+    #
+    class Error < StandardError; end
+
+    #
+    # = WWW::Delicious::HTTPError
+    # 
+    # HTTP connection related error.
+    # Raised when an HTTP request fails or in case of unexpected behavior.
+    #
+    class HTTPError < Error; end
+
+    #
+    # = WWW::Delicious::ResponseError
+    # 
+    # Response related error.
+    # Usually raised in case of a malformed, invalid or empty XML response.
+    #
+    class ResponseError < Error; end
+    
+    
+  end
+end

data/lib/www/delicious/post.rb

@@ -0,0 +1,123 @@
+# 
+# = WWW::Delicious
+#
+# Ruby client for del.icio.us API.
+# 
+#
+# Category::   WWW
+# Package::    WWW::Delicious
+# Subpackage:: WWW::Delicious::Post
+# Author::     Simone Carletti <weppos@weppos.net>
+#
+#--
+# SVN: $Id$
+#++
+
+
+require 'www/delicious/element'
+
+
+module WWW
+  class Delicious
+    
+    class Post < Element
+      
+      # The Post URL
+      attr_accessor :url
+      
+      # The title of the Post
+      attr_accessor :title
+      
+      # The extended description for the Post
+      attr_accessor :notes
+      
+      # The number of other users who saved this Post
+      attr_accessor :others
+      
+      # The unique Id for this Post
+      attr_accessor :uid
+      
+      # Tags for this Post
+      attr_accessor :tags
+      
+      # Timestamp this Post was last saved at
+      attr_accessor :time
+      
+      # Whether this Post must replace previous version of the same Post.
+      attr_accessor :replace
+      
+      # Whether this Post is private
+      attr_accessor :shared
+      
+      
+      # Returns the value for <tt>shared</tt> attribute.
+      def shared
+        !(@shared == false)
+      end
+      
+      # Returns the value for <tt>replace</tt> attribute.
+      def replace
+        !(@replace == false)
+      end
+      
+      # Returns a params-style representation suitable for API calls.
+      def to_params()
+        params = {}
+        params[:url]          = url # this could/should convert back from URI object (MD)
+        params[:description]  = title
+        params[:extended]     = notes if notes
+        params[:shared]       = 'no' if !shared # (MD)
+        params[:tags]         = tags.join(' ') if tags.respond_to? :join
+        params[:replace]      = replace
+        params[:dt]           = WWW::Delicious::TIME_CONVERTER.call(time) if time
+        params
+      end
+      
+      
+      #
+      # Returns whether this object is valid for an API request.
+      # 
+      # To be valid +url+ and +title+ must not be empty.
+      # 
+      # === Examples
+      # 
+      #   post = WWW::Delicious::Post.new(:url => 'http://localhost', :title => 'foo')
+      #   post.api_valid?
+      #   # => true
+      #
+      #   post = WWW::Delicious::Post.new(:url => 'http://localhost')
+      #   post.api_valid?
+      #   # => false
+      #
+      def api_valid?
+        return !(url.nil? or url.empty? or title.nil? or title.empty?)
+      end
+      
+      
+      class << self
+        
+        # 
+        # Creates and returns new instance from a REXML +element+.
+        # 
+        # Implements Element#from_rexml.
+        # 
+        def from_rexml(element)
+          raise ArgumentError, "`element` expected to be a `REXML::Element`" unless element.kind_of? REXML::Element
+          self.new do |instance|
+            instance.url    = element.if_attribute_value(:href) #{ |v| URI.parse(v) } - this was breaking a lot of the API calls (MD)
+            instance.title  = element.if_attribute_value(:description)
+            instance.notes  = element.if_attribute_value(:extended)
+            instance.others = element.if_attribute_value(:others).to_i # cast nil to 0
+            instance.uid    = element.if_attribute_value(:hash)
+            instance.tags   = element.if_attribute_value(:tag)  { |v| v.split(' ') }.to_a
+            instance.time   = element.if_attribute_value(:time) { |v| Time.parse(v) }
+            instance.shared = element.if_attribute_value(:shared) { |v| v == 'no' ? false : true }
+          end
+        end
+        
+      end
+      
+    end
+    
+  end
+end