freebase 0.0.1

data/README

@@ -0,0 +1,25 @@
+= Freebase
+This Ruby-on-Rails plugin provides access to the Freebase API (http://www.freebase.com). Freebase is a collaborative, semantic database similar to Wikipedia only for structured data. Freebase.com provides a JSON-over-HTTP API that this library uses.
+
+Currently only reads are implemented. Contributions, API Suggestions, bug reports are welcome!
+
+This code is ALPHA. The API will change, features will be added. It probably has a bug or two in it. Use it at your own peril.
+
+Author:: Christopher Eppstein (mailto:chris@eppsteins.net)
+Copyright:: Copyright (c) 2007 Christopher Eppstein
+License:: Released under the MIT license
+
+== Installation
+Install the plugin:
+script/plugin install svn://rubyforge.org/var/svn/freebaseapi/trunk/freebase
+
+Then copy freebase.yml to your rails config directory
+
+== Usage Examples
+See the following examples:
+* albums.rb[link:../examples/albums.rb]
+
+== Contributors
+* Pat Allan (mailto:pat@freelancing-gods.com) provided code snippets that
+  exemplified automatic freebase class creation when the class is first referenced.
+

data/lib/core_extensions.rb

@@ -0,0 +1,17 @@
+# Need to modify the inbuilt Module class, to catch const_missing calls.
+class Module
+
+  # New version of const_missing which catches requests made to the
+  # Metaweb module/namespace - and generates modules to represent
+  # data domains if necessary.
+  def const_missing_with_freebase_support(class_id)
+    if self.name[/^Freebase::Types/]
+      new_freebase_type(class_id)
+    else
+      const_missing_without_freebase_support(class_id)
+    end
+  end
+  
+  alias_method_chain :const_missing, :freebase_support
+  
+end

data/lib/freebase.rb

@@ -0,0 +1,160 @@
+# (c) Copyright 2007 Chris Eppstein. All Rights Reserved.
+
+require 'rubygems'
+require 'activesupport'
+require 'net/http'
+require 'core_extensions'
+
+module Freebase
+end
+
+require 'freebase/api'
+
+module Freebase
+  # This module is a namespace scope for the Freebase domains
+  module Types
+    # Automagically creates modules for domains and classes for types
+    # for matching namespaces to Freebase's domain/type naming structure.
+    # Shouldn't need to be called manually because this is called by the module
+    # whenever the constant is missing.
+    def new_freebase_type(name)
+      Freebase::Api::Logger.trace {"new freebase module = #{name}"}
+      self.const_set(name, Module.new do
+        def new_freebase_type(name)
+          Freebase::Api::Logger.trace {"new freebase class = #{name}"}
+          klass = self.const_set(name, Class.new(Freebase::Base))
+          klass.class_eval do
+            cattr_accessor :properties, :schema_loaded
+          end
+          returning(klass) do |tc|
+            tc.load_schema! unless tc.schema_loaded?
+            Freebase::Api::Logger.trace { "Attempting Mixin include: #{tc.name.sub(/Types/,"Mixins")}" }
+            begin
+              tc.send(:include, tc.name.sub(/Types/,"Mixins").constantize)
+            rescue NameError => e
+              Freebase::Api::Logger.trace "failed: #{e}"
+            end
+          end
+        end
+
+        module_function :new_freebase_type
+      end)
+    end
+
+    module_function :new_freebase_type
+  end
+  
+  # Add a module within this module that corresponds to a freebase class within Freebase::Types
+  # and the methods will be mixed in automatically. E.g.:
+  #   module Freebase::Mixins::Music
+  #     module Track
+  #       def formatted_length
+  #         "#{self.length.to_i / 60}:#{sprintf("%02i", self.length.to_i % 60)}"
+  #       end
+  #     end
+  #   end
+  #
+  # Will be mixed in to the Freebase::Types:Music:Track class
+  module Mixins
+  end
+  
+  # This is the base class for all dynamically defined Freebase Types.
+  class Base < Api::FreebaseResult
+    extend Api
+    alias_method :attributes, :result
+    def self.schema_loaded?
+      self.schema_loaded || false
+    end
+    def self.freebase_type
+      @freebase_type ||= self.name["Freebase::Types".length..self.name.length].underscore
+    end
+    def self.load_schema!
+      self.properties = {}
+      propobjs = mqlread(:type => '/type/type', :id => self.freebase_type, :properties => [{:name => nil, :id => nil, :type => nil, :expected_type => nil}]).properties
+      propobjs.each {|propobj|
+        self.properties[propobj.id.split(/\//).last.to_sym] = propobj
+      }
+      self.schema_loaded = true
+    end
+    def self.find(*args)
+      options = args.extract_options!
+      case args.first
+      when :first
+        raise ArgumentError.new("Too many arguments for find(:first)") if args.size > 1
+        find_first(options)
+      when :all
+        raise ArgumentError.new("Too many arguments for find(:all)") if args.size > 1
+        find_all(options)
+      end
+    end
+    def self.add_required_query_attributes(conditions)
+      case conditions
+      when Array
+        conditions.map! {|c| add_required_query_attributes(c)}
+      when Hash
+        if conditions.delete(:fb_object)
+          conditions.reverse_merge!(:type => [], :id => nil) unless conditions.has_key?(:*)
+        else
+          conditions.reverse_merge!(:type => nil) unless conditions.has_key?(:*)
+        end
+        conditions.each {|k,v| add_required_query_attributes(v) unless k == :*}
+      else
+        conditions
+      end
+    end
+    # Don't to call this directly. find(:first, options) will be dispatched here.
+    # This method is provided for extensibility
+    def self.find_first(options = {})
+      conditions = options.fetch(:conditions, {}).reverse_merge(:type => self.freebase_type, :name=>nil, :* => [{}], :limit => 1)
+      add_required_query_attributes(conditions)
+      self.new(mqlread(conditions, :raw => true))
+    end
+    
+    # Don't to call this directly. find(:all, options) will be dispatched here.
+    # This method is provided for extensibility
+    def self.find_all(options = {})
+      query = options.fetch(:conditions, {}).merge(:type => self.freebase_type, :name=>nil, :* => [{}])
+      query[:limit] = options[:limit] if options[:limit]
+      add_required_query_attributes(query)
+      mqlread([query], :raw => true).map{|i| self.new(i)}
+    end
+    
+    # ActiveRecord:Base-like to_s for the class
+    def self.to_s
+      if respond_to?(:properties)  && !self.properties.blank?
+        %Q{#<#{name} #{self.properties.map{|k,v| "#{k}:#{v.expected_type}"}.join(", ")}>}
+      else
+        "#<#{name}>"
+      end
+    end
+    
+    # (re)load all properties of this object
+    def reload
+      query = {:id => self.id, :type=>self.class.freebase_type, :name=> nil, :limit => 1}
+      self.class.properties.each do |k,v|
+        query[k] = [{}] unless query.has_key?(k)
+      end
+      @result = self.class.mqlread(query, :raw => true).symbolize_keys!
+      Freebase::Api::Logger.trace { @result.inspect }
+      return self
+    end
+    
+    # access the properties of this object, lazy loading associations as required.
+    def method_missing(name,*args)
+      if self.class.properties.has_key?(name)
+        reload unless attributes.has_key?(name)
+        resultify attributes[name]
+      elsif self.class.properties.has_key?((singularized_name = name.to_s.singularize.to_sym))
+        reload unless attributes.has_key?(singularized_name)
+        resultify attributes[singularized_name]
+      else
+        super
+      end
+    end
+    
+    # If the object has a name, return it, otherwise the id.
+    def to_s
+      respond_to?(:name) ? name : id
+    end
+  end
+end

data/lib/freebase/api.rb

@@ -0,0 +1,222 @@
+module Freebase::Api
+  # A class for returing errors from the freebase api.
+  # For more infomation see the freebase documentation:
+  # http://www.freebase.com/view/help/guid/9202a8c04000641f800000000544e139#mqlreaderrors
+  class MqlReadError < ArgumentError
+    attr_accessor :code, :freebase_message
+    def initialize(code,message)
+      self.code = code
+      self.freebase_message = message
+    end
+    def message
+      "#{code}: #{freebase_message}"
+    end
+  end
+  
+  # Encapsulates a Freebase result, enables method-based access to the returned values.
+  # E.g.
+  # result = mqlread(:type => "/music/artist", :name => "The Police", :id => nil)
+  # result.id => "/topic/en/the_police"
+  class FreebaseResult
+    
+    attr_accessor :result
+    
+    def initialize(result)
+      @result = result.symbolize_keys!
+    end
+    
+    def id
+      @result[:id]
+    end
+    
+    # result.type is reserved in ruby. Call result.fb_type to access :type instead.
+    def fb_type
+      @result[:type]
+    end
+    
+    # returns the first element of an array if it is one
+    # this for handling generic mql queries like [{}] that return only a single value
+    def depluralize(v)
+      Array(v).first
+    end
+    
+    # converts a returned value from freebase into the corresponding ruby object
+    # This is done first by the core data type and then by the type attribute for an object
+    # The casing is done using a method dispatch pattern which
+    # should make it easy to mix-in new behaviors and type support
+    def resultify(v)
+      resultify_method = "resultify_#{v.class.to_s.downcase}".to_sym
+      v = send(resultify_method, v) if respond_to? resultify_method
+      return v
+    end
+    
+    # resultifies each value in the array
+    def resultify_array(v)
+      v.map{|vv| resultify(vv)}
+    end
+    
+    # resultifies an object hash
+    def resultify_hash(v)
+      vtype = indifferent_access(v,:type)
+      if value_type? vtype
+        resultify_value(vtype,v)
+      elsif vtype.blank?
+        Logger.debug "What's This: #{v.inspect}"
+        FreebaseResult.new(v)
+      elsif vtype.is_a? Array
+        "Freebase::Types#{vtype.first.classify}".constantize.new(v) #TODO: Union these types
+      else
+        "Freebase::Types#{vtype.classify}".constantize.new(v)
+      end
+    end
+    
+    #decides if a type is just an expanded simple value object
+    def value_type?(t)
+      ['/type/text', '/type/datetime'].include?(t)
+    end
+    
+    # dispatches to a value method for the type
+    # or returns the simple value if it doesn't exist
+    # for example /type/text would dispatch to resultify_value_type_text
+    def resultify_value(vtype,v)
+      resultify_method = "resultify_value#{vtype.gsub(/\//,'_')}".to_sym
+      if respond_to? resultify_method
+        send(resultify_method, v) 
+      else
+        indifferent_access(v,:value)
+      end
+    end
+    
+    #provides method based access to the result properties
+    def method_missing(name, *args)
+      raise NoMethodError.new(name.to_s) unless args.length == 0
+      if @result.has_key?(name)
+        resultify @result[name]
+      elsif @result.has_key?((singularized_name = name.to_s.singularize.to_sym)) and @result[singularized_name].is_a?(Array)
+        resultify @result[singularized_name]
+      else
+        raise NoMethodError.new(name.to_s)
+      end
+    end
+    
+    protected
+      def indifferent_access(h,k)
+         h[k] || h[k.to_s] if (h.has_key?(k) || h.has_key?(k.to_s))
+      end
+
+  end
+  
+  # the configuration class controls access to the freebase.yml configuration file.
+  # it will load the rails-environment specific configuration
+  class Configuration
+    
+    include Singleton
+    
+    attr_accessor :filename
+    
+    DEFAULTS = {:host => 'sandbox.freebase.com', :debug => true, :trace => false}
+    
+    def initialize
+      @configuration = {}.reverse_merge!(DEFAULTS)
+      configure_rails if defined?(RAILS_ROOT)
+    end
+    
+    def configure_rails
+      @filename = "#{RAILS_ROOT}/config/freebase.yml"
+      unless File.exists? @filename
+        puts "WARNING: #{RAILS_ROOT}/config/freebase.yml configuration file is not found. Using sandbox.freebase.com." 
+      else
+        set_all YAML.load_file(@filename)[RAILS_ENV].symbolize_keys!
+      end
+    end
+    
+    def set_all(opts = {})
+      opts.each {|k,v| self[k] = v}
+    end
+    
+    def []=(k,v)
+      @configuration[k] = v
+    end
+    
+    def [](k)
+      @configuration[k]
+    end
+  end
+  
+  # logging service. Is it a bad idea?
+  class Logger
+    #TODO: log4r or rails logging?
+    [:trace, :debug, :warn, :error].each do |level|
+      eval %Q{
+        def self.#{level}(message = nil)
+          if Configuration.instance[:#{level}]
+            puts message || yield
+          end
+        end
+      }        
+    end
+  end
+  
+  SERVICES = { :mqlread => '/api/service/mqlread',
+    :mqlwrite => '/api/service/mqlwrite',
+    :login => '/api/account/login',
+    :upload => '/api/service/upload'
+  }
+  
+  # get the service url for the specified service.
+  def service_url(svc)
+    "http://#{Configuration.instance[:host]}#{SERVICES[svc]}"
+  end
+  
+  SERVICES.each_key do |k|
+    define_method("#{k}_service_url") do
+      service_url(k)
+    end
+  end
+  
+  # raise an error if the inner response envelope is encoded as an error
+  def handle_read_error(inner)
+    unless inner['code'].starts_with?('/api/status/ok')
+      Logger.error "<<< Received Error: #{inner.inspect}"
+      error = inner['messages'][0]
+      raise MqlReadError.new(error['code'], error['message'])
+    end
+  end
+  
+
+  
+  # perform a mqlread and return the results
+  # Specify :raw => true if you don't want the results converted into a FreebaseResult object.
+  def mqlread(query, options = {})
+    Logger.trace {">>> Sending Query: #{query.inspect}"}
+    envelope = { :qname => {:query => query }}
+    response = http_request mqlread_service_url, :queries => envelope.to_json
+    result = ActiveSupport::JSON.decode(response)
+    inner = result['qname']
+    handle_read_error(inner)
+    Logger.trace {"<<< Received Response: #{inner['result'].inspect}"}
+    if options[:raw]
+      inner['result']
+    else
+      inner['result'] ? FreebaseResult.new(inner['result']) : nil
+    end
+  end
+  
+  protected
+  def params_to_string(parameters)
+    parameters.keys.map {|k| "#{URI.encode(k.to_s)}=#{URI.encode(parameters[k])}" }.join('&')
+  end
+  def http_request(url, parameters = {})
+    params = params_to_string(parameters)
+    url << '?'+params unless params.blank?
+    returning(Net::HTTP.get_response(URI.parse(url)).body) do |response|
+      Logger.trace do
+        fname = "#{MD5.md5(params)}.mql"
+        open(fname,"w") do |f|
+          f << response
+        end
+        "Wrote response to #{fname}"
+      end
+    end
+  end
+end

data/test/freebase_test.rb

@@ -0,0 +1,36 @@
+require 'test/unit'
+require File.dirname(__FILE__)+'/test_helper'
+
+class FreebaseTest < Test::Unit::TestCase
+  # Replace this with your real tests.
+  def test_load_music_artist
+    Freebase::Types::Music::Artist
+  end
+  def test_find_first_artist
+    assert_kind_of Freebase::Types::Music::Artist,
+                   (artist = Freebase::Types::Music::Artist.find(:first,:conditions => {:name => "The Police"}))
+    assert_equal 20, artist.albums.size
+  end
+  def test_association_preloading
+    artist = Freebase::Types::Music::Artist.find(:first,
+      :conditions => {
+        :name => {:value => ARGV[0], :lang => {:name => "English"}},
+        :album => [{
+          :fb_object => true,
+          :name => {:value => nil, :lang => {:name => "English"}},
+          :release_date => nil,
+          :track => [{
+            :fb_object => true,
+            :length => nil,
+            :name => {:value => nil, :lang => {:name => "English"}}
+          }]
+        }]
+      }
+    )
+    quiesce(:find, :reload) do
+      assert_equal 14, artist.albums.size
+      assert_equal 8, artist.albums.first.tracks.size
+      #artist.albums.first.producer
+    end
+  end
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification 
+name: freebase
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Chris Eppstein
+autorequire: freebase
+bindir: bin
+cert_chain: []
+
+date: 2008-02-03 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.0.2
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.1.2
+    version: 
+description: 
+email: chris@eppsteins.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- lib/core_extensions.rb
+- lib/freebase
+- lib/freebase/api.rb
+- lib/freebase.rb
+- README
+has_rdoc: true
+homepage: http://rubyforge.org/projects/freebaseapi/
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: freebaseapi
+rubygems_version: 0.9.5
+signing_key: 
+specification_version: 2
+summary: Ruby wrapper for the Freebase.com API that makes interacting with freebase.com in your Ruby on Rails application as easy as using Active Record. Freebase is a free, collaborative semantic database.
+test_files: 
+- test/freebase_test.rb