Class: WWW::Delicious
- Defined in:
- lib/www/delicious.rb,
lib/www/delicious/tag.rb,
lib/www/delicious/post.rb,
lib/www/delicious/bundle.rb,
lib/www/delicious/errors.rb,
lib/www/delicious/element.rb,
lib/www/delicious/version.rb
Overview
WWW::Delicious
WWW::Delicious is a Ruby client for 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
- Category
-
WWW
- Package
-
WWW::Delicious
- Author
-
Simone Carletti <[email protected]>
Defined Under Namespace
Modules: Version, XMLUtils Classes: Bundle, Element, Error, HTTPError, Post, ResponseError, Tag
Constant Summary collapse
- NAME =
'WWW::Delicious'
- GEM =
'www-delicious'
- AUTHOR =
'Simone Carletti <[email protected]>'
- VERSION =
defined?(Version) ? Version::STRING : nil
- STATUS =
'alpha'
- BUILD =
''.match(/(\d+)/).to_a.first
- API_BASE_URI =
API Base URL
'https://api.del.icio.us'
- API_PATH_UPDATE =
API Path Update
'/v1/posts/update'
- API_PATH_BUNDLES_ALL =
API Path All Bundles
'/v1/tags/bundles/all'
- API_PATH_BUNDLES_SET =
API Path Set Bundle
'/v1/tags/bundles/set'
- API_PATH_BUNDLES_DELETE =
API Path Delete Bundle
'/v1/tags/bundles/delete'
- API_PATH_TAGS_GET =
API Path Get Tags
'/v1/tags/get'
- API_PATH_TAGS_RENAME =
API Path Rename Tag
'/v1/tags/rename'
- API_PATH_POSTS_GET =
API Path Get Posts
'/v1/posts/get'
- API_PATH_POSTS_RECENT =
API Path Recent Posts
'/v1/posts/recent'
- API_PATH_POSTS_ALL =
API Path All Posts
'/v1/posts/all'
- API_PATH_POSTS_DATES =
API Path Posts by Dates
'/v1/posts/dates'
- API_PATH_POSTS_ADD =
API Path Add Post
'/v1/posts/add'
- API_PATH_POSTS_DELETE =
API Path Delete Post
'/v1/posts/delete'
- SECONDS_BEFORE_NEW_REQUEST =
Time to wait before sending a new request, in seconds
1
- TIME_CONVERTER =
Time converter converts a Time instance into the format requested by Delicious API
lambda { |time| time.iso8601() }
Instance Attribute Summary collapse
-
#base_uri ⇒ Object
readonly
base URI for del.icio.us API.
-
#password ⇒ Object
readonly
del.icio.us account password.
-
#username ⇒ Object
readonly
del.icio.us account username.
Instance Method Summary collapse
-
#bundles_all ⇒ Object
Retrieves all of a user’s bundles and returns an array of
WWW::Delicious::Bundle
. -
#bundles_delete(bundle_or_name) ⇒ Object
Deletes
bundle_or_name
bundle from del.icio.us. -
#bundles_set(bundle_or_name, tags = []) ⇒ Object
Assignes a set of tags to a single bundle, wipes away previous settings for bundle.
-
#http_client ⇒ Object
Returns the reference to current
@http_client
. -
#http_client=(client) ⇒ Object
Sets the internal
@http_client
toclient
. -
#initialize(username, password, options = {}) {|_self| ... } ⇒ Delicious
constructor
Constructs a new
WWW::Delicious
object with givenusername
andpassword
. -
#posts_add(post_or_values) ⇒ Object
Add a post to del.icio.us.
-
#posts_all(options = {}) ⇒ Object
Returns a list of all posts, filtered by argument.
-
#posts_dates(options = {}) ⇒ Object
Returns a list of dates with the number of posts at each date.
-
#posts_delete(url) ⇒ Object
Deletes the post matching given
url
from del.icio.us. -
#posts_get(options = {}) ⇒ Object
Returns an array of
WWW::Delicious::Post
matchingoptions
. -
#posts_recent(options = {}) ⇒ Object
Returns a list of the most recent posts, filtered by argument.
-
#tags_get ⇒ Object
Retrieves the list of tags and number of times used by the user and returns an array of
WWW::Delicious::Tag
. -
#tags_rename(from_name_or_tag, to_name_or_tag) ⇒ Object
Renames an existing tag with a new tag name.
-
#update ⇒ Object
Checks to see when a user last posted an item and returns the last update
Time
for the user. -
#user_agent ⇒ Object
Returns current user agent string.
-
#valid_account? ⇒ Boolean
Returns true if given account credentials are valid.
Constructor Details
#initialize(username, password, options = {}) {|_self| ... } ⇒ Delicious
Constructs a new WWW::Delicious
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:
:user_agent
-
User agent to display in HTTP requests.
:base_uri
-
The base URI to del.icio.us API.
173 174 175 176 177 178 179 180 181 182 183 184 |
# File 'lib/www/delicious.rb', line 173 def initialize(username, password, = {}, &block) # :yields: delicious @username, @password = username.to_s, password.to_s # set API base URI @base_uri = URI.parse([:base_uri] || API_BASE_URI) init_user_agent() init_http_client() yield self if block_given? self # ensure to always return self even if block is given end |
Instance Attribute Details
#base_uri ⇒ Object (readonly)
base URI for del.icio.us API
99 100 101 |
# File 'lib/www/delicious.rb', line 99 def base_uri @base_uri end |
#password ⇒ Object (readonly)
del.icio.us account password
96 97 98 |
# File 'lib/www/delicious.rb', line 96 def password @password end |
#username ⇒ Object (readonly)
del.icio.us account username
93 94 95 |
# File 'lib/www/delicious.rb', line 93 def username @username end |
Instance Method Details
#bundles_all ⇒ Object
Retrieves all of a user’s bundles and returns an array of WWW::Delicious::Bundle
.
d.bundles_all() # => [#<WWW::Delicious::Bundle>, #<WWW::Delicious::Bundle>, ...]
d.bundles_all() # => []
- Raises
-
WWW::Delicious::Error
- Raises
-
WWW::Delicious::HTTPError
- Raises
-
WWW::Delicious::ResponseError
280 281 282 283 |
# File 'lib/www/delicious.rb', line 280 def bundles_all() response = request(API_PATH_BUNDLES_ALL) return parse_bundle_collection(response.body) end |
#bundles_delete(bundle_or_name) ⇒ Object
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
325 326 327 328 329 |
# File 'lib/www/delicious.rb', line 325 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 |
#bundles_set(bundle_or_name, tags = []) ⇒ Object
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
300 301 302 303 304 |
# File 'lib/www/delicious.rb', line 300 def bundles_set(bundle_or_name, = []) params = prepare_bundles_set_params(bundle_or_name, ) response = request(API_PATH_BUNDLES_SET, params) return parse_and_eval_execution_response(response.body) end |
#http_client ⇒ Object
Returns the reference to current @http_client
. 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
197 198 199 |
# File 'lib/www/delicious.rb', line 197 def http_client() return @http_client end |
#http_client=(client) ⇒ Object
Sets the internal @http_client
to client
.
# nil client
obj.http_client = nil
# http client
obj.http_client = Net::HTTP.new()
# invalid client
obj.http_client = 'foo' # => ArgumentError
213 214 215 216 217 218 |
# File 'lib/www/delicious.rb', line 213 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 |
#posts_add(post_or_values) ⇒ Object
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!')
475 476 477 478 479 |
# File 'lib/www/delicious.rb', line 475 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 |
#posts_all(options = {}) ⇒ Object
435 436 437 438 439 |
# File 'lib/www/delicious.rb', line 435 def posts_all( = {}) params = prepare_posts_params(.clone, [:tag]) response = request(API_PATH_POSTS_ALL, params) return parse_post_collection(response.body) end |
#posts_dates(options = {}) ⇒ Object
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
:tag
-
a tag to filter by. It can be either a
WWW::Delicious::Tag
or aString
.
456 457 458 459 460 |
# File 'lib/www/delicious.rb', line 456 def posts_dates( = {}) params = prepare_posts_params(.clone, [:tag]) response = request(API_PATH_POSTS_DATES, params) return parse_posts_dates_response(response.body) end |
#posts_delete(url) ⇒ Object
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/')
495 496 497 498 499 |
# File 'lib/www/delicious.rb', line 495 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 |
#posts_get(options = {}) ⇒ Object
Returns an array of WWW::Delicious::Post
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
:tag
-
a tag to filter by. It can be either a
WWW::Delicious::Tag
or aString
. :dt
-
a
Time
with a date to filter by. :url
-
a valid URI to filter by. It can be either an instance of
URI
or aString
. - Raises
-
WWW::Delicious::Error
- Raises
-
WWW::Delicious::HTTPError
- Raises
-
WWW::Delicious::ResponseError
396 397 398 399 400 |
# File 'lib/www/delicious.rb', line 396 def posts_get( = {}) params = prepare_posts_params(.clone, [:dt, :tag, :url]) response = request(API_PATH_POSTS_GET, params) return parse_post_collection(response.body) end |
#posts_recent(options = {}) ⇒ Object
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
:tag
-
a tag to filter by. It can be either a
WWW::Delicious::Tag
or aString
. :count
-
number of items to retrieve. (default: 15, maximum: 100).
416 417 418 419 420 |
# File 'lib/www/delicious.rb', line 416 def posts_recent( = {}) params = prepare_posts_params(.clone, [:count, :tag]) response = request(API_PATH_POSTS_RECENT, params) return parse_post_collection(response.body) end |
#tags_get ⇒ Object
Retrieves the list of tags and number of times used by the user and returns an array of WWW::Delicious::Tag
.
d.() # => [#<WWW::Delicious::Tag>, #<WWW::Delicious::Tag>, ...]
d.() # => []
- Raises
-
WWW::Delicious::Error
- Raises
-
WWW::Delicious::HTTPError
- Raises
-
WWW::Delicious::ResponseError
343 344 345 346 |
# File 'lib/www/delicious.rb', line 343 def () response = request(API_PATH_TAGS_GET) return parse_tag_collection(response.body) end |
#tags_rename(from_name_or_tag, to_name_or_tag) ⇒ Object
362 363 364 365 366 |
# File 'lib/www/delicious.rb', line 362 def (from_name_or_tag, to_name_or_tag) 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 |
#update ⇒ Object
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
263 264 265 266 |
# File 'lib/www/delicious.rb', line 263 def update() response = request(API_PATH_UPDATE) return parse_update_response(response.body) end |
#user_agent ⇒ Object
Returns current user agent string.
221 222 223 |
# File 'lib/www/delicious.rb', line 221 def user_agent() return @headers['User-Agent'] end |
#valid_account? ⇒ Boolean
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
244 245 246 247 248 249 250 |
# File 'lib/www/delicious.rb', line 244 def valid_account? update() return true rescue HTTPError => e return false if e. =~ /invalid username or password/i raise end |