curb 0.1.4 → 0.7.15

data/README

@@ -1,106 +1,177 @@
-== Curb - Libcurl bindings for Ruby
+# Curb - Libcurl bindings for Ruby
 
-* http://curb.rubyforge.org/
-* http://rubyforge.org/projects/curb
++ [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/ .
+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' mode.
+Curb is a work-in-progress, and currently only supports libcurl's 'easy' and 'multi' modes.
 
-=== License
+## 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
+## You will need
 
-* A working Ruby installation (1.8+, tested with 1.8.5)
-* A working (lib)curl installation, with development stuff (7.5+, tested with 7.15)
-* A sane build environment
++ 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...
+## Installation...
 
 ... will usually be as simple as:
 
-	$ gem install curb
+    $ gem install curb
 	
 Or, if you downloaded the archive:	
 
-  $ rake install 
+    $ 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'
+    $ rake install EXTCONF_OPTS='--with-curl-dir=/path/to/libcurl --prefix=/what/ever'
 	
-Currently, Curb is tested only on GNU/Linux x86 - YMMV on other platforms.
+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 get in touch via the mailing
-list on Curb's Rubyforge page.
+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
+    $ rake doc
 
-=== Examples
+## Usage & examples
 
-Simple fetch via HTTP:
+Curb provides two classes:
 
-  c = Curl::Easy.perform("http://www.google.co.uk")
-  puts c.body_str
++ Curl::Easy - simple API, for day-to-day tasks.
++ Curl::Multi - more advanced API, for operating on multiple URLs simultaneously.
 
-Same thing, more manual:
+### Simple fetch via HTTP:
 
-  c = Curl::Easy.new("http://www.google.co.uk")
-  c.perform
-  puts c.body_str
+    c = Curl::Easy.perform("http://www.google.co.uk")
+    puts c.body_str
 
-Additional config:
+Same thing, more manual:
 
-  Curl::Easy.perform("http://www.google.co.uk") do |curl| 
-    curl.headers["User-Agent"] = "myapp-0.0"
-    curl.verbose = true
-  end
+    c = Curl::Easy.new("http://www.google.co.uk")
+    c.perform
+    puts c.body_str
 
-Same thing, more manual:
+### Additional config:
 
-  c = Curl::Easy.new("http://www.google.co.uk") do |curl| 
-    curl.headers["User-Agent"] = "myapp-0.0"
-    curl.verbose = true
-  end
-  
-  c.perform
+    Curl::Easy.perform("http://www.google.co.uk") do |curl| 
+      curl.headers["User-Agent"] = "myapp-0.0"
+      curl.verbose = true
+    end
 
-Supplying custom handlers:
+Same thing, more manual:
 
-  c = Curl::Easy.new("http://www.google.co.uk")
-  
-  c.on_body { |data| print(data) }
-  c.on_header { |data| print(data) }
+    c = Curl::Easy.new("http://www.google.co.uk") do |curl| 
+      curl.headers["User-Agent"] = "myapp-0.0"
+      curl.verbose = true
+    end
   
-  c.perform
-
-Reusing Curls:
+    c.perform
 
-  c = Curl::Easy.new
+### HTTP basic authentication:
 
-  ["http://www.google.co.uk", "http://www.ruby-lang.org/"].map do |url|
-    c.url = url
+    c = Curl::Easy.new("http://github.com/")
+    c.http_auth_types = :basic
+    c.username = 'foo'
+    c.password = 'bar'
     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')
+### Supplying custom handlers:
 
-HTTP POST file upload:
+    c = Curl::Easy.new("http://www.google.co.uk")
+  
+    c.on_body { |data| print(data) }
+    c.on_header { |data| print(data) }
+  
+    c.perform
 
-  c = Curl::Easy.new("http://my.rails.box/files/upload")
-  c.multipart_form_post = true
-  c.http_post(Curl::PostField.file('myfile.rb'))
+### 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 }
+        curl.on_success {|easy| puts "success, add more easy handles" }
+      end
+      m.add(c)
+    end
+   
+    m.perform do
+      puts "idling... can do some work here"
+    end
+   
+    requests.each do|url|
+      puts responses[url]
+    end
+
+### Easy Callbacks
+
+on_success:  is called when the response code is 20x
+on_failure: is called when the response code is not success, including redirects e.g. 30x
+on_complete: is called in all cases.

data/Rakefile

@@ -4,12 +4,6 @@ require 'rake/clean'
 require 'rake/testtask'
 require 'rake/rdoctask'
 
-begin
-  require 'rake/gempackagetask'
-rescue LoadError
-  $stderr.puts("Rubygems support disabled")
-end
-
 CLEAN.include '**/*.o'
 CLEAN.include "**/*.#{Config::MAKEFILE_CONFIG['DLEXT']}"
 CLOBBER.include 'doc'
@@ -21,8 +15,8 @@ def announce(msg='')
   $stderr.puts msg
 end
 
-desc "Default Task (Build packages)"
-task :default => :package
+desc "Default Task (Test project)"
+task :default => :test
 
 # Determine the current version of the software
 if File.read('ext/curb.h') =~ /\s*CURB_VERSION\s*['"](\d.+)['"]/
@@ -42,7 +36,8 @@ task :test_ver do
 end
 
 # Make tasks -----------------------------------------------------
-MAKECMD = ENV['MAKE_CMD'] || 'make'
+make_program = (/mswin/ =~ RUBY_PLATFORM) ? 'nmake' : 'make'
+MAKECMD = ENV['MAKE_CMD'] || make_program
 MAKEOPTS = ENV['MAKE_OPTS'] || ''
 
 CURB_SO = "ext/curb_core.#{Config::MAKEFILE_CONFIG['DLEXT']}"
@@ -61,13 +56,18 @@ def make(target = '')
 end
 
 # Let make handle dependencies between c/o/so - we'll just run it. 
-file CURB_SO => 'ext/Makefile' do
+file CURB_SO => (['ext/Makefile'] + Dir['ext/*.c'] + Dir['ext/*.h']) do
   m = make
   fail "Make failed (status #{m})" unless m == 0
 end
 
 desc "Compile the shared object"
-task :compile => CURB_SO
+task :compile => [CURB_SO]
+
+desc "Create the markdown file"
+task :markdown do
+  cp "README", "README.markdown"
+end
 
 desc "Install to your site_ruby directory"
 task :install => :alltests do
@@ -78,7 +78,11 @@ end
 # Test Tasks ---------------------------------------------------------
 task :ta => :alltests
 task :tu => :unittests
-task :test => :unittests
+task :test => [:rmpid,:unittests]
+
+task :rmpid do
+  FileUtils.rm_rf Dir.glob("tests/server_lock-*")
+end
 
 if ENV['RELTEST']
   announce "Release task testing - not running regression tests on alltests"
@@ -96,7 +100,7 @@ Rake::TestTask.new(:bugtests) do |t|
   t.test_files = FileList['tests/bug_*.rb']
   t.verbose = false
 end
-                          
+ 
 #Rake::TestTask.new(:funtests) do |t|
   #  t.test_files = FileList['test/func_*.rb']
   #t.warning = true
@@ -106,6 +110,25 @@ end
 task :unittests => :compile
 task :bugtests => :compile
 
+def has_gem?(file,name)
+  begin
+    require file
+    has_http_persistent = true
+  rescue LoadError => e
+    puts "Skipping #{name}"
+  end
+end
+
+desc "Benchmark curl against http://127.0.0.1/zeros-2k - will fail if /zeros-2k or 127.0.0.1 are missing"
+task :bench do
+  sh "ruby bench/curb_easy.rb"
+  sh "ruby bench/curb_multi.rb"
+  sh "ruby bench/nethttp_test.rb" if has_gem?("net/http/persistent","net-http-persistent")
+  sh "ruby bench/patron_test.rb" if has_gem?("patron","patron")
+  sh "ruby bench/typhoeus_test.rb" if has_gem?("typhoeus","typhoeus")
+  sh "ruby bench/typhoeus_hydra_test.rb" if has_gem?("typhoeus","typhoeus")
+end
+
 # RDoc Tasks ---------------------------------------------------------
 desc "Create the RDOC documentation"
 task :doc do
@@ -130,73 +153,63 @@ task :doc_upload => [ :doc ] do
   end
 end
 
-# Packaging ------------------------------------------------
-PKG_FILES = FileList[
-  'ext/*.rb',
-  'ext/*.c',
-  'ext/*.h',
-  'tests/**/*',
-  'samples/**/*',
-  'doc.rb',
-  '[A-Z]*',
-]
-
 if ! defined?(Gem)
   warn "Package Target requires RubyGEMs"
 else
-  spec = Gem::Specification.new do |s|
-    
-    #### Basic information.
-
-    s.name = 'curb'
-    s.version = PKG_VERSION
-    s.summary = "Ruby bindings for the libcurl(3) URL transfer library."
-    s.description = <<-EOF
-      C-language Ruby bindings for the libcurl(3) URL transfer library.
-    EOF
-    s.extensions = 'ext/extconf.rb'    
+  desc 'Generate gem specification'
+  task :gemspec do
+    require 'erb'
+    tspec = ERB.new(File.read(File.join(File.dirname(__FILE__),'lib','curb.gemspec.erb')))
+    File.open(File.join(File.dirname(__FILE__),'curb.gemspec'),'wb') do|f|
+      f << tspec.result
+    end
+  end
 
-    #### Which files are to be included in this gem? 
+  desc 'Build gem'
+  task :package => :gemspec do
+    require 'rubygems/specification'
+    spec_source = File.read File.join(File.dirname(__FILE__),'curb.gemspec')
+    spec = nil
+    # see: http://gist.github.com/16215
+    Thread.new { spec = eval("$SAFE = 3\n#{spec_source}") }.join
+    spec.validate
+    Gem::Builder.new(spec).build
+  end
 
-    s.files = PKG_FILES.to_a
+  task :static do
+    ENV['STATIC_BUILD'] = '1'
+  end
 
-    #### Load-time details
-    s.require_path = 'lib'
-    
-    #### Documentation and testing.
-    s.has_rdoc = true
-    s.extra_rdoc_files = Dir['ext/*.c'] << 'ext/curb.rb' << 'README' << 'LICENSE'
-    s.rdoc_options <<
-      '--title' <<  'Curb API' <<
-      '--main' << 'README'
-
-    s.test_files = Dir.glob('tests/tc_*.rb')
-    
-    #### Author and project details.
+  task :binary_gemspec => [:static, :compile] do
+    require 'erb'
+    ENV['BINARY_PACKAGE'] = '1'
+    tspec = ERB.new(File.read(File.join(File.dirname(__FILE__),'lib','curb.gemspec.erb')))
 
-    s.author = "Ross Bamford"
-    s.email = "curb-devel@rubyforge.org"
-    s.homepage = "http://curb.rubyforge.org"
-    s.rubyforge_project = "curb"
+    File.open(File.join(File.dirname(__FILE__),'curb-binary.gemspec'),'wb') do|f|
+      f << tspec.result
+    end
   end
-  
-  # Quick fix for Ruby 1.8.3 / YAML bug
-  if (RUBY_VERSION == '1.8.3')
-    def spec.to_yaml
-      out = super
-      out = '--- ' + out unless out =~ /^---/
-      out
-    end  
+
+  desc 'Strip extra strings from Binary'
+  task :binary_strip do
+    strip = '/usr/bin/strip'
+    if File.exist?(strip) and `#{strip} -h 2>&1`.match(/GNU/)
+      sh "#{strip} #{CURB_SO}"
+    end
   end
 
-  package_task = Rake::GemPackageTask.new(spec) do |pkg|
-    pkg.need_zip = true
-    pkg.need_tar_gz = true
-    pkg.package_dir = 'pkg'    
-  end      
+  desc 'Build gem'
+  task :binary_package => [:binary_gemspec, :binary_strip] do
+    require 'rubygems/specification'
+    spec_source = File.read File.join(File.dirname(__FILE__),'curb-binary.gemspec')
+    spec = nil
+    # see: http://gist.github.com/16215
+    Thread.new { spec = eval("$SAFE = 3\n#{spec_source}") }.join
+    spec.validate
+    Gem::Builder.new(spec).build
+  end
 end
 
-
 # --------------------------------------------------------------------
 # Creating a release
 desc "Make a new release (Requires SVN commit / webspace access)"

data/doc.rb

@@ -34,7 +34,7 @@ begin
     end
   end
  
-  system("rdoc --title='Curb - libcurl bindings for ruby' --main=README #{pp_srcdir}/*.c README LICENSE ext/curb.rb")
+  system("rdoc --title='Curb - libcurl bindings for ruby' --main=README #{pp_srcdir}/*.c README LICENSE lib/curb.rb")
 ensure
   rm_rf(tmpdir)
 end