basuco 0.0.3

data/lib/basuco.rb

@@ -0,0 +1,30 @@
+require 'net/http'
+require 'json'
+
+Dir[File.dirname(__FILE__) + '/basuco/*.rb'].each {|file| require file }
+
+module Basuco
+    include Request
+
+    #hash of all statuses
+    def self.check_statuses
+      response = http_request status_service_url
+      result = JSON.parse response
+      result
+    end
+  
+end # module Basuco
+
+
+#todo
+
+#search = search,mql's, session = login/logout, status, trans = images, blurbs
+#status all-in-one
+
+#re-structure
+#check all calls, add and modify
+#writing ?
+#rspec's
+
+#write wd
+#post wd

data/lib/basuco/api.rb

@@ -0,0 +1,26 @@
+module Basuco
+  class << self
+    attr_accessor :api
+  end
+
+  class Api
+    include Request
+    def initialize(options = {:host => 'http://www.freebase.com', :username => 'un', :password => 'pw'})
+      @host = options[:host]
+      @username = options[:username]
+      @password = options[:password]
+      Basuco.api = self
+    end
+
+    def api(options = {})
+      options.merge!({:query => query})
+      
+      response = http_request search_service_url, options
+      result = JSON.parse response
+      
+      handle_read_error(result)
+      
+      result['result']
+    end
+  end
+end

data/lib/basuco/attribute.rb

@@ -0,0 +1,67 @@
+module Basuco
+  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, Basuco::Property
+      @data, @property = data, property
+    end
+    
+    # factory method for creating an attribute instance
+    # @api semipublic
+    def self.create(data, property)
+      Basuco::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
+    
+    # type, which attribute values of that property are expected to have
+    # @api public
+    def expected_type
+      @property.expected_type
+    end
+    
+    private
+    # initializes the subject if used for the first time
+    def subject
+      @subject ||= Basuco::Collection.new(@data.map { |r| object_type? ? Basuco::Resource.new(r) : r["value"] })
+    end
+  end
+end

data/lib/basuco/collection.rb

@@ -0,0 +1,7 @@
+module Basuco
+  class Collection < Array
+    def to_s
+      self.inject("") { |m,i| "#{m}#{i.to_s}\n"}
+    end
+  end
+end

data/lib/basuco/property.rb

@@ -0,0 +1,91 @@
+module Basuco
+  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, Basuco::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/basuco/request.rb

@@ -0,0 +1,86 @@
+module Request
+
+    SERVICES = {
+      :mqlread => '/api/service/mqlread',
+      :mqlwrite => '/api/service/mqlwrite',
+      :blurb => '/api/trans/blurb/guid/',
+      :raw => '/api/trans/raw/guid/',
+      :login => '/api/account/login', #not done
+      :logout => '/api/account/logout', #not done
+      :upload => '/api/service/upload',
+      :topic => '/experimental/topic',
+      :search => '/api/service/search',
+      :status => '/api/status', #not done
+      :thumb => 'api/trans/image_thumb'
+
+    }
+
+    def service_url(svc)
+      "#{@host}#{SERVICES[svc]}"
+    end
+
+    SERVICES.each_key do |k|
+      define_method("#{k}_service_url") do
+        service_url(k)
+      end
+    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 TopicNotFound < StandardError ; end
+  class ViewNotFound < StandardError ; 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'
+        error = inner['messages'][0]
+        raise ReadError.new(error['code'], error['message'])
+      end
+    end # handle_read_error
+
+    # returns parsed json response from freebase mqlread service
+    def get_query_response(query, cursor=nil)
+      envelope = { :qname => {:query => query, :escape => false }}
+      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)
+      inner
+    end
+    
+    # encode parameters
+    def params_to_string(parameters)
+      parameters.keys.map {|k| "#{URI.encode(k.to_s)}=#{URI.encode(parameters[k].to_s)}" }.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
+    end
+
+  end #Request

data/lib/basuco/resource.rb

@@ -0,0 +1,215 @@
+module Basuco
+  class Resource
+    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_fetched = data["/type/reflect/any_master"] != nil
+    end
+    
+    # Executes an Mql Query against the Freebase API and returns the result wrapped
+    # in a <tt>Resource</tt> Object.
+    #
+    # == Examples
+    #
+    #  Basuco::Resource.get('/en/the_police') => #<Resource id="/en/the_police" name="The Police">
+    # @api public
+    def self.get(id)
+     # assert_kind_of 'id', id, String
+      arr = Resource.define_query
+      result = Basuco.search.mqlread(arr.merge!(:id => id))
+      raise ResourceNotFound unless result
+      Basuco::Resource.new(result)
+    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 ||= Basuco::Collection.new(types.map { |type| Basuco::View.new(self, type) })
+    end
+    
+    # returns individual view based on the requested type id
+    # @api public
+    def view(type)
+      views.each { |v| return v if v.type.id =~ /^#{Regexp.escape(type)}$/}
+      nil
+    end
+    
+    # returns individual type based on the requested type id
+    # @api public
+    def type(type)
+      types.each { |t| return t if t.id =~ /^#{Regexp.escape(type)}$/}
+      nil
+    end
+
+    # returns all the properties from all assigned types
+    # @api public
+    def properties
+      @properties = Basuco::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 = Basuco.search.mqlread(define_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 = Basuco::Util.convert_hash(@data["/type/reflect/any_master"])
+      raw_attributes.merge!(Basuco::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] = Basuco::Attribute.create(d, p)
+        end
+      end
+      # reverse properties
+      raw_attributes = Basuco::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] = Basuco::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 = Basuco::Collection.new(@data["Basuco:type"].map { |type| Basuco::Type.new(type) })
+      @schema_loaded = true
+    end
+
+    def self.define_query
+        {
+        # :id => id, # needs to be merge!d in instance method
+        :guid => nil,
+        :name => nil,
+        :"Basuco: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"
+          }
+        ]
+      }
+    end
+  end # class Resource
+end # module Basuco