url 0.1.1 → 0.1.2

data/.gitignore

@@ -19,3 +19,6 @@ rdoc
 pkg
 
 ## PROJECT::SPECIFIC
+.yardoc/*
+.yard/*
+doc/*

data/README.rdoc

@@ -1,6 +1,7 @@
 = URL Gem
 
-A simple url object to allow for object oriented based manipulation and usage of a url
+A simple url object to allow for object oriented based manipulation and usage of a url. It works with Typhoeus if it detects it's installed
+or defaults back to Net::HTTP.
 
 == Usage
 
@@ -21,9 +22,40 @@ You can easily extract or change any part of the url
   url.params[:foo] = 'bar'
   url.to_s   # => 'https://my.mail.google.com/mail/?foo=bar&shva=1#mbox'
 
+=== Make Requests
+
+You can quickly and easily make requests from those urls without having to worry about whether they're https or not.
+
+  url = URL.new('https://graph.facebook.com/37901410')
+  response = url.get
+  response # => "{"id":"37901410","name":"Tal Atlas","first_name":"Tal","last_name":"Atlas","link":"http:\\/\\/www.facebook.com\\/talatlas","gender":"male","locale":"en_US"}"
+
+A {URL::Response} object is returned from {URL#post}, {URL#get}, or {URL#delete}. This is basically a string with a few additional methods including:
+
+The time the request took in seconds
+The http code of the response and whether the request was successful or not (code == 200).
+
+  response.time     # => 1.6
+  response.code     # => 200
+  response.success? # => true
+
+You can make GET, POST, or DELETE requests without doing any special formatting.
+
+  url.path << '/feed'
+  url.params[:access_token] = '.....'
+  url.params[:message] = "Hey I'm posting this message with ruby"
+  json = url.post
+  
+  post_id = magic_method(json)
+  
+  url.path = "/#{post_id}"
+  url.params.delete(:message)
+  url.delete
+
 == TODO
 * More Documentation
 * More specs
+* Make faster
 
 == Note on Patches/Pull Requests
  

data/VERSION.yml

@@ -1,5 +1,5 @@
 ---
 :major: 0
 :minor: 1
-:patch: 1
+:patch: 2
 :build: 

data/lib/url.rb

@@ -6,12 +6,28 @@ require 'cgi'
 files = Dir.glob(File.join(File.dirname(__FILE__),'url','**','*.rb'))
 files.each { |f| require f }
 
-#:include: README.rdoc
+# Main class for managing urls
+#   url = URL.new('https://mail.google.com/mail/?shva=1#mbox')
+#   url.params # => {:shva => '1'}
+#   url.scheme # => 'https'
+#   url.host   # => 'mail.google.com'
+#   url.domain # => 'google.com'
+#   url.subdomain # => ['mail']
+#   url.path   # => '/mail/'
+#   url.hash   # => 'mbox'
+#   
+#   url.subdomain = ['my','mail']
+#   url.params[:foo] = 'bar'
+#   url.to_s   # => 'https://my.mail.google.com/mail/?foo=bar&shva=1#mbox'
 class URL
   attr_reader :string, :params
+  
+  # Attributes of the URL which are editable
   attr_accessor :subdomain, :domain, :path, :scheme, :format, :port, :hash
   alias_method :subdomains, :subdomain
   
+  # Creates a new URL object
+  # @param [String] URL the starting url to work with
   def initialize str
     @string = str
     sp = URI.split(@string)
@@ -55,7 +71,7 @@ class URL
   end
   
   # Outputs the full current url
-  # @param [Hash<Symbol,false>,#whatever] ops Prevent certain parts of the object from being shown by setting `:scheme`,`:port`,`:path`,`:params`, or `:hash` to `false`
+  # @param [Hash] ops Prevent certain parts of the object from being shown by setting `:scheme`,`:port`,`:path`,`:params`, or `:hash` to `false`
   # @return [String]
   def to_s ops={}
     ret = String.new
@@ -64,7 +80,6 @@ class URL
     ret << %{:#{port}} if port && ops[:port] != false
     if path && ops[:path] != false
       ret << path
-      # ret << %{.#{format}} if format && ops[:format] != false
     end
     
     ret << params.to_s if params && ops[:params] != false
@@ -81,13 +96,11 @@ class URL
   end
   
   class << self
+    # Define the request handler to use. If Typhoeus is setup it will use {TyHandler} otherwise will default back to Net::HTTP with {NetHandler}
+    # @return [Handler]
     attr_accessor :req_handler
   end
   
-  def req_handler #:nodoc:
-    self.class.req_handler.new(self)
-  end
-  
   # Performs a get request for the current URL
   # @return [URL::Response] A subclass of string which also repsonds to a few added mthods storing more information
   def get(*args)
@@ -106,7 +119,7 @@ class URL
     req_handler.delete(*args)
   end
   
-  def inspect #:nodoc:
+  def inspect
     "#<URL #{to_s}>"
   end
   
@@ -115,5 +128,10 @@ class URL
   else
     URL.req_handler = NetHandler
   end
+  
+private
+  def req_handler
+    self.class.req_handler.new(self)
+  end
 end
 

data/lib/url/handlers.rb

@@ -1,5 +1,18 @@
 class URL
   
+  # Handlers for making requests for the URL. To create your own you need to follow the following conventions:
+  # 1. You must define the get, post, and delete instance methods
+  # 2. These methods should return a {Response} object
+  # 
+  # To create a {Response} object:
+  #   hsh = {
+  #     :code => resp.code,
+  #     :time => resp.time,
+  #     :body => resp.body,
+  #     :response => resp,
+  #     :url => url.to_s
+  #   }
+  #   Response.new(hsh)
   class Handler
     attr_reader :url
     def initialize(url)
@@ -7,6 +20,7 @@ class URL
     end
   end
   
+  # Typhoeus handler
   class TyHandler < Handler
     
     def get(args={})
@@ -42,9 +56,9 @@ class URL
     
   end
   
+  # Net::HTTP Handler
   class NetHandler < Handler
     def get(args={})
-      puts 'net'
       http = http_obj
       request = Net::HTTP::Get.new(url.path + url.params.to_s)
       t = Time.now

data/lib/url/helper_classes.rb

@@ -9,8 +9,26 @@ class URL
   # * response - the original response object from whatever handler you chose
   # * time - time taken to make call
   # * success? - whether the http code is 200
+  # * url - the URL the object was gotten from
   class Response < DelegateClass(String)
-    attr_reader :body,:time,:code,:response
+    # The time taken for the request
+    # @returns [Integer]
+    attr_reader :time
+    
+    # The http code return
+    # @returns [Integer] eg. 200, 404, 500, 503
+    attr_reader :code
+    
+    # The response object generated by the handler
+    # @returns [Net::HTTPResponse,Typhoeus::Response]
+    attr_reader :response
+    
+    # The url which generated this response
+    # @returns [String]
+    attr_reader :url
+    
+    # @param [String] body The body of the response object, main string
+    # @param [Hash] args Additional arguments: :time,:code,:response,:url
     def initialize(str,args={})
       if str.is_a?(Hash)
         args = str
@@ -24,6 +42,8 @@ class URL
       end
     end
     
+    # Compares {Response#code} to 200
+    # @returns [true,false]
     def success?
       return @successful if @successful
       

data/spec/url_spec.rb

@@ -5,40 +5,113 @@ describe URL do
     @url = URL.new('https://mail.google.com:8080/foo/bar/baz?q=one&foo=bar')
   end
   
-  it "should roundtrip" do
-    @url.to_s.should == 'https://mail.google.com:8080/foo/bar/baz?q=one&foo=bar'
-  end
-  
-  it "should parse properly" do
-    @url.params.should == {:q => 'one', :foo => 'bar'}
-    @url.host.should == 'mail.google.com'
-    @url.domain.should == 'google.com'
-    @url.subdomain.should == ['mail']
-    @url.port.should == '8080'
-    @url.scheme.should == 'https'
-  end
-  
-  it "should change and add params" do
-    @url.params[:foo] = 'foo'
-    @url.params[:baz] = 'baz'
-    @url.port = '90'
-    @url.subdomain = 'test'
-    @url.scheme = 'ftp'
-    @url.path = '/bar/baz'
+  describe "#initialize" do
+    it "should parse properly" do
+      @url.params.should == {:q => 'one', :foo => 'bar'}
+      @url.host.should == 'mail.google.com'
+      @url.domain.should == 'google.com'
+      @url.subdomain.should == ['mail']
+      @url.port.should == '8080'
+      @url.scheme.should == 'https'
+    end
     
-    @url.to_s.should include 'ftp://test.google.com:90/bar/baz?'
-    @url.to_s.should include 'q=one'
-    @url.to_s.should include 'foo=foo'
-    @url.to_s.should include 'baz=baz'
+    it "should work with strange urls" do
+      url = URL.new('http://one.mail.google.co.uk')
+      url.domain.should == 'google.co.uk'
+      url.subdomains.should == ['one','mail']
+
+      url = URL.new('http://localhost')
+      url.domain.should == 'localhost'
+      url.subdomain.should be_nil
+    end
   end
   
-  it "should work with strange urls" do
-    url = URL.new('http://one.mail.google.co.uk')
-    url.domain.should == 'google.co.uk'
-    url.subdomains.should == ['one','mail']
+  describe '#to_s' do
+    it "should roundtrip" do
+      @url.to_s.should == 'https://mail.google.com:8080/foo/bar/baz?q=one&foo=bar'
+    end
     
-    url = URL.new('http://localhost')
-    url.domain.should == 'localhost'
-    url.subdomain.should be_nil
+    it "should change and add params" do
+      @url.params[:foo] = 'foo'
+      @url.params[:baz] = 'baz'
+      @url.port = '90'
+      @url.subdomain = 'test'
+      @url.scheme = 'ftp'
+      @url.path = '/bar/baz'
+      
+      @url.to_s.should include 'ftp://test.google.com:90/bar/baz?'
+      @url.to_s.should include 'q=one'
+      @url.to_s.should include 'foo=foo'
+      @url.to_s.should include 'baz=baz'
+    end
+  end
+  
+end
+
+shared_examples_for "all requests" do
+  it "should work" do
+    @resp.should be_success
+  end
+  
+  it "should have a response of the correct class" do
+    @resp.response.should be_a(@resp_class)
+  end
+  
+  it "shoudl have all attribures" do
+    @resp.time.should be_a(Float)
+    @resp.code.should be_a(Integer)
+    @resp.url.should be_a(String)
+  end
+end
+
+shared_examples_for "all builds" do
+  
+  
+  before do
+    @url = URL.new('http://www.omgpop.com/')
+  end
+  
+  describe "#get" do
+    before do
+      @resp = @url.get
+    end
+    it_should_behave_like "all requests"
+  end
+  
+  describe "#post" do
+    before do
+      @resp = @url.post
+    end
+    it_should_behave_like "all requests"
+  end
+  
+  describe "#delete" do
+    before do
+      @resp = @url.delete
+    end
+    it_should_behave_like "all requests"
   end
 end
+
+describe "Typhoeus", URL do
+  before(:all) do
+    require 'typhoeus'
+    URL.req_handler = URL::TyHandler
+    @resp_class = Typhoeus::Response
+  end
+  
+  it_should_behave_like "all builds"
+  
+end
+
+
+describe "Net::HTTP", URL do
+  before(:all) do
+    require 'net/http'
+    URL.req_handler = URL::NetHandler
+    @resp_class = Net::HTTPResponse
+  end\
+  
+  it_should_behave_like "all builds"
+  
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: url
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 31
   prerelease: false
   segments: 
   - 0
   - 1
-  - 1
-  version: 0.1.1
+  - 2
+  version: 0.1.2
 platform: ruby
 authors: 
 - Tal Atlas