open_graph_reader 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: fb82d8a9867ad4c1cf0258ef4e97f993cccdc6aa
+  data.tar.gz: ef67382716657161c2098380bf00c6abc48e6a4e
+SHA512:
+  metadata.gz: a60f2d67610ab9d1cd0587c58b92452f07fff77da489eec68c7906af650247bd42e26506a5d323f9d6ebe4b3bb247b7b26aba2dac5389634c660d80801b6f32b
+  data.tar.gz: 423fb2fe90278c64bd089579c5165c9ee468663c3d9eeb0661c1dfa0a5adc74f12a8772f7f5bdeff0d15ecb52493887d822e13a68dae31de98f9056636e21666

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "spec/fixtures/examples"]
+	path = spec/fixtures/examples
+	url = https://github.com/niallkennedy/open-graph-protocol-examples.git

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.yardopts

@@ -0,0 +1 @@
+--no-private

data/lib/open_graph_reader.rb

@@ -0,0 +1,83 @@
+require 'uri'
+
+begin
+  require 'faraday_middleware/response/follow_redirects'
+rescue LoadError; end
+
+require 'open_graph_reader/base'
+require 'open_graph_reader/builder'
+require 'open_graph_reader/definitions'
+require 'open_graph_reader/fetcher'
+require 'open_graph_reader/object'
+require 'open_graph_reader/parser'
+require 'open_graph_reader/version'
+
+# @todo  quirks mode where invalid attributes don't raise?
+# @todo 1.1 compatibility mode?
+# This module provides the main entry to the library. Please see the
+# {file:README.md} for usage examples.
+module OpenGraphReader
+  # Fetch the OpenGraph object at the given URL. Raise if there are any issues.
+  #
+  # @param [URI,#to_s] url The URL of the OpenGraph object to retrieve.
+  # @return [Base] The base object from which you can obtain the root objects.
+  # @raise [NoOpenGraphDataError] {include:NoOpenGraphDataError}
+  # @raise [InvalidObjectError] {include:InvalidObjectError}
+  def self.fetch! url
+    case url
+    when URI
+      target = Fetcher.new(url)
+      raise NoOpenGraphDataError, "#{url} doesn't contain any HTML" unless target.html?
+      parse! target.body, target.url
+    else
+      fetch! URI.parse(url.to_s)
+    end
+  end
+
+  # Parse the OpenGraph object in the given HTML document. Raise if there are any issues.
+  #
+  # @param [#to_s, Nokogiri::XML::Node] html A HTML document that contains an OpenGraph object.
+  # @param [#to_s] origin The source from where the given document was fetched.
+  # @return [Base] The base object from which you can obtain the root objects.
+  # @raise [NoOpenGraphDataError] {include:NoOpenGraphDataError}
+  # @raise [InvalidObjectError] {include:InvalidObjectError}
+  def self.parse! html, origin=nil
+    parser = Parser.new html
+    raise NoOpenGraphDataError, "#{origin || html} does not contain any OpenGraph tags" unless parser.has_tags?
+    Builder.new(parser.graph, parser.additional_namespaces).base.tap {|base|
+      base.origin = origin.to_s if origin
+    }
+  end
+
+  # Convenience wrapper around {OpenGraphReader.fetch!} that swallows the esceptions
+  # and returns nil instead.
+  #
+  # @param [URI,#to_s] url The URL of the OpenGraph object to retrieve.
+  # @return [Base, nil] The base object from which you can obtain the root objects.
+  # @see OpenGraphReader.fetch!
+  def self.fetch url
+    fetch! url
+  rescue NoOpenGraphDataError, InvalidObjectError
+  end
+
+  # Convenience wrapper around {OpenGraphReader.parse!} that swallows the esceptions
+  # and returns nil instead.
+  #
+  # @param [#to_s] html A HTML document that contains an OpenGraph object.
+  # @param [#to_s] origin The source from where the given document was fetched.
+  # @return [Base, nil] The base object from which you can obtain the root objects.
+  # @see OpenGraphReader.parse!
+  def self.parse html, origin=nil
+    parse! html, origin
+  rescue NoOpenGraphDataError, InvalidObjectError
+  end
+
+  # The target couldn't be fetched, didn't contain any HTML or
+  # any OpenGraph tags.
+  class NoOpenGraphDataError < StandardError
+  end
+
+  # The target did contain OpenGraph tags, but they're not valid.
+  class InvalidObjectError < StandardError
+  end
+end

