ken 0.1.2

data/VERSION

@@ -0,0 +1 @@
+0.1.2

data/examples/artist.rb

@@ -0,0 +1,21 @@
+require 'pathname'
+require 'rubygems'
+
+EXAMPLES_ROOT = Pathname(__FILE__).dirname.expand_path
+require EXAMPLES_ROOT.parent + 'lib/ken'
+
+Ken::Logger.new(STDOUT, :info)
+Ken::Session.new('http://www.freebase.com', 'ma', 'xxxxx')
+
+resource = Ken.get('/en/the_police')
+
+resource.views.each do |view|
+  puts view
+  puts "="*20
+  view.attributes.each do |a|
+    puts a.property
+    puts "-"*20
+    puts a
+    puts # newline
+  end
+end

data/examples/artist_links.rb

@@ -0,0 +1,38 @@
+require 'pathname'
+require 'rubygems'
+
+# displays all links related to music/artists
+# low level api through Ken.session.mqlread is used here
+
+EXAMPLES_ROOT = Pathname(__FILE__).dirname.expand_path
+require EXAMPLES_ROOT.parent + 'lib/ken'
+
+Ken::Session.new('http://www.freebase.com', 'ma', '*****')
+
+puts "collecting artist links... this might take a while..."
+
+artist_links = []
+
+# execute query
+artists = Ken.session.mqlread([{
+  :type => "/music/artist",
+  :id => nil, 
+  :"/common/topic/webpage" => [{:uri => nil}], 
+  :home_page => [{:uri => nil}]
+}], :cursor => true)
+
+# collect artist links
+artists.each do |artist|
+  artist["/common/topic/webpage"].each do |webpage|
+    artist_links << webpage["uri"] unless artist_links.include?(webpage["uri"])
+  end
+  
+  artist["home_page"].each do |homepage|
+    artist_links << homepage["uri"] unless artist_links.include?(homepage["uri"])
+  end
+end
+
+# print artist links
+artist_links.each do |link|
+  puts link
+end

data/ken.gemspec

