= rufus-jig

A HTTP client, greedy with JSON content, GETting conditionally.

Uses Patron (http://github.com/toland/patron) or em-http-request (http://github.com/igrigorik/em-http-request)
and Yajl-ruby (http://github.com/brianmario/yajl-ruby) whenever possible.

This library also contains some CouchDB helpers.

To select a HTTP transport layer for rufus-jig, just make sure you have loaded
the library before loading rufus-jig.

For Patron:

  require 'patron'
  require 'rufus/jig'

For em-http-request:

  require 'em-http'
  require 'rufus/jig'

Please not that em-http-request-0.2.2 and earlier don't support the PUT and DELETE
verbs. Until a newer gem is released you'll need to build the em-http-request gem
from source.

== examples

=== HTTP client

Let's say we have an hypothetical document server.

getting...

  require 'patron'
  require 'yajl'
  require 'rufus/jig'

  h = Rufus::Jig::Http.new('127.0.0.1', 4567)

  p @h.get('/document/xyz.json')
    #
    # => { "type" => "letter", "title" => "four birds" }
    #
    # if it's JSON, decodes it immediately

  r = @h.get('/document/xyz.txt')
  p [ r.status, r.body ]
    #
    # => [ 200, "letter:\n\nfour birds" ]
    #
    # else returns a Response object (currently the one of Patron)

  j = @h.get('/document', :content_type => 'application/json')
  j = @h.get('/document', :content_type => :json)
    #
    # 'Accepts' JSON

posting...

  r = @h.post(
    '/documents', '<doc>four birds</doc>', :content_type => 'application/xml')
  p [ r.status, r.body ]
    #
    # => [ 201, "created." ]


=== Couch helpers

For the real thing : http://github.com/couchrest/couchrest
There is also the excellent : http://github.com/langalex/couch_potato

  require 'patron'
  require 'yajl'
  require 'rufus/jig'

  c = Rufus::Jig::Couch.get_couch('127.0.0.1', 5984)
    # connecting to the local couch

  db = @c.put_db('rufus_jig_test')
    # let's create a database named 'rufus_jig_test'

  d = @db.put_doc('ct2', { 'item' => 'suit', 'brand' => 'suit company' })
  p [ d._id, d._rev, d['item'] ]
    #
    # => [ "ct2", "1-755f205df9f3c3a05849df3554ea24f7", "suit" ]

  # meanwhile, somebody else modifies the doc ...

  d['size'] = 'XL'

  d.put
    #
    # ouch, this gives us :
    # => conflict: Document update conflict. (Rufus::Jig::CouchError)

  d.get
  p [ d._id, d._rev, d['size'] ]
    #
    # re-getting the document
    #
    # => [ "ct2", "2-3a09eafe8739b54ab46105b96c1c69a2", "XL" ]

  d.delete
    # 
    # getting rid of the document

Some class methods (getting right to the stuff).

  require 'patron'
  require 'yajl'
  require 'rufus/jig'

  db = Rufus::Jig::Couch.get_db('http://127.0.0.1:5984/test_db')
    # returns a Rufus::Jig::CouchDatabase instance
    # or nil if the db doesn't exist

  db = Rufus::Jig::Couch.put_db('http://127.0.0.1:5984/test_db')
    # creates a new database, or raise an exception if the db already exists

  doc = Rufus::Jig::Couch.get_doc('http://127.0.0.1:5984/test_db/doc0')
    # returns a Rufus::Jig::CouchDocument instance
    # or nil the document doesn't exist

  # ...

Perhaps the right way to interact from rufus-jig to CouchDB is something like :

  db = Rufus::Jig::Couch.get_db('http://127.0.0.1:5984/test_db')

  doc = db.get_doc('doc0')

  doc['car'] = { 'brand' => 'BMW', 'model' => 'MarkIII' }

  doc.put

  # ...

Get a CouchDatabase instance then play from it.


== rdoc

http://rufus.rubyforge.org/rufus-jig/


== testing

At first, make sure to start the tiny sinatra test server :

  ruby test/server.rb

then do

  ruby test/test.rb


To test the CouchDB helpers, make you have a running Couch on http:/127.0.0.1:5984 then do

  ruby test/test.rb --couch

To test the em-http-request HTTP transport, make sure the sinatra server is running and then do:

  ruby test/test.rb -- --em


== mailing list

On the rufus-ruby list :

http://groups.google.com/group/rufus-ruby


== issue tracker

http://github.com/jmettraux/rufus-jig/issues


== irc

  irc.freenode.net #ruote


== the rest of Rufus

http://rufus.rubyforge.org


== authors

* John Mettraux, jmettraux@gmail.com, http://jmettraux.wordpress.com


== license

MIT