data/lib/open_graph_reader/base.rb

@@ -0,0 +1,57 @@
+require 'forwardable'
+
+module OpenGraphReader
+  # You get an instance of this class as result of your quest to obtain
+  # an OpenGraph object. It simply contains and returns the root objects,
+  # most commonly <tt>og</tt>.
+  class Base
+    extend Forwardable
+
+    # @!method [](name)
+    #   Get a root object by name.
+    #
+    #   @param [String] name The name of the root namespace.
+    #   @return [Object, nil] The corresponding root object if available.
+    #   @api private
+    # @!method []=(name, object)
+    #   Make a new root object available on this base.
+    #
+    #   @param [String] name The name of the root namespace.
+    #   @param [Object] object The corresponding root object.
+    #   @api private
+    def_delegators :@bases, :[], :[]=
+
+    # If available, contains the source location of the document the
+    # available objects were parsed from.
+    #
+    # @return [String, nil]
+    attr_reader :origin
+
+    # Set origin.
+    #
+    # @api private
+    # @see #origin
+    attr_writer :origin
+
+    # @api private
+    def initialize
+      @bases = {}
+    end
+
+    # @private
+    def respond_to_missing?(method, include_private=false)
+      @bases.has_key? method.to_s
+    end
+
+    # Makes the found root objects available.
+    # @return [Object]
+    def method_missing(method, *args, &block)
+      name = method.to_s
+      if respond_to_missing? name
+        @bases[name]
+      else
+        super(method, *args, &block)
+      end
+    end
+  end
+end

data/lib/open_graph_reader/builder.rb

@@ -0,0 +1,100 @@
+module OpenGraphReader
+  # Convert a {Parser::Graph} into the right hierarchy of {Object}s attached
+  # to a {Base}.
+  #
+  # @todo validate required, verticals
+  # @api private
+  class Builder
+    # Well-known types from
+    #
+    # @see http://ogp.me
+    KNOWN_TYPES = %w(
+      website
+      music.song
+      music.album
+      music.playlist
+      music.radio_station
+      video.movie
+      video.episode
+      video.tv_show
+      video.other
+      article
+      book
+      profile
+    ).freeze
+
+    # Create a new builder.
+    #
+    # @param [Parser::Graph] graph
+    # @param [Array<String>] additional_namespaces Namespaces found in the
+    #   prefix attribute of the head tag of the HTML document
+    # @see Parser#graph
+    # @see Parser#additional_namespaces
+    def initialize graph, additional_namespaces=[]
+      @graph = graph
+      @additional_namespaces = additional_namespaces
+    end
+
+    # Build and return the base.
+    #
+    # @return [Base]
+    def base
+      base = Base.new
+
+      type = @graph.fetch 'og:type', 'website'
+
+      validate_type type
+
+      @graph.each do |property|
+        root, *path, name = property.path
+        base[root] ||= Object::Registry[root].new
+        object = resolve base[root], root, path
+
+        if object.respond_to? "#{name}s" # Collection # TODO
+          collection = object.public_send "#{name}s" #TODO
+          if Object::Registry.registered? property.fullname # of subobjects
+            object = Object::Registry[property.fullname].new
+            collection << object
+            object.content = property.content
+          else # of type
+            collection << property.content
+          end
+        elsif Object::Registry.registered? property.fullname # Subobject
+          object[name] ||= Object::Registry[property.fullname].new
+          object[name].content = property.content
+        else # Direct attribute
+          object[name] = property.content
+        end
+      end
+
+      base
+    end
+
+    private
+
+    def resolve object, last_namespace, path
+      return object if path.empty?
+
+      next_name = path.shift
+      if object.respond_to? "#{next_name}s" # collection # TODO: do not respond_to? with user data
+        collection = object.public_send("#{next_name}s") # TODO: do not public_send with user data
+        next_object = collection.last
+        if next_object.nil? #|| path.empty? # Final namespace or missing previous declaration, create a new collection item
+          next_object = Object::Registry[[*last_namespace, next_name].join(':')].new
+          collection << next_object
+        end
+      else
+        next_object = object[next_name]
+        next_object ||= Object::Registry[[*last_namespace, next_name].join(':')].new
+      end
+
+      next_object
+    end
+
+    def validate_type type
+      unless KNOWN_TYPES.include?(type) || @additional_namespaces.include?(type)
+        raise InvalidObjectError, "Undefined type #{type}"
+      end
+    end
+  end
+end