@@ -0,0 +1,91 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{ken}
+  s.version = "0.1.2"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["michael"]
+  s.date = %q{2009-10-16}
+  s.email = %q{ma[at]zive[dot]at}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.textile",
+     "README.txt"
+  ]
+  s.files = [
+    ".gitignore",
+     "History.txt",
+     "LICENSE",
+     "README.textile",
+     "README.txt",
+     "Rakefile",
+     "TODO",
+     "VERSION",
+     "examples/artist.rb",
+     "examples/artist_links.rb",
+     "ken.gemspec",
+     "lib/ken.rb",
+     "lib/ken/attribute.rb",
+     "lib/ken/collection.rb",
+     "lib/ken/logger.rb",
+     "lib/ken/property.rb",
+     "lib/ken/resource.rb",
+     "lib/ken/session.rb",
+     "lib/ken/type.rb",
+     "lib/ken/util.rb",
+     "lib/ken/view.rb",
+     "rails/init.rb",
+     "tasks/ken.rb",
+     "tasks/spec.rb",
+     "test/fixtures/music_artist.json",
+     "test/fixtures/the_police.json",
+     "test/integration/ken_test.rb",
+     "test/test_helper.rb",
+     "test/unit/attribute_test.rb",
+     "test/unit/property_test.rb",
+     "test/unit/resource_test.rb",
+     "test/unit/session_test.rb",
+     "test/unit/type_test.rb",
+     "test/unit/view_test.rb"
+  ]
+  s.homepage = %q{http://github.com/michael/ken}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Ruby API for Accessing the Freebase}
+  s.test_files = [
+    "test/integration/ken_test.rb",
+     "test/test_helper.rb",
+     "test/unit/attribute_test.rb",
+     "test/unit/property_test.rb",
+     "test/unit/resource_test.rb",
+     "test/unit/session_test.rb",
+     "test/unit/type_test.rb",
+     "test/unit/view_test.rb",
+     "examples/artist.rb",
+     "examples/artist_links.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<extlib>, [">= 0"])
+      s.add_runtime_dependency(%q<json>, [">= 0"])
+      s.add_runtime_dependency(%q<addressable>, [">= 0"])
+    else
+      s.add_dependency(%q<extlib>, [">= 0"])
+      s.add_dependency(%q<json>, [">= 0"])
+      s.add_dependency(%q<addressable>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<extlib>, [">= 0"])
+    s.add_dependency(%q<json>, [">= 0"])
+    s.add_dependency(%q<addressable>, [">= 0"])
+  end
+end

data/lib/ken.rb

@@ -0,0 +1,126 @@
+require 'pathname'
+require 'rubygems'
+require 'net/http'
+require 'json'
+require 'extlib/assertions'
+require 'addressable/uri'
+
+dir = Pathname(__FILE__).dirname.expand_path + 'ken'
+
+require dir + 'util'
+require dir + 'resource'
+require dir + 'type'
+require dir + 'view'
+require dir + 'property'
+require dir + 'attribute'
+require dir + 'collection'
+require dir + 'session'
+require dir + 'logger'
+
+# init logger as soon as the library is required
+Ken::Logger.new(STDOUT, :error)
+
+# init default session
+Ken::Session.new('http://www.freebase.com', 'ma', 'xxxxx')
+
+module Ken
+  extend Extlib::Assertions
+  
+  # store query as a constant here.
+  # if the hash gets updated using
+  # #merge! or #update, this will mean
+  # that it actually stores the last
+  # query used. there are 2 sides to this.
+  # on the one hand, it isn't really a 
+  # constant anymore (ruby doesn't complain)?
+  # on the other hand, there is no need to
+  # create a new object everytime a query is
+  # executed. maybe this is fine, maybe not,
+  # this needs to be discussed.
+  
+  FETCH_DATA_QUERY = {
+    # :id => id, # needs to be merge!d in instance method
+    :guid => nil,
+    :name => nil,
+    :"ken:type" => [{
+      :id => nil,
+      :name => nil,
+      :properties => [{
+        :id => nil,
+        :name => nil,
+        :expected_type => nil,
+        :unique => nil,
+        :reverse_property => nil,
+        :master_property => nil,
+      }]
+    }],
+    :"/type/reflect/any_master" => [
+      {
+        :id => nil,
+        :link => nil,
+        :name => nil,
+        :optional => true,
+        :limit => 999999
+      }
+    ],
+    :"/type/reflect/any_reverse" => [
+      {
+        :id => nil,
+        :link => nil,
+        :name => nil,
+        :optional => true,
+        :limit => 999999
+      }
+    ],
+    :"/type/reflect/any_value" => [
+      {
+        :link => nil,
+        :value => nil,
+        :optional => true,
+        :limit => 999999
+        # TODO: support multiple language
+        # :lang => "/lang/en",
+        # :type => "/type/text"
+      }
+    ]
+  }
+  
+  # Executes an Mql Query against the Freebase API and returns the result as
+  # a <tt>Collection</tt> of <tt>Resources</tt>.
+  #
+  # performs a cursored query unless there's a limit specified
+  # == Examples
+  #
+  # Ken.all(:name => "Apple", :type => "/music/album")
+  #
+  # Ken.all(
+  #  :directed_by => "George Lucas",
+  #  :starring => [{
+  #    :actor => "Harrison Ford"
+  #  }],
+  #  :type => "/film/film"
+  # )
+  # @api public
+  def self.all(options = {})
+    assert_kind_of 'options', options, Hash
+    query = { :name => nil }.merge!(options).merge!(:id => nil)
+    result = Ken.session.mqlread([ query ], :cursor => !options[:limit])    
+    Ken::Collection.new(result.map { |r| Ken::Resource.new(r) })
+  end
+  
+  
+  # Executes an Mql Query against the Freebase API and returns the result wrapped
+  # in a <tt>Resource</tt> Object.
+  #
+  # == Examples
+  #
+  #  Ken.get('/en/the_police') => #<Resource id="/en/the_police" name="The Police">
+  # @api public
+  def self.get(id)
+    assert_kind_of 'id', id, String
+    result = Ken.session.mqlread(FETCH_DATA_QUERY.merge!(:id => id))
+    raise ResourceNotFound unless result
+    Ken::Resource.new(result)
+  end
+  
+end # module Ken

data/lib/ken/attribute.rb

@@ -0,0 +1,62 @@
+module Ken
+  class Attribute
+    
+    include Extlib::Assertions
+    attr_reader :property
+    
+    # initializes a resource by json result
+    def initialize(data, property)
+      assert_kind_of 'data', data, Array
+      assert_kind_of 'property', property, Ken::Property
+      @data, @property = data, property
+    end
+    
+    # factory method for creating an attribute instance
+    # @api semipublic
+    def self.create(data, property)
+      Ken::Attribute.new(data, property)
+    end
+    
+    # @api public
+    def to_s
+      subject.to_s
+    end
+    
+    # @api public
+    def inspect
+      result = "#<Attribute property=\"#{property.id || "nil"}\">"
+    end
+    
+    # returns a collection of values
+    # in case of a unique property the array holds just one value
+    # @api public
+    def values
+      subject
+    end
+    
+    # unique properties can have at least one value
+    # @api public
+    def unique?
+      @property.unique?
+    end
+    
+    # object type properties always link to resources
+    # @api public
+    def object_type?
+      @property.object_type?
+    end
+    
+    # returns true if the property is a value type
+    # value type properties refer to simple values like /type/text
+    # @api public
+    def value_type?
+      @property.value_type?
+    end
+    
+    private
+    # initializes the subject if used for the first time
+    def subject
+      @subject ||= Ken::Collection.new(@data.map { |r| object_type? ? Ken::Resource.new(r) : r["value"] })
+    end
+  end
+end

data/lib/ken/collection.rb

@@ -0,0 +1,8 @@
+module Ken
+  class Collection < Array
+    # add a linebreak after each entry
+    def to_s
+      self.inject("") { |m,i| "#{m}#{i.to_s}\n"}
+    end
+  end
+end

data/lib/ken/logger.rb

@@ -0,0 +1,233 @@
+require "time"
+
+# ==== Public Ken Logger API
+#
+# Logger taken from Merb/Datamapper :)
+#
+# To replace an existing logger with a new one:
+#   Ken.logger.set_log(log{String, IO},level{Symbol, String})
+#
+# Available logging levels are:
+#   :off, :fatal, :error, :warn, :info, :debug
+#
+# Logging via:
+#   Ken.logger.fatal(message<String>)
+#   Ken.logger.error(message<String>)
+#   Ken.logger.warn(message<String>)
+#   Ken.logger.info(message<String>)
+#   Ken.logger.debug(message<String>)
+#
+# Flush the buffer to
+#   Ken.logger.flush
+#
+# Remove the current log object
+#   Ken.logger.close
+#
+# ==== Private Ken Logger API
+#
+# To initialize the logger you create a new object, proxies to set_log.
+#   ken::Logger.new(log{String, IO}, level{Symbol, String})
+#
+# Logger will not create the file until something is actually logged
+# This avoids file creation on Ken init when it creates the
+# default logger.
+module Ken
+  
+  class << self #:nodoc:
+    attr_accessor :logger
+  end
+
+  class Logger
+    attr_accessor :aio
+    attr_accessor :delimiter
+    attr_reader   :level
+    attr_reader   :buffer
+    attr_reader   :log
+
+    # @note
+    #   Ruby (standard) logger levels:
+    #     off:   absolutely nothing
+    #     fatal: an unhandleable error that results in a program crash
+    #     error: a handleable error condition
+    #     warn:  a warning
+    #     info:  generic (useful) information about system operation
+    #     debug: low-level information for developers
+    #
+    #   Ken::Logger::LEVELS[:off, :fatal, :error, :warn, :info, :debug]
+    
+    LEVELS =
+    {
+      :off   => 99999,
+      :fatal => 7,
+      :error => 6,
+      :warn  => 4,
+      :info  => 3,
+      :debug => 0
+    }
+
+    def level=(new_level)
+      @level = LEVELS[new_level.to_sym]
+      reset_methods(:close)
+    end
+
+    private
+
+    # The idea here is that instead of performing an 'if' conditional check on
+    # each logging we do it once when the log object is setup
+    def set_write_method
+      @log.instance_eval do
+
+        # Determine if asynchronous IO can be used
+        def aio?
+          @aio = !RUBY_PLATFORM.match(/java|mswin/) &&
+          !(@log == STDOUT) &&
+          @log.respond_to?(:write_nonblock)
+        end
+
+        # Define the write method based on if aio an be used
+        undef write_method if defined? write_method
+        if aio?
+          alias :write_method :write_nonblock
+        else
+          alias :write_method :write
+        end
+      end
+    end
+
+    def initialize_log(log)
+      close if @log # be sure that we don't leave open files laying around.
+      @log = log || "log/dm.log"
+    end
+
+    def reset_methods(o_or_c)
+      if o_or_c == :open
+        alias internal_push push_opened
+      elsif o_or_c == :close
+        alias internal_push push_closed
+      end
+    end
+
+    def push_opened(string)
+      message = Time.now.httpdate
+      message << delimiter
+      message << string
+      message << "\n" unless message[-1] == ?\n
+      @buffer << message
+      flush # Force a flush for now until we figure out where we want to use the buffering.
+    end
+
+    def push_closed(string)
+      unless @log.respond_to?(:write)
+        log = Pathname(@log)
+        log.dirname.mkpath
+        @log = log.open('a')
+        @log.sync = true
+      end
+      set_write_method
+      reset_methods(:open)
+      push(string)
+    end
+
+    alias internal_push push_closed
+
+    def prep_msg(message, level)
+      level << delimiter << message
+    end
+
+    public
+
+    # To initialize the logger you create a new object, proxies to set_log.
+    #   Ken::Logger.new(log{String, IO},level{Symbol, String})
+    #
+    # @param log<IO,String>        either an IO object or a name of a logfile.
+    # @param log_level<String>     the message string to be logged
+    # @param delimiter<String>     delimiter to use between message sections
+    # @param log_creation<Boolean> log that the file is being created
+    def initialize(*args)
+      set_log(*args)
+    end
+
+    # To replace an existing logger with a new one:
+    #   Ken.logger.set_log(log{String, IO},level{Symbol, String})
+    #
+    # @param log<IO,String>        either an IO object or a name of a logfile.
+    # @param log_level<Symbol>     a symbol representing the log level from
+    #   {:off, :fatal, :error, :warn, :info, :debug}
+    # @param delimiter<String>     delimiter to use between message sections
+    # @param log_creation<Boolean> log that the file is being created
+    def set_log(log, log_level = :off, delimiter = " ~ ", log_creation = false)
+      delimiter    ||= " ~ "
+
+      if log_level && LEVELS[log_level.to_sym]
+        self.level = log_level.to_sym
+      else
+        self.level = :debug
+      end
+
+      @buffer    = []
+      @delimiter = delimiter
+
+      initialize_log(log)
+      
+      Ken.logger = self
+
+      self.info("Logfile created") if log_creation
+    end
+
+    # Flush the entire buffer to the log object.
+    #   Ken.logger.flush
+    #
+    def flush
+      return unless @buffer.size > 0
+      @log.write_method(@buffer.slice!(0..-1).join)
+    end
+
+    # Close and remove the current log object.
+    #   Ken.logger.close
+    #
+    def close
+      flush
+      @log.close if @log.respond_to?(:close)
+      @log = nil
+    end
+
+    # Appends a string and log level to logger's buffer.
+
+    # @note
+    #   Note that the string is discarded if the string's log level less than the
+    #   logger's log level.
+    # @note
+    #   Note that if the logger is aio capable then the logger will use
+    #   non-blocking asynchronous writes.
+    #
+    # @param level<Fixnum>  the logging level as an integer
+    # @param string<String> the message string to be logged
+    def push(string)
+      internal_push(string)
+    end
+    alias << push
+
+    # Generate the following logging methods for Ken.logger as described
+    # in the API:
+    #  :fatal, :error, :warn, :info, :debug
+    #  :off only gets a off? method
+    LEVELS.each_pair do |name, number|
+      unless name.to_s == 'off'
+        class_eval <<-EOS, __FILE__, __LINE__
+          # DOC
+          def #{name}(message)
+            self.<<( prep_msg(message, "#{name}") ) if #{name}?
+          end
+        EOS
+      end
+
+      class_eval <<-EOS, __FILE__, __LINE__
+        # DOC
+        def #{name}?
+          #{number} >= level
+        end
+      EOS
+    end
+
+  end # class Logger
+end # module Ken