google-short-links 0.1.0 → 0.1.1

data/Rakefile

@@ -40,7 +40,7 @@ RDoc::Task.new do |rdoc|
   version = File.exist?('VERSION') ? File.read('VERSION') : ''
 
   rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "cleverbot #{version}"
+  rdoc.title = "google-short-links #{version}"
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include(File.join('lib', '**', '*.rb'))
 end

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/google-short-links.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{google-short-links}
-  s.version = "0.1.0"
+  s.version = "0.1.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Benjamin Manns"]

data/lib/google_short_links.rb

@@ -1,3 +1,5 @@
+# Holds the client class for Google Short Links.
+# See GoogleShortLinks::Client.
 module GoogleShortLinks
   autoload :Client, 'google_short_links/client'
   autoload :Parser, 'google_short_links/parser'

data/lib/google_short_links/client.rb

@@ -6,19 +6,63 @@ require 'uri'
 
 require 'httparty'
 
+# Client for Google Short Links.
+#
+# ==== Examples
+#
+#   client = GoogleShortLinks::Client.new :server => 'short.example.com', :secret => 'abcdef1234567890', :email => 'ben@example.com'
+#   link = client.get_or_create_hash 'http://example.com/parent/child/long_document_name.html', :is_public => true
+#   link # => {"status"=>"ok", "url"=>"http://example.com/parent/child/long_document_name.html", "estimated_api_calls_remaining"=>98, "shortcut"=>"abc12", "usage_count"=>0, "owner"=>"ben@example.com", "is_public"=>true, "is_hash"=>true}
 class GoogleShortLinks::Client
   include HTTParty
 
-  attr_accessor :server, :secret, :email
+  # The domain name where Google Short Links is hosted.
+  attr_accessor :server
+
+  # Your HMAC-SHA1 secret.
+  attr_accessor :secret
+
+  # The email for the account under which the links will be created.
+  attr_accessor :email
 
   parser GoogleShortLinks::Parser
 
+  # Initializes a new Client.
+  #
+  # ==== Parameters
+  #
+  # [<tt>options</tt>] Optional Hash containing configuration values.
+  #
+  # ==== Options
+  #
+  # [:server]
+  #   The domain name where Google Short Links is hosted.
+  # [:secret]
+  #   Your HMAC-SHA1 secret.
+  # [:email]
+  #   The email for the account under which the links will be created.
   def initialize options={}
     self.server = options[:server]
     self.secret = options[:secret]
     self.email = options[:email]
   end
 
+  # Creates a URL that is used to create a hash.
+  #
+  # ==== Parameters
+  #
+  # [<tt>url</tt>] Required String containing the URL to be shortened.
+  # [<tt>params</tt>] Optional Hash that will add or override GET parameters in the URL.
+  #
+  # ==== Parameters
+  #
+  # [:is_public]
+  #   Boolean for whether or not the short link can be accessed without logging in to Google Apps.
+  #
+  # ==== Examples
+  #
+  #   link_url = client.get_or_create_hash_url 'http://example.com/parent/child/long_document_name.html', :is_public => true
+  #   link_url # => "http://short.example.com/js/get_or_create_hash?is_public=true&oauth_signature_method=HMAC-SHA1&timestamp=1321663459.0&url=http%3A%2F%2Fexample.com%2Fparent%2Fchild%2Flong_document_name.html&user=ben%40example.com&oauth_signature=JElQ0Oq59q%2BOsinYuMzGX%2F8Tn2U%3D"
   def get_or_create_hash_url url, params={}
     request_path = request_path(:get_or_create_hash)
 
@@ -27,6 +71,23 @@ class GoogleShortLinks::Client
     digest_url(request_path, query)
   end
 
