Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Ruby
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
test
CHANGELOG
Gemfile
LICENSE
README
Rakefile
trunkly.gemspec

README

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	
Something went wrong with that request. Please try again.