data/lib/open_graph_reader/definitions.rb

@@ -0,0 +1,333 @@
+require 'open_graph_reader/object'
+
+module OpenGraphReader
+  # @see http://ogp.me/#metadata
+  class Og
+    include Object
+
+    namespace :og
+
+    # @!macro property
+    # @return [String]
+    string :type,  required: true, default: 'website'
+
+    # @!macro property
+    # @return [String]
+    string :title, required: true
+
+    # @!attribute [r] images
+    #   @return [Array<Image>]
+    # @!macro property
+    # @return [Image]
+    url    :image, required: true, collection: true
+
+    # @!macro property
+    # @return [String, nil]
+    url    :url
+
+    # @!macro property
+    # @return [Audio, nil]
+    url    :audio
+
+    # @!macro property
+    # @return [String, nil]
+    string :description
+
+    # @!macro property
+    # @return [String]
+    enum   :determiner, ['', 'a', 'an', 'the', 'auto'], default: ''
+
+    # @!macro property
+    # @return [Locale, nil]
+    string :locale
+
+    # @!macro property
+    # @return [String, nil]
+    string :site_name
+
+    # @!macro property
+    # @return [Video, nil]
+    url    :video
+
+    # @see http://ogp.me/#structured
+    class Image
+      include Object
+
+      namespace :og, :image
+      content :url
+
+      url     :url
+
+      # @!macro property
+      # @return [String, nil]
+      url     :secure_url
+
+      # @!macro property
+      # @return [String, nil]
+      string  :type
+
+      # @!macro property
+      # @return [Integer, nil]
+      integer :width
+
+      # @!macro property
+      # @return [Integer, nil]
+      integer :height
+
+      # @return [String, nil]
+      def url
+        secure_url || properties[:url] || content
+      end
+    end
+
+    # @see http://ogp.me/#structured
+    class Audio
+      include Object
+
+      namespace :og, :audio
+      content :url
+
+      # This property is not listed on http://ogp.me, but commonly found
+      url    :url
+
+      # @!macro property
+      # @return [String, nil]
+      url    :secure_url
+
+      # @!macro property
+      # @return [String, nil]
+      string :type
+
+      # @return [String, nil]
+      def url
+        secure_url || properties[:url] || content
+      end
+    end
+
+    # @see http://ogp.me/#metadata
+    class Locale
+      include Object
+
+      namespace :og, :locale
+      content :string
+
+      # @!attribute [r] alternates
+      #   @return [Array<String>]
+      # @!macro property
+      # @return [String, nil]
+      string :alternate, collection: true
+    end
+
+    # @see http://ogp.me/#structured
+    class Video
+      include Object
+
+      namespace :og, :video
+      content :url
+
+      # @!macro property
+      # @return [String, nil]
+      url     :secure_url
+
+      # @!macro property
+      # @return [String, nil]
+      string  :type
+
+      # @!macro property
+      # @return [Integer, nil]
+      integer :width
+
+      # @!macro property
+      # @return [Integer, nil]
+      integer :height
+
+      # @return [String, nil]
+      def url
+        secure_url || content
+      end
+    end
+  end
+
+  # @see http://ogp.me/#type_profile
+  class Profile
+    include Object
+
+    namespace :profile
+    content :url
+
+    # @!macro property
+    # @return [String, nil]
+    string :first_name
+
+    # @!macro property
+    # @return [String, nil]
+    string :last_name
+
+    # @!macro property
+    # @return [String, nil]
+    string :username
+
+    # @!macro property
+    # @return [String, nil]
+    enum   :gender, %w(male female)
+
+    # @!macro property
+    # @return [String, nil]
+    # This one only exists because video had to define a video:actor:role,
+    # yay for designing a protocol with implementations in mind
+    string :role
+  end
+
+  # @see http://ogp.me/#type_article
+  class Article
+    include Object
+
+    namespace :article
+
+    # @!macro property
+    # @return [DateTime, nil]
+    datetime :published_time
+
+    # @!macro property
+    # @return [DateTime, nil]
+    datetime :modified_time
+
+    # @!macro property
+    # @return [DateTime, nil]
+    datetime :expiration_time
+
+    # @todo This one is a reference to another OpenGraph object. Support fetching it?
+    # @!attribute [r] authors
+    #   @return [Array<Profile>]
+    # @!macro property
+    # @return [Profile, nil]
+    url      :author, collection: true, to: Profile
+
+    # @!macro property
+    # @return [String, nil]
+    string   :section
+
+    # @!attribute [r] tags
+    #   @return [Array<String>]
+    # @!macro property
+    # @return [String, nil]
+    string   :tag, collection: true
+  end
+
+  # @see http://ogp.me/#type_video
+  class Video
+    include Object
+
+    namespace :video
+
+    # @!attribute [r] actors
+    #  @return [Array<Profile>]
+    # @!macro property
+    # @return [Profile, nil]
+    url      :actor,    to: Profile, verticals: %w(movie episode tv_show other), collection: true
+
+    # @!attribute [r] directors
+    #  @return [Array<Profile>]
+    # @!macro property
+    # @return [Profile, nil]
+    url      :director, to: Profile, verticals: %w(movie episode tv_show other), collection: true
+
+    # @!attribute [r] writers
+    #  @return [Array<Profile>]
+    # @!macro property
+    # @return [Profile, nil]
+    url      :writer,   to: Profile, verticals: %w(movie episode tv_show other), collection: true
+
+    # @!macro property
+    # @return [Integer, nil]
+    integer  :duration,              verticals: %w(movie episode tv_show other)
+
+    # @!macro property
+    # @return [DateTime, nil]
+    datetime :release_date,          verticals: %w(movie episode tv_show other)
+
+    # @!attribute [r] tags
+    #   @return [Array<String>]
+    # @!macro property
+    # @return [String, nil]
+    string   :tag,                   verticals: %w(movie episode tv_show other), collection: true
+
+    # @todo validate that target vertical is video.tv_show ?
+    # @!macro property
+    # @return [Sring, nil]
+    url      :series,   to: Video,   verticals: %w(episode)
+  end
+
+  # @see http://ogp.me/#type_book
+  class Book
+    include Object
+
+    namespace :book
+
+    # @todo This one is a reference to another OpenGraph object. Support fetching it?
+    # @!attribute [r] authors
+    #   @return [Array<Profile>]
+    # @!macro property
+    # @return [Profile, nil]
+    url :author, collection: true, to: Profile
+
+    # @!macro property
+    # @return [Sring, nil]
+    string :isbn
+
+    # @!macro property
+    # @return [DateTime, nil]
+    datetime :release_date
+
+    # @!attribute [r] tags
+    #   @return [Array<String>]
+    # @!macro property
+    # @return [String, nil]
+    string :tag, collection: true
+  end
+
+  # @see http://ogp.me/#type_music
+  class Music
+    include Object
+
+    namespace :music
+
+    # @!macro property
+    # @return [Integer, nil]
+    integer :duration, verticals: %w(song)
+
+
+    # @todo validate that target vertical is music.album/music.song ?
+    # @!attribute [r] albums
+    #   @return [Array<Music>]
+    # @macro property
+    # @return [Music, nil]
+    url      :album,    to: Music,   verticals: %w(song),       collection: true
+
+    # @macro property
+    # @return [Integer, nil]
+    integer  :disc,                  verticals: %w(song album playlist)
+
+    # @macro property
+    # @return [Integer, nil]
+    integer  :track,                 verticals: %w(song album playlist)
+
+    # @!attribute [r] musicians
+    #  @return [Array<Profile>]
+    # @!macro property
+    # @return [Profile, nil]
+    url      :musician, to: Profile, verticals: %w(song album), collection: true
+
+    # @macro property
+    # @return [Music, nil]
+    url      :song,     to: Music,   verticals: %w(album playlist)
+
+    # @macro property
+    # @return [DateTime, nil]
+    datetime :release_date,          verticals: %w(album)
+
+    # @macro property
+    # @return [Profile, nil]
+    url      :creator,  to: Profile, verticals: %w(playlist radio_station)
+  end
+end