Class: WWW::Delicious

Inherits:
Object
  • Object
show all
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/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, 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

Instance Method Summary collapse

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

Options

This class accepts an Hash with additional options. Here’s the list of valid keys:

:user_agent

User agent to display in HTTP requests.

Yields:

  • (_self)

Yield Parameters:



161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/www/delicious.rb', line 161

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)

  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

#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



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

def bundles_all()
  response = request(API_PATH_BUNDLES_ALL)
  return parse_bundles_all_response(response.body)
end

#bundles_delete(bundle_or_name) ⇒ Object

Deletes a bundle.

# 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



317
318
319
320
321
 
# File 'lib/www/delicious.rb', line 317

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



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



186
187
188
 
# File 'lib/www/delicious.rb', line 186

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



203
204
205
206
207
208
 
# File 'lib/www/delicious.rb', line 203

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.



416
417
418
419
420
 
# File 'lib/www/delicious.rb', line 416

def posts_add(post_or_values)
  params = prepare_posts_add_params(post_or_values.clone)
  response = request(API_PATH_POSTS_ADD, params)
  return parse_and_eval_execution_response(response.body)
end

#posts_all(options = {}) ⇒ Object

Returns a list of the most recent posts, filtered by argument.

Options

:tag

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



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

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

#posts_dates(options = {}) ⇒ Object

Returns a list of dates with the number of posts at each date.

Options

:tag

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



406
407
408
409
410
 
# File 'lib/www/delicious.rb', line 406

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

#posts_delete(url) ⇒ Object

Deletes a post from del.icio.us.

Params

url

the url of the item. It can be either an URI or a String.



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

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.

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



366
367
368
369
370
 
# File 'lib/www/delicious.rb', line 366

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)
end

#posts_recent(options = {}) ⇒ Object

Returns a list of the most recent posts, filtered by argument.

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).



380
381
382
383
384
 
# File 'lib/www/delicious.rb', line 380

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)
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.

Raises

WWW::Delicious::Error

Raises

WWW::Delicious::HTTPError

Raises

WWW::Delicious::ResponseError



332
333
334
335
 
# File 'lib/www/delicious.rb', line 332

def tags_get()
  response = request(API_PATH_TAGS_GET)
  return parse_tags_get_response(response.body)
end

#tags_rename(from_name_or_tag, to_name_or_tag) ⇒ Object

Renames an existing tag with a new tag name.

Raises

WWW::Delicious::Error

Raises

WWW::Delicious::HTTPError

Raises

WWW::Delicious::ResponseError



345
346
347
348
349
 
# File 'lib/www/delicious.rb', line 345

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

#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



257
258
259
260
 
# File 'lib/www/delicious.rb', line 257

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

#user_agent ⇒ Object

Returns current user agent string.



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

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

Returns:

  • (Boolean) 


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

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