fluidinfo 0.5.0 → 0.5.1

data/README.rdoc

@@ -1,35 +1,41 @@
-= fluidinfo
+= fluidinfo.rb
 
-Fluidinfo.rb provides a simple interface to fluidinfo.
++fluidinfo.rb+ provides a simple interface to {Fluidinfo}[http://www.fluidinfo.com].
 
 == Simple Example
 
- >> require 'fluidinfo'
- >> fluid = Fluidinfo::Client.new
- >> fluid.get '/objects', :query => 'has gridaphobe/met'
+ >> require "fluidinfo"
+ >> fi = Fluidinfo::Client.new
+ >> fi.get "/objects", :query => "has gridaphobe/met"
  => {"ids"=>["fa0bb30b-d1c2-4438-b65c-d86bbb1a44cd"]}
 
-For now, check out Fluidinfo's extensive 
-{documentation}[http://api.fluidinfo.com/] for explanations of each API call.
+== Authentication
 
+ >> fi = Fluidinfo::Client.new :user => "user", :password => "password"
+ >> fi.post "/objects", :body => {:about => "Pulp Fiction"}
+ >> fi.put "/about/Pulp Fiction/user/rating", :body => 5
 
-== Contributing to fluidinfo
++fluidinfo.rb+ is a wrapper around the
+{RestClient}[http://github.com/archiloque/rest-client] gem, and provides a
+similar API. For more details read the {official documentation}[http://rdoc.info/github/gridaphobe/fluidinfo.rb/frames].
 
-* Check out the latest master to make sure the feature hasn't been implemented 
+== Contributing to fluidinfo.rb
+
+* Check out the latest master to make sure the feature hasn't been implemented
   or the bug hasn't been fixed yet
-* Check out the issue tracker to make sure someone already hasn't requested it 
+* Check out the issue tracker to make sure someone already hasn't requested it
   and/or contributed it
 * Fork the project
 * Start a feature/bugfix branch
 * Commit and push until you are happy with your contribution
-* Make sure to add tests for it. This is important so I don't break it in a 
+* Make sure to add tests for it. This is important so I don't break it in a
   future version unintentionally.
-* Please try not to mess with the Rakefile, version, or history. If you want 
-  to have your own version, or is otherwise necessary, that is fine, but please 
+* Please try not to mess with the Rakefile, version, or history. If you want
+  to have your own version, or is otherwise necessary, that is fine, but please
   isolate to its own commit so I can cherry-pick around it.
 
 == Copyright
 
-Copyright (c) 2011 Eric Seidel. See LICENSE.txt for
+Copyright (c) 2011 Eric Seidel. See {file:LICENSE.txt} for
 further details.
 

data/Rakefile

@@ -29,10 +29,9 @@ Jeweler::RubygemsDotOrgTasks.new
 require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:spec)
 
-require 'yard/rake/yardoc_task'
+require 'yard'
 YARD::Rake::YardocTask.new do |t|
   t.files   = ['lib/**/*.rb']
-  t.options = ['--any', '--extra', '--opts']
 end
 
 task :default => :spec

data/VERSION

@@ -1 +1 @@
-0.5.0
+0.5.1

data/fluidinfo.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = "fluidinfo"
-  s.version = "0.5.0"
+  s.version = "0.5.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Eric Seidel"]

data/lib/fluidinfo/client.rb

@@ -1,103 +1,133 @@
 require "rest-client"
 require "cgi"
+require "uri"
 require "yajl"
 require "base64"
-require "set"
 
 module Fluidinfo
-  ITERABLE_TYPES      = Set.new [Array]
-  SERIALIZEABLE_TYPES = Set.new [NilClass, String, Fixnum, Float, Symbol,
-                                 TrueClass, FalseClass, Array]
-  JSON_TYPES          = Set.new ["application/json",
-                                 "application/vnd.fluiddb.value+json"]
 
+  ##
+  # {Fluidinfo::Client} handles all of the communication between your
+  # application and Fluidinfo. You should create a new
+  # {Fluidinfo::Client} anytime you want to begin making calls as a
+  # different user. All {Fluidinfo::Client} methods return an instance
+  # of {Fluidinfo::Response}.
+  #
+  # Example Usage:
+  #     # start with anonymous calls
+  #     fi = Fluidinfo::Client.new
+  #     fi.get "/values", :query => "has terry/rating > 4 and eric/seen",
+  #                       :tags  => ["imdb.com/title", "amazon.com/price"]
+  #     # now log in
+  #     fi = Fluidinfo::Client.new :user => "user", :password => "password"
+  #     fi.put "/about/Inception/user/comment", :body => "Awesome!"
   class Client
-    # The main fluidinfo instance.
-    MAIN    = 'https://fluiddb.fluidinfo.com'
-    # The sandbox instance, test your code here.
-    SANDBOX = 'https://sandbox.fluidinfo.com'
 
-    def initialize(instance=:main)
-      if instance == :sandbox
-        @instance = SANDBOX
-      else
-        @instance = MAIN
-      end
-      @headers = {
+    ##
+    # Create a new instance of {Fluidinfo::Client}.
+    #
+    # @param [Hash] options Initialization options.
+    #
+    # @option options [String] :user The username to use for
+    #   authentication.
+    # @option options [String] :password The password to use for
+    #   authentication.
+    # @option options [Hash] :headers Additional headers to send with
+    #   every API call made via this client.
+    def initialize(options={})
+      base_url = options[:instance] || Fluidinfo::MAIN
+      headers = {
         :accept => "*/*",
         :user_agent => "fluidinfo.rb/#{Fluidinfo.version}"
-      }
-    end
-
-    def login(user, pass)
-      @headers[:authorization] = "Basic " + 
-        (Base64.encode64 "#{user}:#{pass}").strip
-    end
-
-    def logout
-      @headers.delete :authorization
+      }.merge(options[:headers] || {})
+      @client = RestClient::Resource.new base_url, :user => options[:user],
+                                                   :password => options[:password],
+                                                   :headers => headers
     end
 
     ##
-    # Call GET on one of the APIs
+    # Call GET on one of the APIs.
     #
-    # +options+ contains URI arguments that will be appended to +path+
-    # consult the {Fluidinfo API documentation}[api.fluidinfo.com] for a list of
-    # appropriate options
+    # @param [String] path The path segment of the API call.
+    # @param [Hash] options Additional arguments for the GET call.
+    #
+    # @option options [Hash] :headers Additional headers to send.
+    # @option options [String] :query A Fluidinfo query for objects, only used in
+    #   +/objects+ and +/values+.
+    # @option options [Array] :tags Tags to be deleted, only used in +/values+.
     def get(path, options={})
       url = build_url path, options
-      Response.new(RestClient.get url, @headers)
+      headers = options[:headers] || {}
+      Response.new(@client[url].get headers)
     end
 
     ##
-    # Call HEAD on the /about or /object API to test for the existence
-    # of a tag
-    def head(path)
-      path = @instance + path
-      Response.new(RestClient.head path, @headers)
+    # Call HEAD on one of the APIs. Only used to check for the
+    # existence of a tag using +/about+ or +/objects+.
+    #
+    # @param [String] path The path segment of the API call.
+    # @param [Hash] options Additional arguments for the GET call.
+    #
+    # @option options [Hash] :headers Additional headers to send.
+    def head(path, options={})
+      url = build_url path, options
+      headers = options[:headers] || {}
+      Response.new(@client[url].head headers)
     end
 
     ##
-    # Call POST on one of the APIs
+    # Call POST on one of the APIs.
+    #
+    # @param [String] path The path segment of the API call.
+    # @param [Hash] options Additional arguments for the POST call.
     #
-    # +options[:body]+ contains the request payload. For some API
-    # calls this may be empty.
+    # @option options [Hash] :headers Additional headers to send.
+    # @option options [Hash] :body The payload to send.
     def post(path, options={})
-      path = @instance + path
-      if options[:body]
-        payload = build_payload options
-        headers = @headers.merge :content_type => payload[:mime]
-        Response.new(RestClient.post path, payload[:body], headers)
-      else
-        Response.new(RestClient.post path, nil, @headers)
+      url = build_url path, options
+      body = options[:body]
+      headers = options[:headers] || {}
+      if body
+        # the body for a POST will always be app/json, so no need
+        # to waste cycles in build_payload
+        body = Yajl.dump body
+        headers.merge! :content_type => "application/json"
       end
+      Response.new(@client[url].post body, headers)
     end
 
     ##
-    # Call PUT on one of the APIs
+    # Call PUT on one of the APIs.
     #
-    # +options[:body]+ contains the request payload.
+    # @param [String] path The path segment of the API call.
+    # @param [Hash] options Additional arguments for the PUT call.
     #
-    # +options[:mime]+ contains the MIME-type unless the payload is 
-    # JSON-encodable
+    # @option options [Hash] :headers Additional headers to send.
+    # @option options [Hash, other] :body The payload to send. Type
+    #   should be +Hash+ unless sending a tag-value.
+    # @option options [String] :mime The mime-type of an opaque tag-value.
     def put(path, options={})
       url = build_url path, options
-      payload = build_payload options
-      headers = @headers.merge(:content_type   => payload[:mime],
-                               :content_length => payload[:size])
-      Response.new(RestClient.put url, payload[:body], headers)
+      body, mime = build_payload options
+      headers = (options[:headers] || {}).merge :content_type => mime
+      Response.new(@client[url].put body, headers)
     end
 
     ##
-    # Call DELETE on one of the APIs
+    # Call DELETE on one of the APIs.
     #
-    # +options+ contains URI arguments that will be appended to +path+
-    # consult the {Fluidinfo API documentation}[api.fluidinfo.com] for a list 
-    # of appropriate options
+    # @param [String] path The path segment of the API call.
+    # @param [Hash] options Additional arguments for the DELETE call.
+    #
+    # @option options [Hash] :headers Additional headers to send.
+    # @option options [String] :query A Fluidinfo query for objects, only used in
+    #   +/values+.
+    # @option options [Array] :tags Tags to be deleted, only used in +/values+.
     def delete(path, options={})
       url = build_url path, options
+      headers = options[:headers] || {}
       # nothing returned in response body for DELETE
-      Response.new(RestClient.delete url, @headers)
+      Response.new(@client[url].delete headers)
     end
 
     private
@@ -120,50 +150,53 @@ module Fluidinfo
       end.join('&')
       # fix for /about API
       if path.start_with? '/about/'
-        path = path.split("/").map{|x| CGI.escape x}.join("/")
+        # path components need to be escaped with URI.escape instead
+        # of CGI.escape so " " is translated properly to "%20"
+        path = path.split("/").map{|x| URI.escape x}.join("/")
       end
       if args != ''
-        "#{@instance}#{path}?#{args}"
+        "#{path}?#{args}"
       else
-        "#{@instance}#{path}"
+        "#{path}"
       end
     end
 
     ##
     # Build the payload from the options hash
     def build_payload(options)
-      payload = options.reject {|k,v| !([:body, :mime].include? k)}
-      if payload[:mime]
+      body = options[:body]
+      mime = options[:mime]
+      if mime
         # user set mime-type, let them deal with it :)
         # fix for ruby 1.8
-        if payload[:body].is_a? File
-          payload[:size] = payload[:body].path.size
+        if body.is_a? File
+          size = body.path.size
         else
-          payload[:size] = payload[:body].size
+          size = body.size
         end
-      elsif payload[:body].is_a? Hash
-        payload[:body] = Yajl.dump payload[:body]
-        payload[:mime] = "application/json"
-      elsif SERIALIZEABLE_TYPES.include? payload[:body].class
-        if ITERABLE_TYPES.include? payload[:body].class
-          if is_set_of_strings? payload[:body]
+      elsif body.is_a? Hash
+        body = Yajl.dump body
+        mime = "application/json"
+      elsif SERIALIZEABLE_TYPES.include? body.class
+        if ITERABLE_TYPES.include? body.class
+          if is_set_of_strings? body
             # set of strings is primitive
-            payload[:mime] = "application/vnd.fluiddb.value+json"
+            mime = "application/vnd.fluiddb.value+json"
           else
             # we have an Array with some non-String items
-            payload[:mime] = "application/json"
+            mime = "application/json"
           end
         else
           # primitive type
-          payload[:mime] = "application/vnd.fluiddb.value+json"
+          mime = "application/vnd.fluiddb.value+json"
         end
-        payload[:body] = Yajl.dump payload[:body]
+        body = Yajl.dump body
       else
         raise TypeError, "You must supply the mime-type"
       end
-      payload
+      [body, mime]
     end
-    
+
     ##
     # Check if payload is a "set of strings"
     def is_set_of_strings?(list)

data/lib/fluidinfo/response.rb

@@ -1,11 +1,22 @@
 require "yajl"
 
 module Fluidinfo
+
+  ##
+  # An instance of {Fluidinfo::Response} is returned by all of the
+  # {Fluidinfo::Client} calls. There's no reason to instantiate one
+  # yourself.
   class Response
-    attr_reader :status, :headers, :content, :value, :response
+    # [Integer] The return code of the API call.
+    attr_reader :status
+    # [Hash] The returned headers.
+    attr_reader :headers
+    # [String, nil] The raw response
+    attr_reader :content
+    # [Hash, String] The parsed response if the +Content-Type+ was one of {Fluidinfo::JSON_TYPES}, otherwise equivalent to {#content}.
+    attr_reader :value
 
     def initialize(response)
-      @response = response
       @status   = response.code
       @headers  = response.headers
       @content  = response.body
@@ -16,9 +27,11 @@ module Fluidinfo
                   end
     end
 
+    ##
+    # A shortcut for +Response.value#[]+.
     def [](key)
       @value[key]
     end
-    
+
   end
 end

data/lib/fluidinfo.rb

@@ -1,2 +1,14 @@
 require File.join(File.dirname(__FILE__), "/fluidinfo/client")
 require File.join(File.dirname(__FILE__), "/fluidinfo/response")
+
+##
+# +fludiinfo.rb+ is a library for interacting with
+# {http://www.fluidinfo.com Fluidinfo}. Take a look at
+# {Fluidinfo::Client} to get started.
+module Fluidinfo
+  ITERABLE_TYPES      = [Array]
+  SERIALIZEABLE_TYPES = [NilClass, String, Fixnum, Float, Symbol, TrueClass, FalseClass, Array]
+  JSON_TYPES          = ["application/json", "application/vnd.fluiddb.value+json"]
+  # The main instance of Fluidinfo.
+  MAIN = 'https://fluiddb.fluidinfo.com'
+end

data/spec/fluidinfo_spec.rb

@@ -10,7 +10,7 @@ describe Fluidinfo do
     it "should return a Fluidinfo::Response" do
       r = @fluid.get("/about/fluidinfo")
       r.should be_a(Fluidinfo::Response)
-      r.should respond_to(:status, :content, :headers, :value, :response)
+      r.should respond_to(:status, :content, :headers, :value)
     end
 
     describe "/objects" do
@@ -101,14 +101,13 @@ describe Fluidinfo do
 
   describe "POST" do
     before(:each) do
-      @fluid = Fluidinfo::Client.new
-      @fluid.login 'test', 'test'
+      @fluid = Fluidinfo::Client.new :user => "test", :password => "test"
     end
 
     it "should return a Fluidinfo::Response" do
       r = @fluid.post("/objects")
       r.should be_a(Fluidinfo::Response)
-      r.should respond_to(:status, :content, :headers, :value, :response)
+      r.should respond_to(:status, :content, :headers, :value)
     end
 
     describe "/namespaces" do
@@ -130,14 +129,13 @@ describe Fluidinfo do
 
   describe "PUT" do
     before(:each) do
-      @fluid = Fluidinfo::Client.new
-      @fluid.login 'test', 'test'
+      @fluid = Fluidinfo::Client.new :user => "test", :password => "test"
     end
 
     it "should return a Fluidinfo::Response" do
       r = @fluid.put("/about/fluidinfo/test/tag", :body => nil)
       r.should be_a(Fluidinfo::Response)
-      r.should respond_to(:status, :content, :headers, :value, :response)
+      r.should respond_to(:status, :content, :headers, :value)
       @fluid.delete("/about/fluidinfo/test/tag")
     end
 
@@ -226,12 +224,12 @@ describe Fluidinfo do
     describe "build_url" do
       it "escapes &'s in query tag-values" do
         query = "test/tag=\"1&2\""
-        expected = "https://fluiddb.fluidinfo.com/objects?query=test%2Ftag%3D%221%262%22"
+        expected = "/objects?query=test%2Ftag%3D%221%262%22"
         @fluid.test_build_url("/objects", :query => query).should eq(expected)
 
         query = "oreilly.com/title=\"HTML & CSS: The Good Parts\""
         tags = ["oreilly.com/isbn"]
-        expected = "https://fluiddb.fluidinfo.com/values?query=oreilly.com%2Ftitle%3D%22HTML+%26+CSS%3A+The+Good+Parts%22&tag=oreilly.com/isbn"
+        expected = "/values?query=oreilly.com%2Ftitle%3D%22HTML+%26+CSS%3A+The+Good+Parts%22&tag=oreilly.com/isbn"
         @fluid.test_build_url("/values",
                               :query => query,
                               :tags => tags).should eq(expected)
@@ -239,7 +237,7 @@ describe Fluidinfo do
 
       it "escapes &'s in about-values" do
         about = "tom & jerry"
-        expected = "https://fluiddb.fluidinfo.com/about/tom+%26+jerry"
+        expected = "/about/tom%20&%20jerry"
         @fluid.test_build_url('/about/tom & jerry').should eq(expected)
       end
     end
@@ -248,14 +246,14 @@ describe Fluidinfo do
       it "sets proper mime-types" do
         primitives = [1, 1.1, true, false, nil, ["1", "2", "hi"]]
         primitives.each do |p|
-          h = @fluid.test_build_payload :body => p
-          h[:mime].should eq("application/vnd.fluiddb.value+json")
+          body, mime = @fluid.test_build_payload :body => p
+          mime.should eq("application/vnd.fluiddb.value+json")
         end
 
         non_primitives = [[1, 2, 3], {"hi" => "there"}]
         non_primitives.each do |n|
-          h = @fluid.test_build_payload :body => n
-          h[:mime].should eq("application/json")
+          body, mime = @fluid.test_build_payload :body => n
+          mime.should eq("application/json")
         end
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fluidinfo
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2011-09-17 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
-  requirement: &70220778276580 !ruby/object:Gem::Requirement
+  requirement: &70240390467800 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: 1.6.7
   type: :runtime
   prerelease: false
-  version_requirements: *70220778276580
+  version_requirements: *70240390467800
 - !ruby/object:Gem::Dependency
   name: yajl-ruby
-  requirement: &70220778275920 !ruby/object:Gem::Requirement
+  requirement: &70240390467260 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: 1.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *70220778275920
+  version_requirements: *70240390467260
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70220778275320 !ruby/object:Gem::Requirement
+  requirement: &70240390466660 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +43,10 @@ dependencies:
         version: 0.9.2
   type: :development
   prerelease: false
-  version_requirements: *70220778275320
+  version_requirements: *70240390466660
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70220778274720 !ruby/object:Gem::Requirement
+  requirement: &70240390466120 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,10 +54,10 @@ dependencies:
         version: 2.6.0
   type: :development
   prerelease: false
-  version_requirements: *70220778274720
+  version_requirements: *70240390466120
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &70220778274120 !ruby/object:Gem::Requirement
+  requirement: &70240390465540 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -65,10 +65,10 @@ dependencies:
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *70220778274120
+  version_requirements: *70240390465540
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &70220778273520 !ruby/object:Gem::Requirement
+  requirement: &70240390464960 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -76,10 +76,10 @@ dependencies:
         version: 1.6.4
   type: :development
   prerelease: false
-  version_requirements: *70220778273520
+  version_requirements: *70240390464960
 - !ruby/object:Gem::Dependency
   name: uuidtools
-  requirement: &70220778272920 !ruby/object:Gem::Requirement
+  requirement: &70240390464380 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -87,10 +87,10 @@ dependencies:
         version: 2.1.2
   type: :development
   prerelease: false
-  version_requirements: *70220778272920
+  version_requirements: *70240390464380
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &70220778272320 !ruby/object:Gem::Requirement
+  requirement: &70240390463800 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -98,7 +98,7 @@ dependencies:
         version: 0.7.2
   type: :development
   prerelease: false
-  version_requirements: *70220778272320
+  version_requirements: *70240390463800
 description: This gem provides a simple interface to fluidinfo, built on top of the
   rest-client gem.
 email: gridaphobe@gmail.com
@@ -137,7 +137,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3187277794314220845
+      hash: -1150775427864763998
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: