fogli 0.1.0

data/lib/fogli/facebook_object.rb

@@ -0,0 +1,225 @@
+require 'fogli/facebook_object/properties'
+require 'fogli/facebook_object/connections'
+
+module Fogli
+  # Represents any facebook object. This exposes the common
+  # abstractions used by every other facebook object such as the
+  # concept of properties and connections.
+  #
+  # # Finding an Object
+  #
+  # To find any Facebook object, use the {find} method. The find
+  # method is _lazy_, meaning that it doesn't actually make the HTTP
+  # request to Facebook then, but instead defers the call to when the
+  # first property is accessed.
+  #
+  #     user = Fogli::User["mitchellh"]
+  #     user.first_name # HTTP request is made here
+  #     user.last_name  # Loaded already so not request is made
+  #
+  # # Finding an Object, but Selecting Specific Fields
+  #
+  # To conserve bandwidth and lower transfer time, you can select only
+  # specific fields of an object. An example is shown below:
+  #
+  #     user = Fogli::User.find("mitchellh", :fields => [:first_name, :last_name])
+  #     user.first_name # "Mitchell"
+  #     user.link       # nil, since we didn't request it
+  #
+  # # Checking if an Object Exists
+  #
+  # Since objects are lazy loaded, you can't check the return value of
+  # {find} to see if an object exists. Instead, you must use the
+  # dedicated {exist?} or {#exist?} methods. The difference is
+  # outlined below:
+  #
+  # * {#exist?} loads all of the data associated with an instance to
+  #   check for existence, so that the data is ready to go on a property
+  #   access.
+  # * {exist?} only loads the ID of an object, which uses less
+  #   bandwidth and has less overhead associated with it. This is ideal
+  #   for only checking if an object exists, but not caring about the
+  #   properties.
+  #
+  class FacebookObject < FacebookGraph
+    autoload :ConnectionProxy, 'fogli/facebook_object/connection_proxy'
+    autoload :ConnectionScope, 'fogli/facebook_object/connection_scope'
+    autoload :ScopeMethods, 'fogli/facebook_object/scope_methods'
+
+    include Properties
+    include Connections
+    extend Util::Options
+
+    attr_reader :_fields
+    attr_reader :_raw
+
+    # Every facebook object has an id and typically an updated time
+    # (if authorized)
+    property :id, :updated_time
+
+    class << self
+      # Finds the facebook object associated with the given `id`. The
+      # object is **not loaded** until the first property access. To
+      # check if an object exists, you can call {#exist?} on the
+      # object itself, which will proceed to load all the relevant
+      # properties as well. Or, you can use the class-level {exist?}
+      # if you only care about if the object exists, but not about
+      # it's properties.
+      #
+      # For examples on how to use this method, please view the
+      # documentation for the entire {FacebookObject} class.
+      #
+      # @param [String] id ID of the object
+      #   above.
+      # @param [Hash] options Options such as `fields`.
+      # @return [FacebookObject]
+      def find(id, options=nil)
+        data = { :_loaded => false, :id => id }
+        options = verify_options(options, :valid_keys => [:fields])
+        data[:_fields] = []
+        data[:_fields] << [options[:fields]] if options[:fields]
+        data[:_fields].flatten!
+
+        # Initialize the object with the loaded flag off and with the
+        # ID, so that the object is lazy loaded on first use.
+        new(data)
+      end
+      alias :[] :find
+
+      # Checks if the given object exists within the Facebook
+      # Graph. This method will return `true` or `false` depending on
+      # if the object exists. Calling {exist?} is more efficient than
+      # calling {#exist?} if you only care about the existence of an
+      # object, since {exist?} does not load all the properties
+      # associated with an object, which lowers bandwidth and network
+      # time.
+      #
+      # @param [String] id ID of the object
+      # @return [Boolean]
+      def exist?(id)
+        get("/#{id}", :fields => "id")
+        true
+      rescue Fogli::Exception
+        false
+      end
+
+      # Propagates the properties and connections to any subclasses
+      # which inherit from FacebookObject. This method is called
+      # automatically by Ruby.
+      def inherited(subclass)
+        super
+
+        propagate_properties(subclass)
+        propagate_connections(subclass)
+      end
+    end
+
+    # Initialize a facebook object. If given some data, it will
+    # attempt to populate the various properties with the given data.
+    #
+    # @param [Hash] data The data for this object.
+    def initialize(data=nil)
+      data ||= {}
+
+      # Pull out any "special" values which may be in the data hash
+      @_loaded = !!data.delete(:_loaded)
+      @_fields = data.delete(:_fields) || []
+      @_fields.collect! { |f| f.to_sym }
+
+      populate_properties(data) if !data.empty?
+    end
+
+    # Returns a boolean noting if the object's data has been loaded
+    # yet. {FacebookObject}s are loaded on demand when the first
+    # attribute is accessed.
+    #
+    # @return [Boolean]
+    def loaded?
+      !!@_loaded
+    end
+
+    # Loads the data from Facebook. This is typically called once on
+    # first access of a property.
+    def load!
+      Fogli.logger.info("Fogli Load: #{self.class}[#{id}] (object_id: #{__id__})") if Fogli.logger
+
+      params = {}
+      params[:fields] = _fields.join(",") if !_fields.empty?
+
+      @_raw = get(params)
+      populate_properties(@_raw)
+      @_loaded = true
+      self
+    end
+
+    # Checks if the given object exists. Since these objects are lazy
+    # loaded, a direct {find} call doesn't check the existence of an
+    # object. By calling this method, it forces the data to load and
+    # also returns `true` or `false` depending on if the object exists
+    # or not.
+    #
+    # If you only care about the existence of an object and not it's
+    # data, use {exist?} instead, which is more efficient.
+    #
+    # @return [Boolean]
+    def exist?
+      load!
+      true
+    rescue Fogli::Exception
+      false
+    end
+
+    # Override the read property method to call {#load!} if this
+    # object hasn't been loaded yet.
+    alias_method :read_property_original, :read_property
+    def read_property(name)
+      if name.to_sym != :id
+        if !loaded?
+          load!
+        elsif Fogli.logger
+          # Cache hit, log it if enabled
+          Fogli.logger.info("Fogli Cache: #{self.class}[#{id}].#{name} (object_id: #{__id__})")
+        end
+      end
+
+      read_property_original(name)
+    end
+
+    # Delete an object. This always requires an access token. If you
+    # do not yet have an access token, you must get one via {OAuth}.
+    def delete
+      # Although Facebook supposedly supports DELETE requests, we use
+      # their POST method since the rest client seems to have problems
+      # with DELETE requests.
+      post(:method => :delete)
+    end
+
+    # Override request methods to prepend object ID. When making a
+    # request on an instance of a facebook object, its typically
+    # to access a connection. To avoid repetition, we always prepend
+    # the root object's ID.
+    [:get, :post].each do |method|
+      define_method(method) do |*args|
+        url = "/#{id}"
+        url += args.shift.to_s if !args[0].is_a?(Hash)
+        super(url, *args)
+      end
+    end
+
+    # Customize the inspect method to pretty print Facebook objects
+    # and their associated properties and connections.
+    def inspect
+      values = []
+      self.class.properties.each do |name, options|
+        value = read_property(name)
+        values << "#{name.inspect}=#{value.inspect}"
+      end
+
+      self.class.connections.each do |name, options|
+        values.push("#{name.inspect}=...")
+      end
+
+      "#<#{self.class} #{values.sort.join(", ")}>".strip
+    end
+  end
+end

data/lib/fogli/facebook_object/connection_proxy.rb

@@ -0,0 +1,80 @@
+module Fogli
+  class FacebookObject < FacebookGraph
+    # The proxy object which sits between a facebook object and one of
+    # it's connections. This connection proxy only represents
+    # connections which are a "has many" type, which happens to be
+    # every connection represented by the Facebook Graph except for
+    # "picture" which is handled as a special case.
+    class ConnectionProxy
+      include ScopeMethods
+
+      attr_reader :parent
+      attr_reader :connection_name
+      attr_reader :connection_options
+
+      # Initializes a connection proxy. The actual data associated
+      # with the proxy is not actually loaded until {#load!} is called.
+      #
+      # @param [FacebookObject] parent The parent object of the
+      #   connection
+      # @param [Symbol] connection_name The name of the connection,
+      #   such as 'friends'
+      # @param [Hash] connection_options The options associated with
+      #   the connection.
+      def initialize(parent, connection_name, connection_options)
+        @parent = parent
+        @connection_name = connection_name
+        @connection_options = connection_options
+      end
+
+      # Returns a scope for all of the data which is part of this
+      # connection.
+      #
+      # @return [ConnectionScope]
+      def all
+        # TODO: Cache this value so that the subsequent loads are also
+        # cached.
+        ConnectionScope.new(self)
+      end
+
+      # Loads the data represented by this proxy given the scope. The
+      # proxy itself doesn't cache any data. All the caching is done
+      # on the scope itself.
+      #
+      # **Note:** This method should never be called
+      # manually. Instead, using the various scope methods, and this
+      # method will be called automatically.
+      #
+      # @param [ConnectionScope] scope
+      # @return [Hash]
+      def load(scope)
+        data = parent.get("/#{connection_name}", scope.options)
+        parse_data(data)
+      end
+
+      # Parses the resulting data from a API request for a
+      # connection and returns the hash associated with it. This
+      # method replaces all the data hashes with actual
+      # {FacebookObject} objects.
+      #
+      # @param [Hash] data The data returned from the API call.
+      # @return [Hash]
+      def parse_data(data)
+        data ||= {}
+        data["data"] ||= []
+        data["data"] = data["data"].collect do |raw_item|
+          connection_class.new(raw_item)
+        end
+
+        data
+      end
+
+      # Returns the class associated with this connection.
+      #
+      # @return [Class]
+      def connection_class
+        Fogli.const_get(connection_options[:class])
+      end
+    end
+  end
+end

data/lib/fogli/facebook_object/connection_scope.rb

