# Curb - Libcurl bindings for Ruby
+ [rubyforge rdoc](http://curb.rubyforge.org/)
+ [rubyforge project](http://rubyforge.org/projects/curb)
+ [github project](http://github.com/taf2/curb/tree/master)
Curb (probably CUrl-RuBy or something) provides Ruby-language bindings for the
libcurl(3), a fully-featured client-side URL transfer library.
cURL and libcurl live at [http://curl.haxx.se/](http://curl.haxx.se/) .
Curb is a work-in-progress, and currently only supports libcurl's 'easy' and 'multi' modes.
## License
Curb is copyright (c)2006 Ross Bamford, and released under the terms of the
Ruby license. See the LICENSE file for the gory details.
## You will need
+ A working Ruby installation (1.8+, tested with 1.8.6, 1.8.7, 1.9.1, and 1.9.2)
+ A working (lib)curl installation, with development stuff (7.5+, tested with 7.19.x)
+ A sane build environment (e.g. gcc, make)
## Installation...
... will usually be as simple as:
$ gem install curb
Or, if you downloaded the archive:
$ rake install
If you have a wierd setup, you might need extconf options. In this case, pass
them like so:
$ rake install EXTCONF_OPTS='--with-curl-dir=/path/to/libcurl --prefix=/what/ever'
Curb is tested only on GNU/Linux x86 and Mac OSX - YMMV on other platforms.
If you do use another platform and experience problems, or if you can
expand on the above instructions, please report the issue at http://github.com/taf2/curb/issues
Curb has fairly extensive RDoc comments in the source. You can build the
documentation with:
$ rake doc
## Examples
### Simple fetch via HTTP:
c = Curl::Easy.perform("http://www.google.co.uk")
puts c.body_str
### Same thing, more manual:
c = Curl::Easy.new("http://www.google.co.uk")
c.perform
puts c.body_str
### Additional config:
Curl::Easy.perform("http://www.google.co.uk") do |curl|
curl.headers["User-Agent"] = "myapp-0.0"
curl.verbose = true
end
### Same thing, more manual:
c = Curl::Easy.new("http://www.google.co.uk") do |curl|
curl.headers["User-Agent"] = "myapp-0.0"
curl.verbose = true
end
c.perform
### Supplying custom handlers:
c = Curl::Easy.new("http://www.google.co.uk")
c.on_body { |data| print(data) }
c.on_header { |data| print(data) }
c.perform
### Reusing Curls:
c = Curl::Easy.new
["http://www.google.co.uk", "http://www.ruby-lang.org/"].map do |url|
c.url = url
c.perform
c.body_str
end
### HTTP POST form:
c = Curl::Easy.http_post("http://my.rails.box/thing/create",
Curl::PostField.content('thing[name]', 'box'),
Curl::PostField.content('thing[type]', 'storage'))
### HTTP POST file upload:
c = Curl::Easy.new("http://my.rails.box/files/upload")
c.multipart_form_post = true
c.http_post(Curl::PostField.file('myfile.rb'))
### Multi Interface (Basic HTTP GET):
# make multiple GET requests
easy_options = {:follow_location => true}
multi_options = {:pipeline => true}
Curl::Multi.get('url1','url2','url3','url4','url5', easy_options, multi_options) do|easy|
# do something interesting with the easy response
puts easy.last_effective_url
end
### Multi Interface (Basic HTTP POST):
# make multiple POST requests
easy_options = {:follow_location => true, :multipart_form_post => true}
multi_options = {:pipeline => true}
url_fields = [
{ :url => 'url1', :post_fields => {'f1' => 'v1'} },
{ :url => 'url2', :post_fields => {'f1' => 'v1'} },
{ :url => 'url3', :post_fields => {'f1' => 'v1'} }
]
Curl::Multi.post(url_fields, easy_options, multi_options) do|easy|
# do something interesting with the easy response
puts easy.last_effective_url
end
### Multi Interface (Advanced):
responses = {}
requests = ["http://www.google.co.uk/", "http://www.ruby-lang.org/"]
m = Curl::Multi.new
# add a few easy handles
requests.each do |url|
responses[url] = ""
c = Curl::Easy.new(url) do|curl|
curl.follow_location = true
curl.on_body{|data| responses[url] << data; data.size }
end
m.add(c)
end
m.perform do
puts "idling... can do some work here, including add new requests"
end
requests.each do|url|
puts responses[url]
end
) is private.
