uncoil 1.0.0 → 1.1.0

data/.gitignore

@@ -2,4 +2,5 @@
 .bundle
 Gemfile.lock
 pkg/*
-coverage/
+coverage/
+credentials.yml

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+    - 1.8.7
+    - 1.9.2
+    - 1.9.3
+    - rbx-19mode
+    - jruby-19mode

data/.yardoc/checksums

@@ -0,0 +1,3 @@
+lib/uncoil.rb 0ab3336a87ae06d8a3aa55e15104552fcd7f6e9e
+lib/uncoil/version.rb 2a25a2d46f761aa4d70eeee4a7f6adc42215db7a
+lib/uncoil_submethods.rb 94e18e69c539be74e772316cc9cdc9cfaad296fd

data/.yardoc/proxy_types

@@ -0,0 +1,2 @@
+{I"Object:EF:
+class

data/README.md

@@ -1,21 +1,63 @@
-# uncoil
+# uncoil - the link unshortening gem
+
+[![Build Status](https://secure.travis-ci.org/stim371/uncoil.png)](http://travis-ci.org/stim371/uncoil)
 
 The uncoil gem is a one stop shop for un-shortening urls.
 
 The idea is based off of my site http://uncoil.me and I built this as part of my UWE-Ruby fall project.
 
 ## Why the heck does this exist?
-This gem is all about transparency and safety, and knowing where you are going on the internet.
+This gem is all about transparency, safety and knowing where you are going on the internet.
+
+The last straw was seeing TechCrunch articles with titles like "Don't click on this one specific goo.gl link! It's a virus!" (like [this](http://techcrunch.com/2010/12/07/twitter-virus/) one), which was flabbergasting. How is it that a tech blog and community's only response to these kind of threats is so reactionary and linear? **We can do better than that.**
 
 There are a few instances where it may come in handy:
 
 * You want to make sure you're not heading into an obviously sketchy site
 * You're at work and want to keep out the NSFW
 
-## Example
-I have no idea where http://bit.ly/2EEjBl really goes.
+## Installation
+
+Install the gem:
+
+    gem install uncoil
+
+Add it to your file:
+
+```ruby
+require 'uncoil'
+```
+
+## Usage
+* If you have Bitly login credentials, use them to create a new instance:
 
-But by expanding it with uncoil, I can see that it goes to http://www.cnn.com
+```ruby
+@a = Bitly.new(:bitlyuser => 'YOURAPIUSERNAME', :bitlykey => 'YOURAPIKEY')
+# Or if you don't have any auth criteria
+@a = Bitly.new
+# in which case it will use a standard HTTP loop to find bitly destination urls
+```
+
+* Use the  `expand` method to see where the short link goes:
+
+```ruby
+@a.expand('http://bit.ly/2EEjBl')
+# or pass in an array of links
+@a.expand(['http://bit.ly/2EEjBl','http://is.gd/gbKNRq'])
+```
+
+For each link you pass in, you will get a separate `Uncoil::Response` object out with parameters for `long_url`, `short_url` and `error`
+
+A full usage cycle may look like this:
+
+```ruby
+@a = Bitly.new(:bitlyuser => 'YOURAPIUSERNAME', :bitlykey => 'YOURAPIKEY')
+@b = @a.expand('http://bit.ly/2EEjBl') # => <Uncoil::Response:0x00000100a0d948 @long_url="http://www.cnn.com/" @short_url="http://bit.ly/2EEjBl" @error=nil>
+
+@b.long_url   # => "http://www.cnn.com/"
+@b.short_url  # => "http://bit.ly/2EEjBl"
+@b.error      # => nil
+```
 
 ## How the app works
 
@@ -23,9 +65,7 @@ But by expanding it with uncoil, I can see that it goes to http://www.cnn.com
 2. See if it matches with any of the supported APIs
   * If so, it calls the correct API method
   * If no matching method is found, it runs through an HTTP loop until it receives a 200 response
-3. It then returns a hash containing, among other items, the full url
-
-## Current Issues
+3. It then returns a Response object containing, among other items, the full url
 
 ## Future Enhancements
 Here are a few ideas I have for the future:

data/lib/uncoil.rb

@@ -1,12 +1,21 @@
 require 'bitly'
-require 'open-uri'
-require 'net/http'
-require 'json'
+require_relative 'uncoil_submethods'
 
+# @author Joel Stimson
 class Uncoil
   ISGD_ROOT_URL = "http://is.gd/forward.php?format=json&shorturl="
   BITLY_DOM_ARRAY = %w[bit.ly, j.mp, bitlypro.com, cs.pn, nyti.ms]
   
+  # Creates a new Uncoil object and will log into Bit.ly if you provide credentials
+  #
+  # @option options [String] :bitlyuser A key for your Bit.ly API username
+  # @option options [String] :bitlykey A key for your Bit.ly API key
+  # 
+  # @return [Class] the new instance of the Uncoil class
+  # 
+  # @example Set up a new instance
+  #  Uncoil.new(:bitlyuser => CREDENTIALS['bitlyuser'], :bitlykey => CREDENTIALS['bitlykey']) => "#<Uncoil:0x00000102560d30 @bitly_access=true>"
+  #
   def initialize options = {}
     Bitly.use_api_version_3
     @bitly_access = false
@@ -17,11 +26,28 @@ class Uncoil
       @bitly_access = true
     end
   end
+  
+  # A class method version of the main expand method. This will not have access to the bit.ly API, but it's faster than having to create an instance and then use it for a one-off request.
+  #
+  # @param [String, Array] short_url The single url or array of urls you would like to expand
+  #
+  # @example Use the class method for a one-off request
+  #  Uncoil.expand("http://tinyurl.com/736swvl") # => #<Uncoil::Response:0x00000101ed9250 @long_url="http://www.chinadaily.com.cn/usa/business/2011-11/08/content_14057648.htm", @short_url="http://tinyurl.com/736swvl", @error=nil> 
+  #
+  def self.expand short_url
+    Uncoil.new.expand(short_url)
+  end
 
+  # The main method used for all requests. This method will delegate to submethods based on the domain of the link given.
+  #
+  # @param [String, Array] url_arr This can be a single url as a String or an array of Strings that the method will expand in order
+  #
+  # @return [Uncoil::Response] Returns a response object with getters for the long and short url
+  # 
   def expand url_arr
     output_array = Array(url_arr).flatten.map do |short_url|
-      short_url = clean_url(short_url)
-      domain    = identify_domain(short_url)
+      short_url  = clean_url(short_url)
+      domain     = identify_domain(short_url)
       
       begin
         long_url = 
@@ -43,34 +69,29 @@ class Uncoil
     output_array.length == 1 ? output_array[0] : output_array
   end
 
+
+  # Contacts the bit.ly API to see if the domain is a bitlypro domain, which are custom domains purchased by 3rd parties but managed by bit.ly
+  #
+  # @param [String] url_domain The domain to check against the bit.ly API.
+  #
   def check_bitly_pro url_domain
     @bitly_instance.bitly_pro_domain(url_domain)
   end
-
-  def uncoil_bitly short_url
-    @bitly_instance.expand(short_url).long_url
-  end
-
-  def uncoil_isgd short_url
-    JSON.parse(open(ISGD_ROOT_URL + "#{short_url}") { |file| file.read } )["url"]
-  end
-
-  def uncoil_other short_url, depth = 10
-    url = URI.encode(short_url)
-    response = Net::HTTP.get_response(URI.parse(url))
-    
-    case response
-      when Net::HTTPSuccess     then url
-      when Net::HTTPRedirection then uncoil_other(response['location'], depth - 1)
-    end
-  end
   
-  # helper methods to clean up the code above
   
+  # Extracts the domain from the link to help match it with the right sub-method to expand the url
+  #
+  # @param [String] short_url A single url to extract a domain from.
+  #
   def identify_domain short_url
     clean_url(short_url).split("/")[2].to_s
   end
+  
 
+  # Standardizes the url by adding a protocol if there isn't one and removing trailing slashes
+  #
+  # @param [String] short_url A single url to be cleaned up.
+  #
   def clean_url short_url
     short_url = "http://" << short_url unless short_url =~ /^https?:\/\//
     short_url.chop! if short_url[-1] == "/"
@@ -79,9 +100,16 @@ class Uncoil
   
 end
 
+
 class Uncoil::Response
   attr_reader :long_url, :short_url, :error
   
+  # Creates a new Response object with attributes for the original and short url, as well as any errors that occured. It is called at the end of 'expand' method.
+  #
+  # @param [String] long_url The expanded url that we were looking for.
+  # @param [String] short_url The original, short url that we used to look up the long url.
+  # @param [String] error The error output if anything went wrong during the request. And I mean ANYTHING from a code error to an HTTP issue. It catches it all.
+  #
   def initialize(long_url, short_url, error)
     @long_url = long_url
     @short_url = short_url

data/lib/uncoil/version.rb

@@ -1,3 +1,3 @@
 class Uncoil
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/uncoil_submethods.rb

@@ -0,0 +1,38 @@
+require 'open-uri'
+require 'net/http'
+require 'json'
+
+class Uncoil
+  
+  # Expands any links that are bitly or bitlypro domains as long as you have logged into the bitly API.
+  # 
+  # @param [String] short_url The short url you would like to expand.
+  # 
+  def uncoil_bitly short_url
+    @bitly_instance.expand(short_url).long_url
+  end
+
+  # Expands any links that are isgd domains.
+  # 
+  # @param [String] short_url The short url you would like to expand.
+  #
+  def uncoil_isgd short_url
+    JSON.parse(open(ISGD_ROOT_URL + "#{short_url}") { |file| file.read } )["url"]
+  end
+
+  # Expands any links that do not match the above domains.
+  # 
+  # @param [String] short_url The short url you would like to expand.
+  # @param [Integer, 10] depth The number of redirects you would like this method to follow.
+  #
+  def uncoil_other short_url, depth = 10
+    url = URI.encode(short_url)
+    response = Net::HTTP.get_response(URI.parse(url))
+  
+    case response
+      when Net::HTTPSuccess     then url
+      when Net::HTTPRedirection then uncoil_other(response['location'], depth - 1)
+    end
+  end
+  
+end

data/spec/spec_helper.rb

@@ -1,2 +1,4 @@
 require 'simplecov'
-SimpleCov.start
+SimpleCov.start
+
+CREDENTIALS = YAML.load_file("./credentials.yml")['bitly']

data/spec/uncoil_response_spec.rb

@@ -0,0 +1,21 @@
+require 'spec_helper'
+require 'uncoil'
+
+describe "the response object" do
+  
+  subject { Uncoil.new(:bitlyuser => CREDENTIALS['bitlyuser'], :bitlykey => CREDENTIALS['bitlykey'])}
+  
+  before(:all) {
+    @subject = subject.expand("http://is.gd/gbKNRq")
+  }
+  
+  it "should return a response object" do
+    @subject.class.should eq Uncoil::Response
+  end
+  
+  it "should respond to getter methods" do
+    @subject.long_url.should_not eq nil
+    @subject.short_url.should_not eq nil
+  end
+  
+end

data/spec/uncoil_spec.rb

@@ -3,21 +3,26 @@ require 'uncoil'
 
 describe Uncoil do
   
-  subject { Uncoil.new(:bitlyuser => "stim371", :bitlykey => "R_7a6f6d845668a8a7bb3e0c80ee3c28d6")}
+  subject { Uncoil.new(:bitlyuser => CREDENTIALS['bitlyuser'], :bitlykey => CREDENTIALS['bitlykey'])}
   
-  describe "when using the submethods" do
+  describe "#expand class method" do
+    it "should successfully return a response object" do
+      Uncoil.expand("http://tinyurl.com/736swvl").class.should eq Uncoil::Response
+    end
     
-    context "when trying to undo a bit.ly link" do
-      it "should bring back the correct long link" do
-        expected_result = "http://www.cnn.com/"
-        subject.uncoil_bitly("http://bit.ly/2EEjBl").should eq expected_result
-      end
+    it "should bring back the correct link" do
+      response = Uncoil.expand("http://tinyurl.com/736swvl")
+      response.long_url.should eq "http://www.chinadaily.com.cn/usa/business/2011-11/08/content_14057648.htm"
     end
+  end
   
-    context "when trying to undo a bit.ly pro link" do
+  describe "when using the submethods" do
+    
+    context "when trying to undo a bit.ly and bit.ly pro link" do
       it "should bring back the correct long link" do
-        expected_result = "http://www.c-spanvideo.org/program/CainNew"
-        subject.uncoil_bitly("http://cs.pn/vsZpra").should eq expected_result
+        {"http://bit.ly/2EEjBl" => "http://www.cnn.com/", "http://cs.pn/vsZpra" => "http://www.c-spanvideo.org/program/CainNew" }.each { |short_url, long_url| 
+        subject.uncoil_bitly(short_url).should eq long_url
+        }
       end
     end
   
@@ -36,15 +41,11 @@ describe Uncoil do
   
   describe "the main expand method" do
     
-    it "should return a response object" do
-      subject.expand("http://is.gd/gbKNRq").class.should eq Uncoil::Response
-    end
-    
     it "should raise an error for non-urls" do
       subject.expand("a").error.should_not be_nil
     end
     
-    context "and when expanding a link" do
+    context "when expanding a link" do
       
       def check_response response, expected_result
         response.long_url.should eq expected_result[:long_url]

data/uncoil.gemspec

@@ -22,6 +22,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency "rspec"
   s.add_development_dependency "guard-rspec"
   s.add_development_dependency "simplecov"
+  s.add_development_dependency "rake"
   
   s.add_runtime_dependency "bitly"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: uncoil
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-21 00:00:00.000000000 Z
+date: 2012-03-07 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2157463580 !ruby/object:Gem::Requirement
+  requirement: &2152984160 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2157463580
+  version_requirements: *2152984160
 - !ruby/object:Gem::Dependency
   name: guard-rspec
-  requirement: &2157463160 !ruby/object:Gem::Requirement
+  requirement: &2152983000 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2157463160
+  version_requirements: *2152983000
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &2157462740 !ruby/object:Gem::Requirement
+  requirement: &2152981500 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,21 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2157462740
+  version_requirements: *2152981500
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &2152980660 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *2152980660
 - !ruby/object:Gem::Dependency
   name: bitly
-  requirement: &2157462320 !ruby/object:Gem::Requirement
+  requirement: &2152979620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,7 +65,7 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2157462320
+  version_requirements: *2152979620
 description: Uncoil is a gem to unshorten urls so you know where obscured links really
   go. If you have bitly login credentials, initialize an instance of Uncoil to use
   the bitly API.
@@ -65,6 +76,10 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
+- .yardoc/checksums
+- .yardoc/objects/root.dat
+- .yardoc/proxy_types
 - Gemfile
 - Guardfile
 - Manifest
@@ -72,8 +87,10 @@ files:
 - Rakefile
 - lib/uncoil.rb
 - lib/uncoil/version.rb
+- lib/uncoil_submethods.rb
 - spec/helper_method_spec.rb
 - spec/spec_helper.rb
+- spec/uncoil_response_spec.rb
 - spec/uncoil_spec.rb
 - uncoil.gemspec
 homepage: https://github.com/stim371/uncoil
@@ -104,4 +121,6 @@ summary: Uncoil is a gem to unshorten urls so you know where obscured links real
 test_files:
 - spec/helper_method_spec.rb
 - spec/spec_helper.rb
+- spec/uncoil_response_spec.rb
 - spec/uncoil_spec.rb
+has_rdoc: