freeb 0.0.1

data/lib/freeb.rb

@@ -0,0 +1,28 @@
+module Freeb
+  def self.config
+    yield Freeb::Config
+  end
+
+  def self.get(freebase_id)
+    API.get(freebase_id)
+  end
+
+  def self.search(params)
+    API.search(params)
+  end
+
+  def self.topic(mql)
+    API.topic(mql)
+  end
+
+  def self.mqlread(mql)
+    API.mqlread(mql)
+  end
+end
+
+directory = File.dirname(File.absolute_path(__FILE__))
+Dir.glob("#{directory}/freeb/*.rb") { |file| require file }
+Dir.glob("#{directory}/generators/freeb/*.rb") { |file| require file }
+Dir.glob("#{directory}/../app/models/*.rb") { |file| require file }
+
+ActiveRecord::Base.extend Freeb::Models::ClassMethods

data/lib/freeb/api.rb

@@ -0,0 +1,91 @@
+require 'httparty'
+require 'uri'
+require 'json'
+
+module Freeb
+  class API
+    @base_url = "https://www.googleapis.com/freebase/v1/"
+    
+    def self.get(id)
+      mql = {
+        "id" => id,
+        "name" => nil
+      }
+      topic(mql)
+    end
+
+    def self.topic(mql)
+      result = mqlread(mql)
+      return nil if result.blank?
+      if result.is_a?(Array)
+        result.collect { |r| Topic.new(r) }
+      else
+        Topic.new(result)
+      end
+    end
+
+    def self.search(params)
+      log "Search Request: #{params}"
+      url = "#{@base_url}search"
+      result = get_result(url, params)
+      log "Search Response: #{result}"
+      result["result"].collect { |r| Topic.new(r) }
+    end
+
+    def self.mqlread(mql)
+      log "MQL Request: #{mql}"
+      url = "#{@base_url}mqlread"
+      result = get_result(url, :query => mql.to_json)
+      log "MQL Response: #{result}"
+      return nil if result["result"].blank?
+      result["result"]
+    end
+
+    def self.description(id)
+      url = "#{@base_url}text#{id}"
+      result = get_result(url, nil)
+      result["result"]
+    end
+
+    def self.get_result(url, params={})
+      unless params.nil?
+        params[:key] = Config.settings[:api_key] unless Config.settings[:api_key].blank?
+        url = "#{url}?#{params.to_query}"
+      end
+      if Config.settings[:cache][:is_active]
+        cache_key = cache_key_for_url(url)
+        result = Rails.cache.read(cache_key)
+        if result
+          log "Read cache for #{url}"
+          result
+        else
+          result = get_uncached_result(url)
+          Rails.cache.write(cache_key, result, :expires_in => Config.settings[:cache][:expires_in])
+          log "Wrote cache for #{url}"
+          result
+        end
+      else
+        get_uncached_result(url)
+      end
+    end
+
+    def self.get_uncached_result(url)
+      response = HTTParty.get(url)
+      if response.code == 200
+        return JSON.parse(response.body)
+      end
+      raise ResponseException, "Freebase Response #{response.code}: #{JSON.parse(response.body).inspect}"
+      nil
+    end
+
+    private
+
+    def self.cache_key_for_url(url)
+      {:gem => "Freeb", :class => "API", :key => "get_result", :url => url}
+    end
+
+    def self.log(message)
+      Rails.logger.debug("Freeb: #{message}")
+    end
+  end
+end

data/lib/freeb/config.rb

@@ -0,0 +1,25 @@
+require 'active_support/core_ext/numeric'
+
+module Freeb
+  class Config
+    class << self
+      attr_reader :settings
+    end
+
+    @settings = {
+      :api_key => nil,
+      :cache => {
+        :is_active => true,
+        :expires_in => 1.day
+      }
+    }
+
+    def self.api_key(api_key)
+      @settings[:api_key] = api_key
+    end
+
+    def self.cache(options)
+      @settings[:cache].merge!(options)
+    end
+  end
+end

data/lib/freeb/converter.rb

@@ -0,0 +1,60 @@
+module Freeb
+  class Converter
+    def self.freebase_id_to_topic(freebase_id, model)
+      config = ModelConfig.get(model)
+      query_properties = ModelConfig.get_query_properties(model)
+      mql = {
+        :id => freebase_id,
+        :type => config[:type],
+        :name => nil
+      }.merge(query_properties)
+      API.topic(mql)
+    end
+
+    def self.name_to_topic(name, model)
+      config = ModelConfig.get(model)
+      query_properties = ModelConfig.get_query_properties(model)
+      mql = {
+        :id => nil,
+        :type => config[:type],
+        :name => name
+      }.merge(query_properties)
+      API.topic(mql)
+    end
+
+    def self.topic_to_record_attributes(topic, model)
+      config = ModelConfig.get(model)
+      attributes = {
+        :freebase_id => topic.id,
+        :name => topic.name
+      }
+      config[:properties].each do |key, property_config|
+        if property_config[:method].blank?
+          attributes[key] = topic[property_config[:id]]
+        else
+          attributes[key] = model.send(property_config[:method], topic)
+        end
+      end
+      config[:topics].each do |key, topic_config|
+        attributes[key] = topic[topic_config[:id]].collect { |hash| topic_hash_to_freebase_topic_record(hash) }
+      end
+      config[:has_many].each do |key, association_config|
+        records = topic[association_config[:id]]
+        model = association_config[:class_name].constantize
+        attributes[key] = records.collect { |hash|
+          topic = Topic.new(hash)
+          hash = topic_to_record_attributes(topic, model)
+          model.ffind_or_create(hash) }
+      end
+      attributes
+    end
+
+    def self.topic_hash_to_freebase_topic_record(topic_hash)
+      hash = {
+        :freebase_id => topic_hash["id"],
+        :name => topic_hash["name"]
+      }
+      record = FreebaseTopic.find_or_create_by_freebase_id(hash)
+    end
+  end
+end

data/lib/freeb/dsl.rb

@@ -0,0 +1,25 @@
+module Freeb
+  class DSL
+    attr_reader :config
+
+    def initialize
+      @config = {}
+    end
+
+    def type(value)
+      @config[:type] = value
+    end
+
+    def properties(*args)
+      @config[:properties] = args
+    end
+
+    def topics(*args)
+      @config[:topics] = args
+    end
+
+    def has_many(*args)
+      @config[:has_many] = args
+    end
+  end
+end

data/lib/freeb/engine.rb

@@ -0,0 +1,5 @@
+module Freeb
+  class Engine < ::Rails::Engine
+    isolate_namespace Freeb
+  end
+end

data/lib/freeb/exceptions.rb

@@ -0,0 +1,3 @@
+module Freeb
+  class ResponseException < Exception; end
+end

data/lib/freeb/model_config.rb

@@ -0,0 +1,172 @@
+module Freeb
+  class ModelConfig
+    @models = {}
+    
+    def self.register(model, options)
+      key = model_to_key(model)
+      @models[key] = normalize_options(options)
+    end
+
+    def self.get(model)
+      key = model_to_key(model)
+      @models[key]
+    end
+
+    def self.get_query_properties(model)
+      config = get(model)
+      query_properties = {}
+      raise "Empty Freeb config for #{model}" if config.blank?
+      query_properties.merge!(config[:properties].inject({}) { |h, (k, property)| h[property[:id]] = nil; h })
+      query_properties.delete("description")
+      query_properties.merge!(config[:topics].inject({}) { |h, (k, topic)| h[topic[:id]] = [{:id => nil, :name => nil}]; h })
+      query_properties.merge!(get_has_many_properties(model))
+      query_properties
+    end
+
+    def self.get_has_many_properties(model)
+      config = get(model)
+      properties = {}
+      config[:has_many].each do |key, association|
+        association_class = association[:class_name].classify.constantize
+        association_class_config = get(association_class)
+        association_properties = {:id => nil, :name => nil}
+        association_properties.merge!(get_query_properties(association_class))
+        key = association[:id]
+        properties[key] = [association_properties]
+      end
+      properties
+    end
+
+    def self.get_migration_properties(model)
+      config = get(model)
+      schema = Freeb.mqlread({
+        :name => nil,
+        :id => config[:type],
+        :type => [{:id => "/type/type"}],
+        "!/type/property/schema" => [{"/type/property/expected_type" => nil, "id" => nil, "name" => nil}]
+      })
+      property_types = {}
+      schema["!/type/property/schema"].each do |property|
+        property_types[property["id"]] = property["/type/property/expected_type"]
+      end
+      config[:properties].collect do |key, property|
+        expected_type = property_types[property[:id]]
+        type = case expected_type
+        when "/type/boolean"
+          :boolean
+        when "/type/datetime"
+          :datetime
+        when "/type/float"
+          :float
+        when "/type/int"
+          :integer
+        when "/type/text"
+          :text
+        else
+          :string
+        end
+        if property[:id] == "description"
+          type = "text"
+        end
+        { :key => key, :type => type }
+      end
+    end
+
+    def self.model_to_key(model)
+      model.name.underscore.to_sym
+    end
+
+    def self.normalize_options(options)
+      normalize_properties(options)
+      normalize_topics(options)
+      normalize_has_many(options)
+      options
+    end
+
+    def self.normalize_properties(options)
+      properties = {}
+      options[:properties].flatten(1).each do |property|
+        if property.is_a?(String)
+          properties[property.to_sym] = {
+            :key => property,
+            :id => key_to_id(property, options)
+          }
+        elsif property.is_a?(Hash)
+          property.each do |key, value|
+            if value.is_a?(String)
+              properties[key.to_sym] = {
+                :key => value,
+                :id => key_to_id(value, options)
+              }
+            elsif value.is_a?(Hash)
+              defaults = {
+                :key => key,
+                :id => key_to_id(key, options)
+              }
+              properties[key.to_sym] = defaults.merge(value)
+            end
+          end
+        end 
+      end
+      options[:properties] = properties
+    end
+
+    def self.normalize_topics(options)
+      topics = {}
+      options[:topics] = [options[:topics]] if !options[:topics].is_a?(Array)
+      options[:topics].each do |topic|
+        if topic.is_a?(String) || topic.is_a?(Symbol)
+          topic = topic.to_s
+          topics[topic.to_sym] = {
+            :key => topic,
+            :id => key_to_id(topic, options)
+          }
+        elsif topic.is_a?(Hash)
+          topic.each do |key, value|
+            topics[key.to_sym] = {
+              :key => key,
+              :id => key_to_id(value, options)
+            }
+          end
+        end
+      end
+      options[:topics] = topics 
+    end
+
+    def self.normalize_has_many(options)
+      associations = {}
+      options[:has_many] = [options[:has_many]] if !options[:has_many].is_a?(Array)
+      options[:has_many].each do |association|
+        if association.is_a?(String) || association.is_a?(Symbol)
+          association = association.to_s
+          associations[association.to_sym] = {
+            :key => association.to_sym,
+            :id => key_to_id(value, options),
+            :class_name => association.singularize.camelize
+          }
+        elsif association.is_a?(Hash)
+          association.each do |key, value|
+            key = key.to_s
+            associations[key.to_sym] = {
+              :key => key,
+              :id => key_to_id(value, options),
+              :class_name => key.singularize.camelize
+            }
+          end
+        end
+      end
+      options[:has_many] = associations 
+    end
+
+    def self.key_to_id(key, options)
+      key = key.to_s
+      if key == "description"
+        key
+      elsif key[0,1] == "/"
+        key
+      else
+        "#{options[:type]}/#{key}"
+      end
+    end
+  end
+end

data/lib/freeb/models.rb

