open_graph_reader 0.1.0

data/lib/open_graph_reader/fetcher.rb

@@ -0,0 +1,82 @@
+require 'faraday'
+
+module OpenGraphReader
+  # Fetch an URI to retrieve its HTML body, if available.
+  #
+  # @api private
+  class Fetcher
+    # Create a new fetcher.
+    #
+    # @param [URI] uri the URI to fetch.
+    def initialize uri
+      raise ArgumentError, "url needs to be an instance of URI" unless uri.is_a? URI
+      @uri = uri
+      @connection = Faraday.default_connection.dup
+
+      if defined? FaradayMiddleware
+        unless @connection.builder.handlers.include? FaradayMiddleware::FollowRedirects
+          @connection.builder.insert(0, FaradayMiddleware::FollowRedirects)
+        end
+      end
+    end
+
+    # The URL to fetch
+    #
+    # @return [String]
+    def url
+      @uri.to_s
+    end
+
+    # Fetch the full page.
+    #
+    # @return [Faraday::Response]
+    def fetch
+      @get_response = @connection.get(@uri)
+    end
+    alias_method :fetch_body, :fetch
+
+    # Fetch just the headers
+    #
+    # @return [Faraday::Response]
+    def fetch_headers
+      @head_response = @connection.head(@uri)
+    end
+
+    # Retrieve the body
+    #
+    # @todo Custom error class
+    # @raise [ArgumentError] The received content does not seems to be HTML.
+    # @return [String]
+    def body
+      fetch_body unless fetched?
+      raise ArgumentError, "Did not receive a HTML site at #{@uri}" unless html?
+      @get_response.body
+    end
+
+    # Whether the target URI seems to return HTML
+    #
+    # @return [Bool]
+    def html?
+      fetch_headers unless fetched_headers?
+      response = @get_response || @head_response
+      return false unless response.success?
+      return false unless response['content-type']
+      response['content-type'].include? 'text/html'
+    end
+
+    # Whether the target URI was fetched.
+    #
+    # @return [Bool]
+    def fetched?
+      !@get_response.nil?
+    end
+    alias_method :fetched_body?, :fetched?
+
+    # Whether the headers of the target URI were fetched.
+    #
+    # @return [Bool]
+    def fetched_headers?
+      !@get_response.nil? || !@head_response.nil?
+    end
+  end
+end

data/lib/open_graph_reader/object.rb

@@ -0,0 +1,95 @@
+require 'open_graph_reader/object/registry'
+require 'open_graph_reader/object/dsl'
+require 'open_graph_reader/object/dsl/types'
+
+module OpenGraphReader
+
+  # This module provides the base functionality for all OpenGraph objects
+  # and makes the {DSL} methods for describing them available when included.
+  #
+  # @example Define a new object
+  #   class MyObject
+  #     include OpenGraphReader::Object
+  #
+  #      namespace :my, :object
+  #      content :string
+  #      string :name, required: true
+  #   end
+  module Object
+    # @private
+    def self.included base
+      base.extend DSL
+    end
+
+    # If the namespace this object represents had a value, it is available here
+    # @return [String, nil]
+    attr_reader :content
+
+    # Regular properties on this object
+    #
+    # @api private
+    # @return [{String => String, Object}]
+    attr_reader :properties
+
+    # Properties on this object that are arrays.
+    #
+    # @api private
+    # @return [{String => Array<String, Object>}]
+    attr_reader :children
+
+
+    # Create a new object. If your class overrides this don't forget to call <tt>super</tt>.
+    def initialize
+      @properties = {}
+      @children = Hash.new {|h, k| h[k] = [] }
+    end
+
+    # Whether this object has the given property
+    #
+    # @param [#to_s] name
+    # @return [Bool]
+    def has_property? name
+      self.class.available_properties.include? name.to_s
+    end
+
+    # Set the content for this object in case it is also a property on
+    # another object. If a processor is defined, it will be called.
+    #
+    # @api private
+    # @param [String] value
+    def content= value
+      value = self.class.content_processor.call(value)
+      @content = value
+    end
+
+    # Get a property on this object.
+    #
+    # @api private
+    # @param [#to_s] name
+    # @todo right error?
+    # @raise [InvalidObjectError] If the requested property is undefined.
+    # @return [String, Object]
+    def [] name
+      raise InvalidObjectError, "Undefined property #{name} on #{inspect}" unless has_property? name
+      properties[name.to_s]
+    end
+
+    # Set the property to the given value.
+    #
+    # @api private
+    # @param [#to_s] name
+    # @param [String, Object] value
+    # @raise [InvalidObjectError] If the requested property is undefined.
+    def []= name, value
+      raise InvalidObjectError, "Undefined property #{name} on #{inspect}" unless has_property? name
+      public_send "#{name}=", value
+    end
+
+    # Returns {#content} if available.
+    #
+    # @return [String]
+    def to_s
+      content || super
+    end
+  end
+end

data/lib/open_graph_reader/object/dsl.rb

