This Trunkly ruby client library has been developed by Filippo Diotalevi (filippo@diotalevi.com)
and it's distributed under the terms of the Apache License v.2.0
------------------------------------------------------------------------------------------------------

This project provides a Ruby client to connect to the Trunkly API.

You don't need to be a Trunkly registered user to use the API, but without your API KEY you won't be able to post new links.

To register to Trunk.ly go to http://trunk.ly/ and click on Sign Up.
Once you are signed up go on your profile page and copy the API KEY somewhere; you will use it later.


HOW TO USE THE RUBY CLIENT

0) Installation

$ gem install trunkly

In your file or irb
$ require "rubygems"  #ruby 1.8 only
$ require "trunkly"

1) Retrieve the latest links shared by a user

t = Trunkly::Trunkly.new
links = t.links(:user => 'fdiotalevi')    #this retrieves my 100 latest links

Alternatively, you can use the dynamic method  links_by_<user-name-here>, f.i.

links = t.links_by_fdiotalevi    #this retrieves my 100 latest links

The method 'links' returns an array of Trunkly::Link. The meaningful instance variables of Link are
- url 
- title
- tags #comma separated list of tags
- note #description of the link
- dt_string #date when the link was shared


2) Retrieve your latest links

You can retrieve your links in two ways:
a) using the method explained in section 1 and your username

b) using your API Key like in the example

t = Trunkly::Trunkly.new('my_api_key_goes_here')
links = t.links    #this retrieves my 100 latest links


3) Advanced search

Some examples of advanced search

t = Trunkly::Trunkly.new
links = t.links(:user => 'fdiotalevi', :tags => 'ruby')  #retrieves links shared with tag ruby   
links = t.links(:user => 'fdiotalevi', :tags => 'ruby,rails')  #retrieves links shared with tag ruby and rails
links = t.links(:since_time => '2011-01-01 00:00:00') #retrieves links shared after 01/01/2011. Date format is '%Y-%m-%d %H:%M:%S'

You can mix and match all the search parameters in your query

If you use the dynamic method, you can of course omit the user, f.i.

links = t.links_by_fdiotalevi(:tags => 'ruby')  #retrieves links shared with tag ruby   


4) Pagination

By default Trunkly returns the 100 latest links. You can specify exactly how many results you want and paginate them:

t = Trunkly::Trunkly.new
t.links(:count => 10)    #returns the 10 latest links
t.links(:count => 10, :page => 1)  #returns the 2nd page of results (so results from 11..20)

An even shorter method is, after the first invocation, use the 'next_page' and 'prev_page' method

t = Trunkly::Trunkly.new
t.links(:count => 10)    #returns the 10 latest links
t.next_page   		#returns results from 11..20
t.prev_page			#returns restult 1..10


5) Timeline

To get the list of your friends link (called Timeline)

t = Trunkly::Trunkly.new('my_api_key_goes_here')
links = t.timeline    #this retrieves 100 links

You can apply the usual filters and pagination parameters


6) Save a link

Saving a link is very simple

t = Trunkly::Trunkly.new('my_api_key_goes_here') #you need an API key to save a link
t.save do |it|
  it.url = 'http://github.com'
  it.title = 'GitHub'
  it.tags = ['git','vcs']
  it.note = 'GitHub website'
end

Note that 'tags' and 'note' are optional parameters.

Alternative way (longer and dumber):

t = Trunkly::Trunkly.new('my_api_key_goes_here') #you need an API key to save a link
it = Trunkly::Link.new
it.url = 'http://github.com'
it.title = 'GitHub'
it.tags = ['git','vcs']
it.note = 'GitHub website'
t.save it

Alternative alternative way:

t = Trunkly::Trunkly.new('my_api_key_goes_here') #you need an API key to save a link
it = Trunkly::Link.new(
	{:url => 'http://github.com', :title=> 'GitHub', :tags => ['git','vcs'], :note => 'GitHub website'}
	)
t.save it