adamsalter-ken 0.1.1

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

data/lib/ken/property.rb

@@ -0,0 +1,91 @@
+module Ken
+  class Property
+    
+    include Extlib::Assertions
+    
+    VALUE_TYPES = %w{
+     /type/id
+     /type/int
+     /type/float
+     /type/boolean
+     /type/text
+     /type/rawstring
+     /type/uri
+     /type/datetime
+     /type/key
+    }
+    
+    # initializes a resource by json result
+    def initialize(data, type)
+      assert_kind_of 'data', data, Hash
+      assert_kind_of 'type', type, Ken::Type
+      @data, @type = data, type
+    end
+    
+    # property id
+    # @api public
+    def id
+      @data["id"]
+    end
+    
+    # property name
+    # @api public
+    def name
+      @data["name"]
+    end
+    
+    # @api public
+    def to_s
+      name || id || ""
+    end
+    
+    # @api public
+    def inspect
+      result = "#<Property id=\"#{id}\" expected_type=\"#{expected_type || "nil"}\" unique=\"#{unique?}\" object_type=\"#{object_type?}\">"
+    end
+    
+    # returns the type of which the property is a part of
+    # every property always has exactly one type.
+    # that's why /type/property/schema is a unique property
+    # @api public
+    def type
+      @type
+    end
+    
+    # reverse property, which represent incoming links
+    # @api public
+    def reverse_property
+      @data["reverse_property"]
+    end
+    
+    # master property, which represent an outgoing link (or primitive value)
+    # @api public
+    def master_property
+      @data["master_property"]
+    end
+    
+    # returns true if the property is unique
+    # @api public
+    def unique?
+      return @data["unique"]==true
+    end
+    
+    # returns true if the property is an object type
+    # @api public
+    def object_type?
+      !value_type?
+    end
+    
+    # returns true if the property is a value type
+    # @api public
+    def value_type?
+      VALUE_TYPES.include?(expected_type)
+    end
+    
+    # type, which attribute values of that property are expected to have
+    # @api public
+    def expected_type
+      @data["expected_type"]
+    end
+  end
+end

data/lib/ken/resource.rb

@@ -0,0 +1,144 @@
+module Ken
+  class Resource
+    include Extlib::Assertions
+    
+    attr_reader :data
+    
+    # initializes a resource using a json result
+    def initialize(data)
+      assert_kind_of 'data', data, Hash
+      @schema_loaded, @attributes_loaded, @data = false, false, data
+      @data_fechted = data["/type/reflect/any_master"] != nil
+    end
+    
+    # resource id
+    # @api public
+    def id
+      @data["id"] || ""
+    end
+    
+    # resource guid
+    # @api public
+    def guid
+      @data['guid'] || ""
+    end
+    
+    # resource name
+    # @api public
+    def name
+      @data["name"] || ""
+    end
+    
+    # @api public
+    def to_s
+      name || id || ""
+    end
+    
+    # @api public
+    def inspect
+      result = "#<Resource id=\"#{id}\" name=\"#{name || "nil"}\">"
+    end
+    
+    # returns all assigned types
+    # @api public
+    def types
+      load_schema! unless schema_loaded?
+      @types
+    end
+    
+    # returns all available views based on the assigned types
+    # @api public
+    def views
+      @views ||= Ken::Collection.new(types.map { |type| Ken::View.new(self, type) })
+    end
+    
+    # returns individual view based on the requested type
+    # @api public
+    def view(type)
+      types.each { |t| return Ken::View.new(self, t) if t.id =~ /^#{Regexp.escape(type)}$/ }
+      nil
+    end
+
+    # returns all the properties from all assigned types
+    # @api public
+    def properties
+      @properties = Ken::Collection.new
+      types.each do |type|
+        @properties.concat(type.properties)
+      end
+      @properties
+    end
+    
+    # returns all attributes for every type the resource is an instance of
+    # @api public
+    def attributes
+      load_attributes! unless attributes_loaded?
+      @attributes.values
+    end
+    
+    # search for an attribute by name and return it
+    # @api public
+    def attribute(name)
+      attributes.each { |a| return a if a.property.id == name }
+      nil
+    end
+    
+    # returns true if type information is already loaded
+    # @api public
+    def schema_loaded?
+      @schema_loaded
+    end
+    
+    # returns true if attributes are already loaded
+    # @api public
+    def attributes_loaded?
+      @attributes_loaded
+    end
+    # returns true if json data is already loaded
+    # @api public
+    def data_fetched?
+      @data_fetched
+    end
+    
+    private
+    # executes the fetch data query in order to load the full set of types, properties and attributes
+    # more info at http://lists.freebase.com/pipermail/developers/2007-December/001022.html
+    # @api private
+    def fetch_data
+      return @data if @data["/type/reflect/any_master"]
+      @data = Ken.session.mqlread(FETCH_DATA_QUERY.merge!(:id => id))
+    end
+    
+    # loads the full set of attributes using reflection
+    # information is extracted from master, value and reverse attributes
+    # @api private
+    def load_attributes!
+      fetch_data unless data_fetched?
+      # master & value attributes
+      raw_attributes = Ken::Util.convert_hash(@data["/type/reflect/any_master"])
+      raw_attributes.merge!(Ken::Util.convert_hash(@data["/type/reflect/any_value"]))
+      @attributes = {}
+      raw_attributes.each_pair do |a, d|
+        properties.select { |p| p.id == a}.each do |p|
+          @attributes[p.id] = Ken::Attribute.create(d, p)
+        end
+      end
+      # reverse properties
+      raw_attributes = Ken::Util.convert_hash(@data["/type/reflect/any_reverse"])
+      raw_attributes.each_pair do |a, d|
+        properties.select { |p| p.master_property == a}.each do |p|
+          @attributes[p.id] = Ken::Attribute.create(d, p)
+        end
+      end
+      @attributes_loaded = true
+    end
+    
+    # loads the resource's metainfo
+    # @api private
+    def load_schema!
+      fetch_data unless data_fetched?
+      @types = Ken::Collection.new(@data["ken:type"].map { |type| Ken::Type.new(type) })
+      @schema_loaded = true
+    end
+  end # class Resource
+end # module Ken

data/lib/ken/session.rb

@@ -0,0 +1,132 @@
+module Ken
+  class << self #:nodoc:
+    attr_accessor :session
+  end
+  
+  # A class for returing errors from the freebase api.
+  # For more infomation see the freebase documentation:
+  class ReadError < ArgumentError
+    attr_accessor :code, :msg
+    def initialize(code,msg)
+      self.code = code
+      self.msg = msg
+    end
+    def message
+      "#{code}: #{msg}"
+    end
+  end
+  
+  class AttributeNotFound < StandardError; end
+  class PropertyNotFound < StandardError; end
+  class ResourceNotFound < StandardError; end
+  class ViewNotFound < StandardError; end
+  
+  # partially taken from chris eppstein's freebase api
+  # http://github.com/chriseppstein/freebase/tree
+  class Session
+    
+    public
+    # Initialize a new Ken Session
+    #   Ken::Session.new(host{String, IO}, username{String}, password{String})
+    #
+    # @param host<String>          the API host
+    # @param username<String>      freebase username
+    # @param password<String>      user password
+    def initialize(host, username, password)
+      @host = host
+      @username = username
+      @password = password
+      
+      Ken.session = self
+
+      # TODO: check connection
+      Ken.logger.info("connection established.")
+    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)
+      "#{@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'][0, '/api/status/ok'.length] == '/api/status/ok'
+        Ken.logger.error "Read Error #{inner.inspect}"
+        error = inner['messages'][0]
+        raise ReadError.new(error['code'], error['message'])
+      end
+    end # handle_read_error
+
+
+    # perform a mqlread and return the results
+    # TODO: should support multiple queries
+    #       you should be able to pass an array of queries
+    # Specify :cursor => true to batch the results of a query, sending multiple requests if necessary.
+    def mqlread(query, options = {})
+      Ken.logger.info ">>> Sending Query: #{query.to_json}"
+      cursor = options[:cursor]
+      if cursor
+        query_result = []
+        while cursor
+          response = get_query_response(query, cursor)
+          query_result += response['result']
+          cursor = response['cursor']
+        end
+      else
+        response = get_query_response(query, cursor)
+        cursor = response['cursor']
+        query_result = response['result']
+      end
+      query_result
+    end
+
+    protected
+    # returns parsed json response from freebase mqlread service
+    def get_query_response(query, cursor=nil)
+      envelope = { :qname => {:query => query }}
+      envelope[:qname][:cursor] = cursor if cursor
+      
+      response = http_request mqlread_service_url, :queries => envelope.to_json
+      
+      result = JSON.parse response
+      
+      inner = result['qname']
+      handle_read_error(inner)
+      Ken.logger.info "<<< Received Response: #{inner['result'].inspect}"
+      inner
+    end
+    
+    # encode parameters
+    def params_to_string(parameters)
+      parameters.keys.map {|k| "#{URI.encode(k.to_s)}=#{URI.encode(parameters[k])}" }.join('&')
+    end
+    
+    # does the dirty work
+    def http_request(url, parameters = {})
+      params = params_to_string(parameters)
+      url << '?'+params unless params !~ /\S/
+
+      return Net::HTTP.get_response(::URI.parse(url)).body
+      
+      fname = "#{MD5.md5(params)}.mql"
+      open(fname,"w") do |f|
+        f << response
+      end
+      Ken.logger.info("Wrote response to #{fname}")
+    end
+    
+  end # class Session
+end # module Ken

data/lib/ken/type.rb

@@ -0,0 +1,53 @@
+module Ken
+  class Type
+    
+    include Extlib::Assertions
+    
+    # initializes a resource using a json result
+    def initialize(data)
+      assert_kind_of 'data', data, Hash
+      @data = data
+    end
+    
+    # access property info
+    # @api public
+    def properties
+      @properties ||= Ken::Collection.new(@data["properties"].map { |property| Ken::Property.new(property, self) })
+    end
+    
+    # type id
+    # @api public
+    def id
+      @data["id"]
+    end
+    
+    # type name
+    # @api public
+    def name
+      @data["name"]
+    end
+    
+    # @api public
+    def to_s
+      name || id || ""
+    end
+    
+    # @api public
+    def inspect
+      result = "#<Type id=\"#{id}\" name=\"#{name || "nil"}\">"
+    end
+    
+    # delegate to property_get
+    def method_missing sym
+      property_get(sym.to_s)
+    end
+    
+    private
+    # @api private
+    # search for a property by name and return it
+    def property_get(name)
+      properties.each { |p| return p if p.id =~ /\/#{name}$/ }
+      raise PropertyNotFound
+    end
+  end
+end

data/lib/ken/util.rb

@@ -0,0 +1,18 @@
+module Ken
+  module Util
+    # magic hash conversion
+    def convert_hash(source)
+      source.inject({}) do |result, item|
+        if result[item["link"]]
+          result[item["link"]] << { "id" => item["id"], "name" => item["name"], "value" => item["value"] }
+        else
+          result[item["link"]] = []
+          result[item["link"]] << { "id" => item["id"], "name" => item["name"], "value" => item["value"] }
+        end
+        result
+      end
+    end
+    module_function :convert_hash
+  end
+end
+