+  # Creates a URL that is used to create a shortlink with a customized shortcut.
+  #
+  # ==== Parameters
+  #
+  # [<tt>url</tt>] Required String containing the URL to be shortened.
+  # [<tt>shortcut</tt>] Required String containing the custom shortcut.
+  # [<tt>params</tt>] Optional Hash that will add or override GET parameters in the URL.
+  #
+  # ==== Parameters
+  #
+  # [:is_public]
+  #   Boolean for whether or not the short link can be accessed without logging in to Google Apps.
+  #
+  # ==== Examples
+  #
+  #   link_url = client.get_or_create_shortlink_url 'http://example.com/parent/child/long_document_name.html', 'example', :is_public => true
+  #   link_url # => "http://short.example.com/js/get_or_create_shortlink?is_public=true&oauth_signature_method=HMAC-SHA1&shortcut=example&timestamp=1321663613.0&url=http%3A%2F%2Fexample.com%2Fparent%2Fchild%2Flong_document_name.html&user=ben%40example.com&oauth_signature=FsOEjCDw3qpz%2B59Pdi4d1Qvv0Os%3D"
   def get_or_create_shortlink_url url, shortcut, params={}
     request_path = request_path(:get_or_create_shortlink)
 
@@ -35,6 +96,17 @@ class GoogleShortLinks::Client
     digest_url(request_path, query)
   end
 
+  # Creates a URL that is used to get details about a link from its shortcut.
+  #
+  # ==== Parameters
+  #
+  # [<tt>shortcut</tt>] Required String containing the URL to be shortened.
+  # [<tt>params</tt>] Optional Hash that will add or override GET parameters in the URL.
+  #
+  # ==== Examples
+  #
+  #   link_url = client.get_details_url 'example'
+  #   link_url # => "http://short.example.com/js/get_details?oauth_signature_method=HMAC-SHA1&shortcut=example&timestamp=1321663629.0&user=ben%40example.com&oauth_signature=p8XqzF0lITupKN3Ta0qu2E8hqBI%3D"
   def get_details_url shortcut, params={}
     request_path = request_path(:get_details)
 
@@ -43,25 +115,69 @@ class GoogleShortLinks::Client
     digest_url(request_path, query)
   end
 
+  # Shortens a URL.
+  #
+  # ==== Parameters
+  #
+  # [<tt>url</tt>] Required String containing the URL to be shortened.
+  # [<tt>params</tt>] Optional Hash that will add or override GET parameters in the URL.
+  #
+  # ==== Parameters
+  #
+  # [:is_public]
+  #   Boolean for whether or not the short link can be accessed without logging in to Google Apps.
+  #
+  # ==== Examples
+  #
+  #   link = client.get_or_create_hash 'http://example.com/parent/child/long_document_name.html', :is_public => true
+  #   link # => {"status"=>"ok", "url"=>"http://example.com/parent/child/long_document_name.html", "estimated_api_calls_remaining"=>98, "shortcut"=>"abc12", "usage_count"=>0, "owner"=>"ben@example.com", "is_public"=>true, "is_hash"=>true}
   def get_or_create_hash url, params={}
     self.class.get(get_or_create_hash_url(url, params)).parsed_response
   end
 
+  # Creates a shortlink with a customized shortcut.
+  #
+  # ==== Parameters
+  #
+  # [<tt>url</tt>] Required String containing the URL to be shortened.
+  # [<tt>shortcut</tt>] Required String containing the custom shortcut.
+  # [<tt>params</tt>] Optional Hash that will add or override GET parameters in the URL.
+  #
+  # ==== Parameters
+  #
+  # [:is_public]
+  #   Boolean for whether or not the short link can be accessed without logging in to Google Apps.
+  #
+  # ==== Examples
+  #
+  #   link = client.get_or_create_shortlink 'http://example.com/parent/child/long_document_name.html', 'example', :is_public => true
+  #   link # => {"status"=>"ok", "url"=>"http://example.com/parent/child/long_document_name.html", "estimated_api_calls_remaining"=>99, "shortcut"=>"example", "usage_count"=>0, "owner"=>"ben@example.com", "is_public"=>true, "is_hash"=>false}
   def get_or_create_shortlink url, shortcut, params={}
     self.class.get(get_or_create_shortlink_url(url, shortcut, params)).parsed_response
   end
 