@@ -0,0 +1,123 @@
+module Fogli
+  class FacebookObject < FacebookGraph
+    # Represents a connection scope, which is just a scoped view of
+    # data. Since Facebook connections often represent massive amounts
+    # of data (e.g. a Facebook feed for a user often has thousands of
+    # entries), it is unfeasible for Facebook to send all this data in
+    # one request, or for a typical developer to want access to _all_
+    # of this data. Facebook solves this problem by paginating the
+    # data over several API calls. {ConnectionScope} allows developers
+    # to scope the requests using various methods such as {#since},
+    # {#until}, {#limit}, and {#offset}, hiding the need for
+    # pagination from the developer.
+    #
+    # Scopes are defined by chaining methods together. An actual
+    # request to Facebook is only made when the data load is
+    # requested:
+    #
+    # 1. {#all}
+    # 2. {#each}
+    #
+    # # Scoping a Connection
+    #
+    #     items = User["mitchellh"].feed.since("yesterday").limit(5).all
+    #     items.each do |item|
+    #        ...
+    #     end
+    #
+    class ConnectionScope
+      include ScopeMethods
+      include Enumerable
+
+      attr_reader :proxy
+      attr_reader :options
+      attr_reader :_data
+
+      # Initializes a connection scope. The actual data associated
+      # with the proxy is not actually loaded until it is accessed.
+      #
+      # @param [ConnectionProxy] proxy The {ConnectionProxy} which
+      #   this scope belongs to.
+      # @param [Hash] options The options built up to this point.
+      def initialize(proxy, options=nil)
+        @proxy = proxy
+        @options = options || {}
+        @_data = nil
+      end
+
+      # Evaluates the current scope and yields to the given block for
+      # each item. This method automatically handles facebook's
+      # pagination, so the developer need not worry about it.
+      def each(&block)
+        load! if !_data
+
+        i = 0
+        count = 0
+        while true
+          # Sanity check to avoid nil accesses, although this should
+          # never happen
+          break if !_data || !_data[i]
+
+          Fogli.logger.info("Fogli Cache: #{log_string(i)}") if Fogli.logger
+
+          _data[i]["data"].each do |item|
+            count += 1
+            yield item
+
+            # Facebook's "limit" is a limit per page, not a total
+            # limit, which is what is expected, so we have to keep
+            # track of that manually
+            return if options[:limit] && count >= options[:limit].to_i
+          end
+
+          i += 1
+
+          if i >= _data.length
+            # Load the next page, but exit the loop if we're on the
+            # last page.
+            break if !load!
+          end
+        end
+      end
+
+      # Loads the next batch of data associated with this scope and
+      # adds it to the data array.
+      def load!
+        result = if _data.nil?
+          # We haven't loaded any of the data yet so start with the
+          # first page.
+
+          # Default the fields to be all fields of the parent
+          @options[:fields] ||= proxy.connection_class.properties.keys.join(",")
+
+          @_data = [proxy.load(self)]
+          true
+        else
+          # We want to load the next page of the data, and append it
+          # to the data array.
+          next_page = _data.last["paging"]["next"] rescue nil
+          _data << proxy.parse_data(FacebookGraph.raw_get(next_page)) if next_page
+          !next_page.nil?
+        end
+
+        Fogli.logger.info("Load: #{log_string(_data.length)}") if Fogli.logger && result
+        result
+      end
+
+      # Clears the data cache associated with this scope. This will
+      # force a reload of the data on the next call and will remove
+      # all references to any data items.
+      def clear_cache
+        @_data = nil
+      end
+
+      # Returns the common log string for a scope. This is used
+      # internally for the logger output, if enabled.
+      #
+      # @return [String]
+      def log_string(page)
+        "#{proxy.parent.class}/#{proxy.connection_name} (page #{page}) (object_id: #{__id__})"
+      end
+    end
+  end
+end

data/lib/fogli/facebook_object/connections.rb

@@ -0,0 +1,56 @@
+module Fogli
+  class FacebookObject < FacebookGraph
+    # Represents connections on a Facebook Object. Connections are
+    # relationships between data.
+    module Connections
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Defines a connection on the object.
+        def connection(*names)
+          options = names.last
+          options = {} if !options.kind_of?(Hash)
+
+          raise ArgumentError.new("`:class` is required for a connection.") if !options[:class]
+
+          names.each do |name|
+            next if name.kind_of?(Hash)
+            name = name.to_s.downcase.to_sym
+            connections[name] = options
+
+            # Create a method for reading the property.
+            define_method(name) { read_connection(name) }
+          end
+        end
+
+        # Returns the connections associated with this facebook
+        # object.
+        #
+        # @return [Hash]
+        def connections
+          @_connections ||= {}
+        end
+
+        # Propagates connections to another class. This is used
+        # internally for making sure that subclasses get all the
+        # connections associated with the parent classes.
+        def propagate_connections(klass)
+          connections.each { |n, o| klass.connection(n, o) }
+        end
+      end
+
+      def read_connection(name)
+        connection_values[name]
+      end
+
+      def connection_values
+        @_connection_values ||= Hash.new do |h,k|
+          options = self.class.connections[k]
+          h[k] = ConnectionProxy.new(self, k, options)
+        end
+      end
+    end
+  end
+end