@@ -0,0 +1,130 @@
+require 'open_graph_reader/object/registry'
+
+module OpenGraphReader
+  module Object
+    # This module provides the methods to define new types and properties,
+    # as well as setting other metadata necessary to describe an object, such
+    # as its namespace.
+    module DSL
+      # @!macro define_type_description
+      #   @param [Symbol] name the name of the property in the current namespace
+      #   @param [{Symbol => Bool, Class, Array<String>}] options additional options
+      #   @option options [Bool] :required (false) Make the property required.
+      #   @option options [Bool] :collection (false) This property can occur multiple times.
+      #   @option options [Class] :to This property maps to the given object (optional).
+      #     belongs to the given verticals of the object (optional).
+      #   @option options [Array<String>] :verticials This property
+      #
+      # @!macro property
+      #   @!attribute [rw] $1
+
+      # @!macro [attach] define_type
+      #   @!method $1(name, options={})
+      #     @!macro define_type_description
+      #
+      # Defines a new DSL method for modeling a new type
+      #
+      # @yield  convert and validate
+      # @yieldparam [::Object] value the value to be converted and validated
+      # @yieldparam [Array<::Object>] *args any additional arguments
+      # @yieldparam [{Symbol => Bool, Class, Array<String>}] options the options hash as last parameter
+      def self.define_type(name, &processor)
+        processors[name] = processor
+
+        define_method(name) do |name, *args|
+          available_properties << name.to_s
+          options = args.pop if args.last.is_a? Hash
+          options ||= {}
+
+          Registry.register [@namespace, name].join(':'), options[:to] if options[:to]
+
+          if options[:verticals]
+            options[:verticals].each do |vertical|
+              verticals[[@namespace, vertical].join('.')] << name
+            end
+          end
+
+          if options[:collection]
+            define_method("#{name}s") do
+              children[name.to_s]
+            end
+
+            define_method(name) do
+              # TODO raise if required
+              value = children[name.to_s].first
+              # TODO: figure out a sane way to distinguish subobject properties
+              value.content if value && value.is_a?(Object)
+              value || options[:default]
+            end
+          else
+            define_method(name) do
+              # TODO raise if required
+              properties[name.to_s] || options[:default]
+            end
+
+            define_method("#{name}=") do |value|
+              # TODO: figure out a sane way to distinguish subobject properties
+              value = processor.call(value, *args, options) unless value.is_a? Object
+              properties[name.to_s] = value
+            end
+          end
+        end
+      end
+      singleton_class.send(:alias_method, :define_type_with_args, :define_type)
+
+      # @overload namespace
+      #   Get the namespace of this object.
+      #
+      #   @return [String] A colon separated namespace, for example <tt>og:image</tt>.
+      # @overload namespace(*names)
+      #   Set the namespace of this object.
+      #
+      #   @param [Array<#to_s>] *names The individual parts of the namespace as list
+      #   @example
+      #     namespace :og, :image
+      def namespace *names
+        return @namespace if names.empty?
+        @namespace = names.join(':')
+        Registry.register @namespace, self
+      end
+
+      # Set the type for the content attribute
+      #
+      # @param [Symbol] type one of the registered types.
+      def content type
+        @content_processor = DSL.processors[type]
+      end
+
+      # The list of defined properties on this object.
+      #
+      # @return [Array<String>]
+      def available_properties
+        @available_properties ||= []
+      end
+
+      # A map from type names to processing blocks.
+      #
+      # @api private
+      # @return [{Symbol => Proc}]
+      def self.processors
+        @processors ||= {}
+      end
+
+      # The processor for the content attribute.
+      #
+      # @api private
+      # @return [Proc]
+      def content_processor
+        @content_processor || proc {|value| value }
+      end
+
+      # A map from vertical names to attributes that belong to them.
+      #
+      # @api private
+      # @return [{String => Array<Strin>}]
+      def verticals
+        @verticals ||= Hash.new {|h, k| h[k] = [] }
+      end
+    end
+  end
+end

data/lib/open_graph_reader/object/dsl/types.rb

@@ -0,0 +1,71 @@
+require 'date'
+
+require 'open_graph_reader/object/dsl'
+
+module OpenGraphReader
+  module Object
+    module DSL
+      # @see http://ogp.me/#string
+      define_type :string do |value|
+        value.to_s
+      end
+
+      # @see http://ogp.me/#url
+      define_type :url do |value|
+        value.to_s.tap {|value|
+          unless value.start_with?('http://') || value.start_with?('https://')
+            raise InvalidObjectError, "URL #{value.inspect} does not start with http:// or https://"
+          end
+        }
+      end
+
+      # @!method enum(name, allowed, options={})
+      #   @param [Array<String>] allowed the list of allowed values
+      #   @!macro define_type_description
+      # @see http://ogp.me/#enum
+      define_type_with_args :enum do |value, allowed|
+        unless allowed.include? value
+          raise InvalidObjectError, "Expected one of #{allowed.inspect} but was #{value.inspect}"
+        end
+
+        value.to_s
+      end
+
+      # @see http://ogp.me/#integer
+      define_type :integer do  |value|
+        begin
+          Integer(value)
+        rescue  ArgumentError => e
+          raise InvalidObjectError, "Integer expected, but was #{value.inspect}"
+        end
+      end
+
+      # @see http://ogp.me/#datetime
+      define_type :datetime do |value|
+        begin
+          DateTime.iso8601 value
+        rescue ArgumentError => e
+          raise InvalidObjectError, "ISO8601 datetime expected, but was #{value.inspect}"
+        end
+      end
+
+      # @see http://ogp.me/#bool
+      define_type :boolean do |value|
+        {'true' => true, 'false' => false, '1' => true, '0' => false}[value].tap {|bool|
+          if bool.nil?
+            raise InvalidObjectError, "Boolean expected, but was #{value.inspect}"
+          end
+        }
+      end
+
+      # @see http://ogp.me/#float
+      define_type :float do |value|
+        begin
+          Float(value)
+        rescue ArgumentError => e
+          raise InvalidObjectError, "Float expected, but was #{value.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/open_graph_reader/object/registry.rb