@@ -0,0 +1,175 @@
+module Freeb
+  module Models
+    module ClassMethods
+      def freeb(&block)
+        include InstanceMethods
+        dsl = DSL.new
+        dsl.instance_eval(&block)
+        options = ModelConfig.register(self, dsl.config)
+
+        accessible_attributes = [:freebase_id, :name]
+        accessible_attributes += (options[:properties].merge(options[:topics]).merge(options[:has_many])).keys
+
+        attr_reader :freeb_config
+        attr_accessible *accessible_attributes
+        validates_presence_of :freebase_id, :name
+        
+        initialize_topic_associations(options)
+        initialize_has_many_associations(options)
+        
+        @freeb_config = ModelConfig.get(self)
+      end
+
+      def initialize_topic_associations(options)
+        return if options[:topics].blank?
+        options[:topics].each do |key, value|
+          join_association = :"#{key}_freebase_topic_relations"
+          has_many join_association, :as => :subject, :class_name => "FreebaseTopicRelation",
+            :conditions => {:property => value[:id]}, :before_add => :"before_add_#{join_association}"
+          define_method :"before_add_#{join_association}" do |record|
+            record.property = value[:id]
+          end
+          has_many key, :through => join_association, :source => :freebase_topic
+          join_association = :"freebase_topic_relations_#{key}"
+          FreebaseTopic.has_many join_association, :class_name => "FreebaseTopicRelation",
+            :conditions => {:property => value[:id]}
+          FreebaseTopic.has_many self.name.tableize, :through => join_association,
+            :source => :subject, :source_type => self.name
+        end
+      end
+
+      def initialize_has_many_associations(options)
+        return if options[:has_many].blank?
+        options[:has_many].each do |key, association|
+          # Two-sided polymorphic has_many relationships are supported by Rails, so we'll do this with a HABTM and
+          # custom insert SQL. Is there a better approach?
+          join_table = "freebase_model_relations"
+          has_and_belongs_to_many key, :join_table => join_table,
+            :foreign_key => "subject_id", :association_foreign_key => "object_id",
+            :conditions => {
+              "#{join_table}.subject_type" => self.name,
+              "#{join_table}.object_type" => association[:class_name],
+              "#{join_table}.property" => association[:id]
+            },
+            :insert_sql => proc { |object|
+              %{INSERT INTO `#{join_table}`
+                  (`subject_type`, `subject_id`, `property`, `object_type`, `object_id`)
+                VALUES
+                  ("#{self.class.name}", "#{id}", "#{association[:id]}", "#{association[:class_name]}", "#{object.id}" )}
+            }
+        end
+      end
+
+      def fnew(freebase_id)
+        return nil if freebase_id.nil?
+        return fnew_with_array(freebase_id) if freebase_id.is_a?(Array)
+        topic = Converter.freebase_id_to_topic(freebase_id, self)
+        new(Converter.topic_to_record_attributes(topic, self))
+      end
+
+      def fnew_by_name(name)
+        return nil if name.nil?
+        return names.collect { |name| fnew_by_name(name) } if name.is_a?(Array)
+        topic = Converter.name_to_topic(name, self)
+        new(Converter.topic_to_record_attributes(topic, self))
+      end
+
+      def fcreate(freebase_id)
+        return nil if freebase_id.nil?
+        return fcreate_with_array(freebase_id) if freebase_id.is_a?(Array)
+        existing = find_by_freebase_id(freebase_id)
+        return existing unless existing.blank?
+        begin
+          topic = Converter.freebase_id_to_topic(freebase_id, self)
+        rescue ResponseException
+          return nil
+        end
+        return nil if topic.blank?
+        create(Converter.topic_to_record_attributes(topic, self))
+      end
+
+      def fcreate_by_name(name)
+        return nil if name.nil?
+        if name.is_a?(Array)
+          names = name
+          return names.collect { |name| fcreate_by_name(name) }
+        end
+        existing = find_by_name(name)
+        return existing unless existing.blank?
+        begin
+          topic = Converter.name_to_topic(name, self)
+        rescue ResponseException
+          return nil
+        end
+        return nil if topic.blank?
+        create(Converter.topic_to_record_attributes(topic, self))
+      end
+
+      def fcreate_all
+        return fcreate([{}])
+      end
+
+      def ffind_or_create(hash)
+        find_or_create_by_freebase_id(hash)
+      end
+
+      protected
+
+      def fnew_with_array(array)
+        if array.first.is_a?(String)
+          freebase_ids = array
+          freebase_ids.collect { |freebase_id| fnew(freebase_id) }
+        elsif array.first.is_a?(Hash)
+          fnew_with_mql(array)
+        end
+      end
+
+      def fcreate_with_array(array)
+        if array.first.is_a?(String)
+          freebase_ids = array
+          freebase_ids.collect { |freebase_id| fcreate(freebase_id) }
+        elsif array.first.is_a?(Hash)
+          fcreate_with_mql(array)
+        end
+      end
+
+      def fnew_with_mql(mql)
+        results = mql_to_results(mql)
+        results.collect do |hash|
+          topic = Topic.new(hash)
+          new(Converter.topic_to_record_attributes(topic, self))
+        end
+      end
+
+      def fcreate_with_mql(mql)
+        results = mql_to_results(mql)
+        results.collect do |hash|
+          topic = Topic.new(hash)
+          ffind_or_create(Converter.topic_to_record_attributes(topic, self))
+        end
+      end
+
+      def mql_to_results(mql)
+        mql[0] = mql[0].inject({}){|hash, (k,v)| hash[k.to_s] = v; hash}
+        mql[0]["id"] = nil if mql[0]["id"].blank?
+        mql[0]["name"] = nil if mql[0]["name"].blank?
+        mql[0]["type"] = @freeb_config[:type] if mql[0]["type"].blank?
+        API.mqlread(mql)
+      end
+    end
+
+    module InstanceMethods
+      def fupdate
+        topic = Converter.freebase_id_to_topic(freebase_id, self)
+        attributes = Converter.topic_to_record_attributes(topic, self)
+        update_attributes(attributes)
+      end
+
+      def fimage(options={})
+        url = "https://usercontent.googleapis.com/freebase/v1/image#{freebase_id}"
+        url << "?#{options.to_query}" unless options.blank?
+        url
+      end
+    end
+  end
+end