Class: WWW::Delicious

Inherits:
Object show all
Defined in:
lib/www/delicious.rb,
lib/www/delicious/tag.rb,
lib/www/delicious/post.rb,
lib/www/delicious/errors.rb,
lib/www/delicious/bundle.rb,
lib/www/delicious/version.rb,
lib/www/delicious/element.rb

Overview

WWW::Delicious

WWW::Delicious is a Ruby client for delicious.com 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

Defined Under Namespace

Modules: Version, XMLUtils Classes: Bundle, Element, Error, HTTPError, Post, ResponseError, Tag

Constant Summary

NAME =
"WWW::Delicious"
GEM =
"www-delicious"
AUTHORS =
["Simone Carletti <weppos@weppos.net>"]
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 }
VERSION =
Version::STRING

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Delicious) initialize(username, password, options = {}) {|_self| ... }

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 delicious.com 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.

Yields:

  • (_self)

Yield Parameters:



166
167
168
169
170
171
172
173
174
175
176
177
# File 'lib/www/delicious.rb', line 166

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

Instance Attribute Details

- (Object) base_uri (readonly)

base URI for del.icio.us API



92
93
94
# File 'lib/www/delicious.rb', line 92

def base_uri
  @base_uri
end

- (Object) password (readonly)

del.icio.us account password



89
90
91
# File 'lib/www/delicious.rb', line 89

def password
  @password
end

- (Object) username (readonly)

del.icio.us account username



86
87
88
# File 'lib/www/delicious.rb', line 86

def username
  @username
end

Instance Method Details

- (Object) bundles_all

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



276
277
278
279
# File 'lib/www/delicious.rb', line 276

def bundles_all
  response = request(API_PATH_BUNDLES_ALL)
  parse_bundle_collection(response.body)
end

- (Object) bundles_delete(bundle_or_name)

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



321
322
323
324
325
# File 'lib/www/delicious.rb', line 321

def bundles_delete(bundle_or_name)
  params = prepare_bundles_delete_params(bundle_or_name)
  response = request(API_PATH_BUNDLES_DELETE, params)
  parse_and_eval_execution_response(response.body)
end

- (Object) bundles_set(bundle_or_name, tags = [])

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



296
297
298
299
300
# File 'lib/www/delicious.rb', line 296

def bundles_set(bundle_or_name, tags = [])
  params = prepare_bundles_set_params(bundle_or_name, tags)
  response = request(API_PATH_BUNDLES_SET, params)
  parse_and_eval_execution_response(response.body)
end

- (Object) http_client

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


190
191
192
# File 'lib/www/delicious.rb', line 190

def http_client
  @http_client
end

- (Object) http_client=(client)

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


206
207
208
209
210
211
# File 'lib/www/delicious.rb', line 206

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

- (Object) posts_add(post_or_values)

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!')


471
472
473
474
475
# File 'lib/www/delicious.rb', line 471

def posts_add(post_or_values)
  params = prepare_param_post(post_or_values).to_params
  response = request(API_PATH_POSTS_ADD, params)
  parse_and_eval_execution_response(response.body)
end

- (Object) posts_all(options = {})

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

:tag

a tag to filter by. It can be either a WWW::Delicious::Tag or a String.



431
432
433
434
435
# File 'lib/www/delicious.rb', line 431

def posts_all(options = {})
  params = prepare_posts_params(options.clone, [:tag])
  response = request(API_PATH_POSTS_ALL, params)
  parse_post_collection(response.body)
end

- (Object) posts_dates(options = {})

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 a String.



452
453
454
455
456
# File 'lib/www/delicious.rb', line 452

def posts_dates(options = {})
  params = prepare_posts_params(options.clone, [:tag])
  response = request(API_PATH_POSTS_DATES, params)
  parse_posts_dates_response(response.body)
end

- (Object) posts_delete(url)

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/')


491
492
493
494
495
# File 'lib/www/delicious.rb', line 491

def posts_delete(url)
  params = prepare_posts_params({ :url => url }, [:url])
  response = request(API_PATH_POSTS_DELETE, params)
  parse_and_eval_execution_response(response.body)
end

- (Object) posts_get(options = {})

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 a String.

: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 a String.

Raises

WWW::Delicious::Error

Raises

WWW::Delicious::HTTPError

Raises

WWW::Delicious::ResponseError



392
393
394
395
396
# File 'lib/www/delicious.rb', line 392

def posts_get(options = {})
  params = prepare_posts_params(options.clone, [:dt, :tag, :url])
  response = request(API_PATH_POSTS_GET, params)
  parse_post_collection(response.body)
end

- (Object) posts_recent(options = {})

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 a String.

:count

number of items to retrieve. (default: 15, maximum: 100).



412
413
414
415
416
# File 'lib/www/delicious.rb', line 412

def posts_recent(options = {})
  params = prepare_posts_params(options.clone, [:count, :tag])
  response = request(API_PATH_POSTS_RECENT, params)
  parse_post_collection(response.body)
end

- (Object) tags_get

Retrieves the list of tags and number of times used by the user and returns an array of WWW::Delicious::Tag.

d.tags_get # => [#<WWW::Delicious::Tag>, #<WWW::Delicious::Tag>, ...]
d.tags_get # => []

Raises

WWW::Delicious::Error

Raises

WWW::Delicious::HTTPError

Raises

WWW::Delicious::ResponseError



339
340
341
342
# File 'lib/www/delicious.rb', line 339

def tags_get
  response = request(API_PATH_TAGS_GET)
  parse_tag_collection(response.body)
end

- (Object) tags_rename(from_name_or_tag, to_name_or_tag)

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



358
359
360
361
362
# File 'lib/www/delicious.rb', line 358

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)
  parse_and_eval_execution_response(response.body)
end

- (Object) update

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



259
260
261
262
# File 'lib/www/delicious.rb', line 259

def update
  response = request(API_PATH_UPDATE)
  parse_update_response(response.body)
end

- (Object) user_agent

Returns current user agent string.



214
215
216
# File 'lib/www/delicious.rb', line 214

def user_agent
  @headers['User-Agent']
end

- (Boolean) valid_account?

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



237
238
239
240
241
242
243
244
245
246
# File 'lib/www/delicious.rb', line 237

def valid_account?
  update
  true
rescue HTTPError => e
  if e.message =~ /invalid username or password/i
    false
  else
    raise
  end
end