@@ -0,0 +1,54 @@
+require 'singleton'
+require 'forwardable'
+
+module OpenGraphReader
+  module Object
+    # Global registry of namespaces and their representing classes.
+    #
+    # @api private
+    class Registry
+      extend Forwardable
+      include Singleton
+
+      class << self
+        extend Forwardable
+        # @!method register(namespace, klass)
+        #   Register a new namespace in the registry.
+        #
+        #   @param [String] namespace The namespace in colon separated form, for example <tt>og:image</tt>.
+        #   @param [Class] klass The class to register. It should include {Object}.
+        #   @api private
+        #
+        # @!method registered?(namespace)
+        #   Check whether a namespace is registered.
+        #
+        #   @param [String] namespace The namespace in colon separated form, for example <tt>og:image</tt>.
+        #   @return [Bool]
+        #   @api private
+        #
+        # @!method [](namespace)
+        #   Fetch the class associated with the given namespace
+        #
+        #   @param [String] namespace The namespace in colon separated form, for example <tt>og:image</tt>.
+        #   @return [Class] The matching class.
+        #   @raise [ArgumentError] If the given namespace wasn't registered.
+        #   @api private
+        def_delegators :instance, :register, :registered?, :[]
+      end
+
+      def_delegators :@namespaces, :[]=, :has_key?
+      alias_method :register, :[]=
+      alias_method :registered?,  :has_key?
+
+      def initialize
+        @namespaces = {}
+      end
+
+      # @see Registry.[]
+      def [] namespace
+        raise ArgumentError, "#{namespace} is not a registered namespace" unless registered? namespace
+        @namespaces[namespace]
+      end
+    end
+  end
+end

data/lib/open_graph_reader/parser.rb

@@ -0,0 +1,85 @@
+require 'nokogiri'
+
+require 'open_graph_reader/parser/graph'
+
+module OpenGraphReader
+  # Parse OpenGraph tags in a HTML document into a graph.
+  #
+  # @api private
+  class Parser
+    # Namespaces found in the passed documents head tag
+    #
+    # @return [Array<String>]
+    attr_reader :additional_namespaces
+
+    # Create a new parser.
+    #
+    # @param [#to_s, Nokogiri::XML::Node] html the document to parse.
+    # @param [String] origin The source the document was obtained from.
+    def initialize html, origin=nil
+      @doc = to_doc html
+      @origin = origin
+      @additional_namespaces = []
+    end
+
+    # Whether there are any OpenGraph tags at all.
+    #
+    # @return [Bool]
+    def has_tags?
+      !graph.empty?
+    end
+
+    # Build and return the {Graph}.
+    #
+    # @return [Graph]
+    def graph
+      @graph ||= build_graph
+    end
+
+    private
+
+    def build_graph
+      graph = Graph.new
+      head = @doc.xpath('/html/head').first
+
+      raise NoOpenGraphDataError, "There's no head tag in #{@doc}" unless head
+
+      condition = "starts-with(@property, 'og:')"
+      if head['prefix']
+        @additional_namespaces = head['prefix'].scan(/(\w+):\s*([^ ]+)/).map(&:first)
+        @additional_namespaces.each do |additional_namespace|
+          next if additional_namespace == 'og'
+          condition << " or starts-with(@property, '#{additional_namespace}')"
+        end
+      end
+
+      head.xpath("meta[#{condition}]").each do |tag|
+        *path, leaf = tag['property'].split(':')
+        node = path.inject(graph.root) {|node, name|
+          child = node.children.reverse.find {|child| child.name == name }
+
+          unless child
+            child = Graph::Node.new name
+            node << child
+          end
+
+          child
+        }
+
+        # TODO: make stripping configurable?
+        node << Graph::Node.new(leaf, tag['content'].strip)
+      end
+
+      graph
+    end
+
+    def to_doc html
+      case html
+      when Nokogiri::XML::Node
+        html
+      else
+        Nokogiri::HTML.parse(html.to_s)
+      end
+    end
+  end
+end