+  # Gets details about a link from its shortcut.
+  #
+  # ==== Parameters
+  #
+  # [<tt>shortcut</tt>] Required String containing the URL to be shortened.
+  # [<tt>params</tt>] Optional Hash that will add or override GET parameters in the URL.
+  #
+  # ==== Examples
+  #
+  #   link = client.get_details 'example'
+  #   link # => {"status"=>"ok", "url"=>"http://example.com/parent/child/long_document_name.html", "estimated_api_calls_remaining"=>100, "shortcut"=>"example", "usage_count"=>0, "owner"=>"ben@example.com", "is_public"=>true, "is_hash"=>false}
   def get_details shortcut, params={}
     self.class.get(get_details_url(shortcut, params)).parsed_response
   end
 
   protected
 
-  def request_path action
+  def request_path action #:nodoc:
     "http://#{server}/js/#{action}"
   end
 
-  def base_params
+  def base_params #:nodoc:
     {
       :oauth_signature_method => 'HMAC-SHA1',
       :timestamp => Time.now.to_i.to_f,
@@ -69,11 +185,11 @@ class GoogleShortLinks::Client
     }
   end
 
-  def params_to_query params
+  def params_to_query params #:nodoc:
     params.to_a.sort_by { |param| param.to_s }.map { |(key, value)| "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}" }.join('&')
   end
 
-  def digest request_path, query
+  def digest request_path, query #:nodoc:
     content = "GET&#{CGI.escape(request_path)}&#{CGI.escape(query)}"
 
     digest = OpenSSL::Digest::Digest.new('sha1')
@@ -81,7 +197,7 @@ class GoogleShortLinks::Client
     CGI.escape(Base64.encode64(digest_raw).chomp)
   end
 
-  def digest_url request_path, query
+  def digest_url request_path, query #:nodoc:
     request_uri = URI.parse(request_path)
     request_uri.query = "#{query}&oauth_signature=#{digest(request_path, query)}"
     request_uri.to_s

data/lib/google_short_links/parser.rb

@@ -1,9 +1,13 @@
 require 'httparty'
 require 'multi_json'
 
+# Parses the JSON that Google Short Links returns.
 class GoogleShortLinks::Parser < HTTParty::Parser
+  # Google returns the JSON response as a text/html mime type.
+  # This class only supports JSON currently.
   SupportedFormats = { 'text/html' => :json }
 
+  # Decodes JSON into a hash.
   def json
     MultiJson.decode(body)
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-short-links
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -14,7 +14,7 @@ default_executable:
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
-  requirement: &22456740 !ruby/object:Gem::Requirement
+  requirement: &26633460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,10 +22,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *22456740
+  version_requirements: *26633460
 - !ruby/object:Gem::Dependency
   name: multi_json
-  requirement: &22456100 !ruby/object:Gem::Requirement
+  requirement: &26632780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -33,10 +33,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *22456100
+  version_requirements: *26632780
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &22455460 !ruby/object:Gem::Requirement
+  requirement: &26632180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -44,10 +44,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *22455460
+  version_requirements: *26632180
 - !ruby/object:Gem::Dependency
   name: rcov
-  requirement: &22454860 !ruby/object:Gem::Requirement
+  requirement: &26631580 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -55,10 +55,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *22454860
+  version_requirements: *26631580
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: &22454260 !ruby/object:Gem::Requirement
+  requirement: &26630980 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -66,10 +66,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *22454260
+  version_requirements: *26630980
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &22453640 !ruby/object:Gem::Requirement
+  requirement: &26630340 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -77,10 +77,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *22453640
+  version_requirements: *26630340
 - !ruby/object:Gem::Dependency
   name: timecop
-  requirement: &22453020 !ruby/object:Gem::Requirement
+  requirement: &26629740 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -88,7 +88,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *22453020
+  version_requirements: *26629740
 description: Ruby wrapper for Google Short Links.
 email: benmanns@gmail.com
 executables: []
@@ -131,7 +131,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2703034883636259662
+      hash: -3436815904282187362
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: