ruby-oembed 0.7.6 → 0.8.1

data/.gitignore

@@ -1,2 +1,5 @@
 /pkg
-/.bundle
+/.bundle
+/rails_oembed
+/doc
+.DS_Store

data/CHANGELOG.rdoc

@@ -0,0 +1,49 @@
+= CHANGELOG
+
+== 0.8.1 - 27 February 2011
+
+* Removed all dependencies on external gems. XML is parsed using REXML and JSON can be parsed using YAML thanks to the convert_json_to_yaml method borrowed from Rails! (Marcos Wright Kuhns)
+* Fixed several errors that cropped up when the json gem wasn't installed. (Marcos Wright Kuhns)
+* OEmbed::Response#field now always return Strings. Previously, some JSON values were parsed into other Object types, like Integer and Float instances.
+* OEmbed::Response#url has been renamed OEmbed::Response#request_url because OEmbed::Response::Photo#url should be the URL of the static photo to be used by the oEmbed consumer.
+* OEmbed::Response.create_for now requires the format parameter.
+* OEmbed::Formatter backends won't try to load gems that haven't already been loaded. (Marcos Wright Kuhns)
+* Better code documentation, all around. (Marcos Wright Kuhns)
+
+=== Deprecations & Removals
+
+* Removed the OEmbed::Response::METHODS constant.
+* OEmbed::Provders::Pownce has been removed since pownce.com is no longer active.
+* Provider#url and Provider#name will be removed at some point in the future.
+* All direct raw calls will be made private at some point in the future (i.e. Provider#raw, Providers#raw, and ProviderDiscovery#raw)
+
+== 0.8.0 - Unreleased
+
+* Added OEmbed::Formatter Backends, to remove the dependency on the json gem and make adding support for other parsing libraries easier. This also fixes GitHub Issue =1. (Marcos Wright Kuhns)
+* Catch invalid endpoint URLs on OEmbed::Provider instantiation. (Marcos Wright Kuhns)
+* Jeweler uses the new OEmbed::Version Class. (Marcos Wright Kuhns)
+* Corrected syntax for Youtube provider in the README (Ryan Richards)
+* Removed the deprecated rails/init.rb file. (Marcos Wright Kuhns)
+
+== 0.7.6 - 11 October 2010
+
+* Released all recent changes to judofyr/master on GitHub. (Marcos Wright Kuhns)
+* Added CHANGELOG & LICENSE information. (Marcos Wright Kuhns)
+
+== 0.7.5 - 29 September 2010
+
+* Updated the list of {Embedly}[http://embed.ly] URL schemes. (Aris Bartee)
+* {rvmrc file}[http://rvm.beginrescueend.com/workflow/rvmrc/] added. (Aris Bartee)
+
+== 0.7.0 - 23 August 2010
+
+* Gemified. (Aris Bartee)
+* Added the {Embedly}[http://embed.ly] Provider. (Alex Kessinger)
+* OEmbed::Response now includes the original request url. (Colin Shea)
+* Unregistering providers with duplicate URL patterns works. (Marcos Wright Kuhns)
+
+== 0.0.0 - May 2008 - July 2010
+
+* Initial work & release as a library (Magnus Holm, et al.)
+* Many Providers supported, including {OohEmbed}[http://oohembed.com].
+* Support for JSON (via the json gem) and XML (via the xml-simple gem).

data/Gemfile.lock

@@ -1,25 +1,31 @@
 PATH
   remote: .
   specs:
-    ruby-oembed (0.7.6)
-      json
-      xml-simple
+    ruby-oembed (0.8.0)
 
 GEM
   remote: http://rubygems.org/
   specs:
+    diff-lcs (1.1.2)
     gemcutter (0.6.1)
     git (1.2.5)
     jeweler (1.4.0)
       gemcutter (>= 0.1.0)
       git (>= 1.2.5)
       rubyforge (>= 2.0.0)
-    json (1.4.6)
+    json (1.5.1)
     json_pure (1.4.6)
-    rspec (1.3.0)
+    rspec (2.5.0)
+      rspec-core (~> 2.5.0)
+      rspec-expectations (~> 2.5.0)
+      rspec-mocks (~> 2.5.0)
+    rspec-core (2.5.1)
+    rspec-expectations (2.5.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.5.0)
     rubyforge (2.0.4)
       json_pure (>= 1.1.7)
-    xml-simple (1.0.12)
+    xml-simple (1.0.14)
 
 PLATFORMS
   ruby
@@ -27,6 +33,5 @@ PLATFORMS
 DEPENDENCIES
   jeweler
   json
-  rspec
+  rspec (>= 2.0)
   ruby-oembed!
-  xml-simple

data/README.rdoc

@@ -0,0 +1,79 @@
+= ruby-oembed http://stillmaintained.com/metavida/ruby-oembed.png
+
+An oEmbed consumer library written in Ruby, letting you easily get embeddable HTML representations of supported web pages, based on their URLs. See {oembed.com}[http://oembed.com] for more about the protocol.
+
+= Installation
+
+  gem install ruby-oembed
+
+= Get Started
+
+== Providers
+
+Get information about a URL via an OEmbed::Provider. This library comes with many Providers built right in, to make your life easy.
+
+  resource = OEmbed::Providers::Youtube.get("http://www.youtube.com/watch?v=2BYXBC8WQ5k")
+  resource.video? #=> true
+  resource.thumbnail_url #=> "http://i3.ytimg.com/vi/2BYXBC8WQ5k/hqdefault.jpg"
+  resource.html #=> <<-HTML
+    <object width="425" height="344">
+      <param name="movie" value="http://www.youtube.com/v/2BYXBC8WQ5k?fs=1"></param>
+      <param name="allowFullScreen" value="true"></param>
+      <param name="allowscriptaccess" value="always"></param>
+      <embed src="http://www.youtube.com/v/2BYXBC8WQ5k?fs=1" type="application/x-shockwave-flash" width="425" height="344" allowscriptaccess="always" allowfullscreen="true"></embed>
+    </object>
+  HTML
+
+If you'd like to use a provider that isn't included in the library, it's easy to create one. Just provide the oEmbed API endpoint and URL scheme(s).
+
+  my_provider = OEmbed::Provider.new("http://my.cool-service.com/api/oembed_endpoint.{format}")
+  my_provider << "http://*.cool-service.com/image/*"
+  my_provider << "http://*.cool-service.com/video/*"
+  resource = my_provider.get("http://a.cool-service.com/video/1") #=> OEmbed::Response
+  resource.provider.name #=> "My Cool Service"
+
+To use multiple Providers at once, simply register them.
+
+  OEmbed::Providers.register(OEmbed::Providers::Youtube, my_provider)
+  resource = OEmbed::Providers.get("http://www.youtube.com/watch?v=2BYXBC8WQ5k") #=> OEmbed::Response
+  resource.type #=> "video"
+  resource.provider.name #=> "Youtube"
+
+Last but not least, ruby-oembed supports both {oohEmbed}[http://oohembed.com] and {Embedly}[http://embed.ly]. These services are provider aggregators. Each supports a wide array of websites ranging from {Amazon.com}[http://www.amazon.com] to {xkcd}[http://www.xkcd.com].
+
+== Formatters
+
+This library works wonderfully on it's on, but can get a speed boost by using 3rd party libraries to parse oEmbed data. To use a 3rd party Formatter, just be sure to require the library _before_ ruby-oembed.
+
+  require 'json'
+  require 'xmlsimple'
+  require 'oembed'
+  
+  OEmbed::Formatter::JSON.backend #=> OEmbed::Formatter::JSON::Backends::JSONGem
+  OEmbed::Formatter::XML.backend  #=> OEmbed::Formatter::XML::Backends::XmlSimple
+
+The following, optional, backends are currently supported:
+* The {JSON implementation for Ruby}[http://flori.github.com/json/]
+* Rails' ActiveSupport::JSON (confirmed to work with Rails 3.0.x and should work with Rails 2.0+)
+* {XmlSimple}[http://xml-simple.rubyforge.org/]
+
+= Lend a Hand
+
+Code for the ruby-oembed library is {hosted on GitHub}[http://github.com/judofyr/ruby-oembed].
+
+  # Get the code.
+  git clone git://github.com/judofyr/ruby-oembed.git
+  cd ruby-oembed
+  # Install all development-related gems.
+  gem install bundler
+  bundle install
+  # Run the tests.
+  rake specs
+
+If you encounter any bug, feel free to {create an Issue}[http://github.com/judofyr/ruby-oembed/issues].
+
+To submit a patch, please {fork}[http://help.github.com/forking/] the library and commit your changes along with relevant tests. Once you're happy with the changes, {send a pull request}[http://help.github.com/pull-requests/].
+
+= License
+
+This code is free to use under the terms of the MIT license.

data/Rakefile

@@ -1,17 +1,32 @@
+require File.expand_path(File.join(__FILE__, '../lib/oembed/version'))
+
 begin
   require 'jeweler'
+  
+  Dir[File.join(File.dirname(__FILE__), "lib/tasks/*.rake")].sort.each { |ext| load ext }
+  
   Jeweler::Tasks.new do |gemspec|
     gemspec.name = "ruby-oembed"
+    gemspec.version = OEmbed::Version
+    gemspec.homepage = "http://github.com/judofyr/ruby-oembed"
     gemspec.summary = "oEmbed for Ruby"
-    gemspec.description = "An oEmbed client written in Ruby, letting you easily get embeddable HTML representations of a supported web pages, based on their URLs. See http://oembed.com for more about the protocol."
+    gemspec.description = "An oEmbed consumer library written in Ruby, letting you easily get embeddable HTML representations of supported web pages, based on their URLs. See http://oembed.com for more information about the protocol."
+    gemspec.license = "MIT"
     gemspec.email = "arisbartee@gmail.com"
-    gemspec.homepage = "http://github.com/judofyr/ruby-oembed"
     gemspec.authors = ["Magnus Holm","Alex Kessinger","Aris Bartee","Marcos Wright Kuhns"]
-    gemspec.add_dependency("json")
-    gemspec.add_dependency("xml-simple")
-    gemspec.add_development_dependency("rspec")
+    gemspec.add_development_dependency("json")
+    gemspec.add_development_dependency("xml-simple")
+    gemspec.add_development_dependency("rspec", ">=2.0")
+    
+    gemspec.rdoc_options = %W(
+      --main README.rdoc
+      --title #{gemspec.full_name}
+      --inline-source
+      --exclude tasks
+      CHANGELOG.rdoc
+    )
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError
   puts "Jeweler not available. Install it with: gem install jeweler"
-end
+end

data/lib/oembed/errors.rb

@@ -1,28 +1,47 @@
 module OEmbed
+  
+  # A generic OEmbed-related Error. The OEmbed library does its best to capture all internal
+  # errors and wrap them in an OEmbed::Error class so that the error-handling code in your
+  # application can more easily identify the source of errors.
+  #
+  # The following Classes inherit from OEmbed::Error
+  # * OEmbed::FormatNotSupported
+  # * OEmbed::NotFound
+  # * OEmbed::ParseError
+  # * OEmbed::UnknownFormat
+  # * OEmbed::UnknownResponse
   class Error < StandardError
   end
 
-  class NotFound < OEmbed::Error
+  # This is a test
+  class NotFound < OEmbed::Error # :nodoc:
     def to_s
       "No embeddable content at '#{super}'"
     end
   end
 
-  class UnknownFormat < OEmbed::Error
+  class UnknownFormat < OEmbed::Error # :nodoc:
     def to_s
       "The provider doesn't support the '#{super}' format"
     end
   end
 
-  class FormatNotSupported < OEmbed::Error
+  class FormatNotSupported < OEmbed::Error # :nodoc:
     def to_s
       "This server doesn't have the correct libraries installed to support the '#{super}' format"
     end
   end
 
-  class UnknownResponse < OEmbed::Error
+  class UnknownResponse < OEmbed::Error # :nodoc:
     def to_s
       "Got unknown response (#{super}) from server"
     end
   end
+
+  class ParseError < OEmbed::Error # :nodoc:
+    def to_s
+      "There was an error parsing the server response (#{super})"
+    end
+  end
+    
 end

data/lib/oembed/formatter/json/backends/activesupportjson.rb

@@ -0,0 +1,28 @@
+# Only allow this backend if ActiveSupport::JSON is already loaded
+raise LoadError, "ActiveSupport::JSON isn't available. require 'activesupport/json'" unless defined?(ActiveSupport::JSON)
+
+module OEmbed
+  module Formatter
+    module JSON
+      module Backends
+        module ActiveSupportJSON
+          ParseError = ::ActiveSupport::JSON.parse_error
+          extend self
+
+          # Parses a JSON string or IO and convert it into an object.
+          def decode(json)
+            ::ActiveSupport::JSON.decode(json)
+          end
+        
+        end
+      end
+    end
+  end
+end
+
+# Only allow this backend if it parses JSON strings the way we expect it to
+begin
+  raise unless OEmbed::Formatter.test_backend(OEmbed::Formatter::JSON::Backends::ActiveSupportJSON)
+rescue
+  raise LoadError, "The version of ActiveSupport::JSON you have installed isn't parsing JSON like ruby-oembed expected."
+end

data/lib/oembed/formatter/json/backends/jsongem.rb

@@ -0,0 +1,31 @@
+# Only allow this backend the json gem is already loaded
+raise LoadError, "The json library isn't available. require 'json'" unless defined?(JSON)
+
+module OEmbed
+  module Formatter
+    module JSON
+      module Backends
+        module JSONGem
+          ParseError = ::JSON::ParserError
+          extend self
+
+          # Parses a JSON string or IO and convert it into an object.
+          def decode(json)
+            if json.respond_to?(:read)
+              json = json.read
+            end
+            ::JSON.parse(json)
+          end
+        
+        end
+      end
+    end
+  end
+end
+
+# Only allow this backend if it parses JSON strings the way we expect it to
+begin
+  raise unless OEmbed::Formatter.test_backend(OEmbed::Formatter::JSON::Backends::JSONGem)
+rescue
+  raise LoadError, "The version of the json library you have installed isn't parsing JSON like ruby-oembed expected."
+end

data/lib/oembed/formatter/json/backends/yaml.rb

@@ -0,0 +1,85 @@
+# Unlike other backends, require YAML if it's not already loaded
+require 'yaml' unless defined?(YAML)
+
+module OEmbed
+  module Formatter
+    module JSON
+      module Backends
+        # Use the YAML library, part of the standard library, to parse JSON values that has been converted to YAML.
+        module Yaml
+          ParseError = ::StandardError
+          extend self
+
+          # Parses a JSON string or IO and converts it into an object.
+          def decode(json)
+            if json.respond_to?(:read)
+              json = json.read
+            end
+            YAML.load(convert_json_to_yaml(json))
+          rescue ArgumentError
+            raise ParseError, "Invalid JSON string"
+          end
+
+          protected
+            # Ensure that ":" and "," are always followed by a space
+            def convert_json_to_yaml(json) #:nodoc:
+              require 'strscan' unless defined? ::StringScanner
+              scanner, quoting, marks, pos = ::StringScanner.new(json), false, [], nil
+              scanner.scan_until(/\{/)
+              while scanner.scan_until(/(\\['"]|['":,\\]|\\.)/)
+                case char = scanner[1]
+                when '"', "'"
+                  if !quoting
+                    quoting = char
+                    pos = scanner.pos
+                  elsif quoting == char
+                    quoting = false
+                  end
+                when ":",","
+                  marks << scanner.pos - 1 unless quoting
+                when "\\"
+                  scanner.skip(/\\/)
+                end
+              end
+              raise ParseError unless scanner.scan_until(/\}/)
+
+              if marks.empty?
+                raise ParseError
+              else
+                left_pos  = [-1].push(*marks)
+                right_pos = marks << scanner.pos + scanner.rest_size
+                output    = []
+                left_pos.each_with_index do |left, i|
+                  scanner.pos = left.succ
+                  chunk = scanner.peek(right_pos[i] - scanner.pos + 1)
+                  chunk.gsub!(/\\([\\\/]|u[[:xdigit:]]{4})/) do
+                    ustr = $1
+                    if ustr.index('u') == 0
+                      [ustr[1..-1].to_i(16)].pack("U")
+                    elsif ustr == '\\'
+                      '\\\\'
+                    else
+                      ustr
+                    end
+                  end
+                  output << chunk
+                end
+                output = output * " "
+
+                output.gsub!(/\\\//, '/')
+                output
+              end
+            end
+        
+        end
+      end
+    end
+  end
+end
+
+# Only allow this backend if it parses JSON strings the way we expect it to
+begin
+  raise unless OEmbed::Formatter.test_backend(OEmbed::Formatter::JSON::Backends::Yaml)
+rescue
+  raise LoadError, "The version of the YAML library you have installed isn't parsing JSON like ruby-oembed expected."
+end

data/lib/oembed/formatter/json.rb

@@ -0,0 +1,69 @@
+module OEmbed
+  module Formatter
+    # Handles parsing JSON values using the best available backend.
+    module JSON
+      # A Array of all available backends, listed in order of preference.
+      DECODERS = %w(ActiveSupportJSON JSONGem Yaml)
+      
+      class << self
+        
+        # Returns true if there is a valid JSON backend. Otherwise, raises OEmbed::FormatNotSupported
+        def supported?
+          !!backend
+        end
+        
+        # Parses a JSON string or IO and convert it into an object
+        def decode(json)
+          backend.decode(json)
+        end
+        
+        # Returns the current JSON backend.
+        def backend
+          set_default_backend unless defined?(@backend)
+          raise OEmbed::FormatNotSupported, :json unless defined?(@backend)
+          @backend
+        end
+
+        def backend=(name)
+          if name.is_a?(Module)
+            @backend = name
+          else
+            already_required = false
+            begin 
+              already_required = OEmbed::Formatter::JSON::Backends.const_defined?(name, false)
+            rescue ArgumentError # we're dealing with ruby < 1.9 where const_defined? only takes 1 argument, but behaves the way we want it to.
+              already_required = OEmbed::Formatter::JSON::Backends.const_defined?(name)
+            rescue NameError # no backends have been loaded yet
+              already_required = false
+            end
+            
+            require "oembed/formatter/json/backends/#{name.to_s.downcase}" unless already_required
+            @backend = OEmbed::Formatter::JSON::Backends::const_get(name)
+          end
+          @parse_error = @backend::ParseError
+        end
+        
+        def with_backend(name)
+          old_backend, self.backend = backend, name
+          yield
+        ensure
+          self.backend = old_backend
+        end
+
+        def set_default_backend
+          DECODERS.find do |name|
+            begin
+              self.backend = name
+              true
+            rescue LoadError
+              # Try next decoder.
+              false
+            end
+          end
+        end
+        
+      end
+      
+    end # JSON
+  end
+end

data/lib/oembed/formatter/xml/backends/rexml.rb

@@ -0,0 +1,44 @@
+# Unlike other backends, require REXML if it's not already loaded
+require 'rexml/document' unless defined?(REXML)
+
+module OEmbed
+  module Formatter
+    module XML
+      module Backends
+        # Use the REXML library, part of the standard library, to parse XML values.
+        module REXML
+          ParseError = ::REXML::ParseException
+          extend self
+
+          # Parses an XML string or IO and convert it into an object
+          def decode(xml)
+            if !xml.respond_to?(:read)
+              xml = StringIO.new(xml)
+            end
+            obj = {}
+            doc = ::REXML::Document.new(xml)
+            doc.elements[1].elements.each do |el|
+              obj[el.name] = el.text
+            end
+            obj
+          rescue
+            case $!
+            when ParseError
+              raise $!
+            else
+              raise ParseError, "Couldn't parse the given document."
+            end  
+          end
+        
+        end
+      end
+    end
+  end
+end
+
+# Only allow this backend if it parses XML strings the way we expect it to
+begin
+  raise unless OEmbed::Formatter.test_backend(OEmbed::Formatter::XML::Backends::REXML)
+rescue
+  raise LoadError, "The version of the REXML library you have installed isn't parsing XML like ruby-oembed expected."
+end

data/lib/oembed/formatter/xml/backends/xmlsimple.rb

@@ -0,0 +1,39 @@
+# Only allow this backend the xml-simple gem is already loaded
+raise ::LoadError, "The xml-simple library isn't available. require 'xmlsimple'" unless defined?(XmlSimple)
+
+module OEmbed
+  module Formatter
+    module XML
+      module Backends
+        # Use the xml-simple gem to parse XML values.
+        module XmlSimple
+          ParseError = ::ArgumentError
+          extend self
+
+          # Parses an XML string or IO and convert it into an object.
+          def decode(xml)
+            if !xml.respond_to?(:read)
+              xml = StringIO.new(xml)
+            end
+            ::XmlSimple.xml_in(xml, 'ForceArray'=>false)    
+          rescue
+            case $!
+            when ::ArgumentError
+              raise $!
+            else
+              raise ::ArgumentError, "Couldn't parse the given document."
+            end  
+          end
+        
+        end
+      end
+    end
+  end
+end
+
+# Only allow this backend if it parses XML strings the way we expect it to
+begin
+  raise unless OEmbed::Formatter.test_backend(OEmbed::Formatter::XML::Backends::XmlSimple)
+rescue
+  raise ::LoadError, "The version of the xml-simple library you have installed isn't parsing XML like ruby-oembed expected."
+end

data/lib/oembed/formatter/xml.rb

@@ -0,0 +1,76 @@
+module OEmbed
+  module Formatter
+    # Handles parsing XML values using the best available backend.
+    module XML
+      # A Array of all available backends, listed in order of preference.
+      DECODERS = %w(XmlSimple REXML)
+      
+      class << self
+        
+        # Returns true if there is a valid XML backend. Otherwise, raises OEmbed::FormatNotSupported
+        def supported?
+          !!backend
+        end
+        
+        # Parses an XML string or IO and convert it into an object
+        def decode(xml)
+          backend.decode(xml)
+        end
+        
+        # Returns the current XML backend.
+        def backend
+          set_default_backend unless defined?(@backend)
+          raise OEmbed::FormatNotSupported, :xml unless defined?(@backend)
+          @backend
+        end
+        
+        # Sets the current XML backend. Raises a LoadError if the given
+        # backend cannot be loaded
+        #   OEmbed::Formatter::XML.backend = 'REXML'
+        def backend=(name)
+          if name.is_a?(Module)
+            @backend = name
+          else
+            already_required = false
+            begin 
+              already_required = OEmbed::Formatter::XML::Backends.const_defined?(name, false)
+            rescue ArgumentError # we're dealing with ruby < 1.9 where const_defined? only takes 1 argument, but behaves the way we want it to.
+              already_required = OEmbed::Formatter::XML::Backends.const_defined?(name)
+            rescue NameError # no backends have been loaded yet
+              already_required = false
+            end
+            
+            require "oembed/formatter/xml/backends/#{name.to_s.downcase}" unless already_required
+            @backend = OEmbed::Formatter::XML::Backends.const_get(name)
+          end
+          @parse_error = @backend::ParseError
+        end
+        
+        # Perform a set of operations using a backend other than the current one.
+        #   OEmbed::Formatter::XML.with_backend('XmlSimple') do
+        #     OEmbed::Formatter::XML.decode(xml_value)
+        #   end
+        def with_backend(name)
+          old_backend, self.backend = backend, name
+          yield
+        ensure
+          self.backend = old_backend
+        end
+        
+        def set_default_backend
+          DECODERS.find do |name|
+            begin
+              self.backend = name
+              true
+            rescue LoadError
+              # Try next decoder.
+              false
+            end
+          end
+        end
+        
+      end
+      
+    end # XML
+  end
+end