michael-ken 0.0.1 → 0.0.2

data/Manifest.txt

@@ -1,27 +1,34 @@
-.gitignore
 History.txt
 LICENSE
 Manifest.txt
-README.txt
 README.textile
+README.txt
 Rakefile
 TODO
-ken.gemspec
+examples/artist.rb
 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/version.rb
-spec/mql_spec.rb
-spec/property_spec.rb
-spec/resource_spec.rb
-spec/session_spec.rb
-spec/type_spec.rb
+lib/ken/view.rb
+spec/fixtures/music_artist.json
+spec/fixtures/the_police.json
+spec/integration/ken_spec.rb
 spec/spec.opts
 spec/spec_helper.rb
+spec/unit/attribute_spec.rb
+spec/unit/property_spec.rb
+spec/unit/resource_spec.rb
+spec/unit/session_spec.rb
+spec/unit/type_spec.rb
+spec/unit/view_spec.rb
+tasks/gemspec.rb
 tasks/hoe.rb
 tasks/install.rb
-tasks/spec.rb
+tasks/spec.rb

data/README.textile

@@ -0,0 +1,173 @@
+h1. Ken
+
+h2. Introduction
+
+Ken is a Data Layer for Knowledge Representation.
+
+It's being built to access the Metaweb Services supplied by Freebase.com.
+Just born, the project’s goals are the provision of a concise API for querying and writing.
+Therefore it wraps the Metaweb Architecture to smart Ruby Objects (that represent the Metaweb Architecture).
+
+You can navigate the Freebase Graph using a rubyish syntax.
+
+You should be able to use this Library as a Data Layer (instead of or in addition to 
+ActiveRecord/DataMapper) for your Web Framework of choice (Merb, Rails).
+
+
+h2. Installation
+
+Use GitHub RubyGems.
+
+<pre>
+<code>
+  $ gem sources -a http://gems.github.com (you only have to do this once)
+  $ sudo gem install michael-ken
+</code>
+</pre>
+
+Or even better, stay on The Edge.
+  
+
+h2. Getting started
+
+The first place to get started with Freebase is of course, Freebase. Try out their Browser at 
+"http://www.freebase.com":http://www.freebase.com.
+
+The Freebase Database can be thought of as a huge graph of interconnected nodes that represent 
+knowledge (in a much more structured way than wikipedia does).
+That graph can be viewed at a higher level through an object-oriented lens which leads to easier interaction.
+To understand the fundamental Metaweb Architecture please read the official
+"MQL Reference guide":http://download.freebase.com/MQLReferenceGuide.pdf (with focus on Chapter 2)
+provided by Freebase.
+
+In addition, you can learn a lot by employing the Freebase "Query Editor":http://www.freebase.com/tools/queryeditor/.
+
+h3. Fetching a Resource
+
+Let's ask Ken what he knows about the British Band New Order.
+
+<pre>
+<code>
+  resource = Ken.get('/en/new_order') # => <Resource id="/en/new_order" name="New Order">
+</code>
+</pre>
+
+h3. Inspecting the types
+
+Every Resource can have multiple types.
+
+<pre>
+<code>
+  resource.types
+  # => [ #<Type id="/film/music_contributor" name="Film music contributor">, #<Type id="/music/artist" name="Musical Artist">, 
+         #<Type id="/common/topic" name="Topic">, #<Type id="/music/musical_group" name="Musical Group">,
+         #<Type id="/broadcast/artist" name="Broadcast Artist">, #<Type id="/music/group_member" name="Musical Group Member"> ]
+</code>
+</pre>
+
+We can see that New Order is a member of Music Artist, Film Music Contributor, Broadcast Artist and other types.
+
+h3. Inspecting a types properties
+
+A type defines a set of properties to describe a Resource.
+
+<pre>
+<code>
+  resource.types.each do |type|
+    type.properties # => e.g. [ #<Property id="/music/musical_group/member"> ]
+  end
+</code>
+</pre>
+
+We get sets of Properties for each Type. The Type Musical Group has just one Property @/music/musical_group/member@
+named Members Of Musical Group.
+
+h4. Listing all Attributes
+
+After inspecting a Resource's Types and Properties we now know what we could know. But actually we don't know nothing :)
+So it's time to ask for the values of properties, the so called _Attributes_.
+
+~Note: In Ken's terminology we differ between _Properties_ and concrete Property instances, the _Attributes_, while
+Freebase itself doesn't.~ 
+
+<pre>
+<code>
+  resource.attributes.each do |att|
+    att # => e.g. #<Attribute property="/music/artist/album">
+    att.property.name # => e.g. "Albums"
+    
+    att.values
+    # e.g. => [ #<Resource id="/guid/9202a8c04000641f8000000002fa2556" name="Ceremony">, 
+                #<Resource id="/guid/9202a8c04000641f8000000002fa24d5" name="Procession">,
+                #<Resource id="/guid/9202a8c04000641f8000000002fa20d3" name="Everything's Gone Green">, ... ]
+    # e.g. => ["1980"]
+  end
+</code>
+</pre>
+
+Attributes are slightly more complicated to handle compared to Types and Properties.
+
+There are four kinds of Attributes.
+  * Unique Value Type
+  * Unique Object Type
+  * Non-unique Value Type
+  * Non-unique Object
+  
+In order to be able to use unique and non-unique Attributes in the same manner we always wrap the value of an Attribute
+in a Collection, no matter if there's one value or there are many.
+
+h4. Group Attributes by their Type using Views
+
+
+<pre>
+<code>
+  resource.views.each do |view|
+    view # => e.g. #<View type="/music/artist">
+    view.type # => e.g #<Type id="/music/artist" name="Musical Artist">
+    view.attributes
+    # => [#<Attribute property="/music/artist/home_page">, #<Attribute property="/music/artist/genre">,
+          #<Attribute property="/music/artist/active_start">, #<Attribute property="/music/artist/similar_artist">,
+          #<Attribute property="/music/artist/album">, #<Attribute property="/music/artist/label">,
+          #<Attribute property="/music/artist/track">, #<Attribute property="/music/artist/origin">]
+            
+    view.attributes.each do |att|
+      att.values
+      # e.g. => [ #<Resource id="/en/alternative_dance" name="Alternative dance">,
+                  #<Resource id="/en/synthpop" name="Synthpop">, 
+                  #<Resource id="/en/house_music" name="House music">,
+                  #<Resource id="/en/post-punk" name="Post-punk"> ]
+      # e.g. => ["1980"]
+    end
+  end
+</code>
+</pre>
+
+h2. Status
+
+Currently, the focus lies on inspecting Freebase Resources in a generic way. That's why
+there is no support for accessing Properties or Attributes directly when you know them already.
+That keeps me focussed and prevents me from adding too much sugar.
+
+Therefore I would say that the first application using Ken will definitely be a Browser Application. :)
+
+If you rather want to query based on Types and access Properties/Attributes directly you should consider using
+Chris "Eppsteins Freebase Library":http://github.com/chriseppstein/freebase/tree/master instead. 
+
+h3. Features
+
+* Fetching of single Resources
+* Type inspection
+* Attributes inspection
+* Views on Resources to group Attributes based on the Resource's types
+* Some specs
+
+h3. Roadmap
+
+# Much more specs
+# Support for querying of multiple Resources
+# Better Type Support
+# API for Set Based Browsing (see http://mqlx.com/~david/parallax/)
+# Accessing Properties/Attributes directly (e.g. resource.genres )
+# Write-Support
+
+Initial thoughts, obviously not up-to-date and not conforming to the current version, are available at "http://wiki.github.com/michael/ken":http://wiki.github.com/michael/ken.

data/README.txt

@@ -1,26 +1,54 @@
-= Mql
+= Ken
 
 * http://www.github.com/michael/ken
 
 == DESCRIPTION:
 
-FIX (describe your package)
+Ken is a Data Layer for Knowledge Representation.
+
+It's being built to access the Metaweb Services supplied by Freebase.com.
+Just born, the project’s goals are the provision of a concise API for querying and writing.
+Therefore it wraps the Metaweb Architecture to smart Ruby Objects (that represent the Metaweb Architecture).
+
+You can navigate the Freebase Graph using a rubyish syntax.
+
+You should be able to use this Library as a Data Layer (instead of or in addition to 
+ActiveRecord/DataMapper) for your Web Framework of choice (Merb, Rails).
+
 
 == FEATURES/PROBLEMS:
 
-* FIX (list of features or problems)
+Features
+
+* Fetching of single Resources
+* Type inspection
+* Attributes inspection
+* Views on Resources to group Attributes based on the Resource's types
+* Some specs
+
+Roadmap
+
+1. Much more specs
+2. Support for querying of multiple Resources
+3. Better Type Support
+4. API for Set Based Browsing (see http://mqlx.com/~david/parallax/)
+5. Accessing Properties/Attributes directly (e.g. resource.genres )
+6. Write-Support
 
 == SYNOPSIS:
 
-  FIX (code sample of usage)
+resource = Ken.get('/en/new_order') # => <Resource id="/en/new_order" name="New Order">
 
 == REQUIREMENTS:
 
-* FIX (list of requirements)
+- Ruby >=1.8.x
+- RubyGems >=1.2.x
+- Extlib >=0.9.x
 
 == INSTALL:
 
-* FIX (sudo gem install, anything else)
+$ gem sources -a http://gems.github.com (you only have to do this once)
+$ sudo gem install michael-ken
 
 == LICENSE:
 

data/Rakefile

@@ -11,7 +11,7 @@ require ROOT + 'lib/ken/version'
 AUTHOR           = 'Michael Aufreiter'
 EMAIL            = 'ma[at]zive[dot]at'
 GEM_NAME         = 'ken'
-GEM_VERSION      = '0.0.1'# Ken::VERSION
+GEM_VERSION      = '0.0.2'# Ken::VERSION
 GEM_DEPENDENCIES = [
   [ 'extlib', '>=0.9.10'     ]
   # [ 'addressable', '~>2.0.1' ]

data/examples/artist.rb

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

data/lib/ken.rb

@@ -8,9 +8,12 @@ require 'addressable/uri'
 dir = Pathname(__FILE__).dirname.expand_path + 'ken'
 
 require dir + 'version'
+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'
@@ -18,13 +21,22 @@ 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
   def self.all(options = {})
-    #raise ArgumentError.new("must be a hash") unless options.is_a(::Hash)
+    # raise ArgumentError.new("must be a hash") unless options.is_a(::Hash)
     raise NotImplementedError
   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">
   def self.get(id)
     # TODO check if it has a correct /type/object/id syntax
     raise ArgumentError.new("must be a string") unless id.is_a?(::String)
@@ -38,7 +50,10 @@ module Ken
         :properties => [{
           :id => nil,
           :name => nil,
-          :expected_type => nil
+          :expected_type => nil,
+          :unique => nil,
+          :reverse_property => nil,
+          :master_property => nil,
         }]
       }]
     }

data/lib/ken/attribute.rb

@@ -0,0 +1,52 @@
+module Ken
+  class Attribute
+    attr_reader :property
+    
+    # initializes a resource by json result
+    def initialize(data, property)
+      raise "error" unless data.kind_of?(Array)
+      
+      @data = data
+      @property = property # belongs to a property
+      self
+    end
+    
+    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 just the subject
+    def values
+      subject
+    end
+    
+    def unique?
+      @property.unique?
+    end
+    
+    def object_type?
+      @property.object_type?
+    end
+    
+    # is this a good idea? using the values method seems more natural to me
+    # def method_missing(name, *args, &block)
+    #   subject.send(name, *args, &block)
+    # end
+    
+    # initializes the subject if used the first time
+    private
+    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

@@ -7,5 +7,10 @@ module Ken
     # def method_missing(name, *args, &blk)
     #   @data.send name, *args, &blk
     # end
+    
+    # add a linebreak after each entry
+    def to_s
+      self.inject("") { |m,i| "#{m}#{i.to_s}\n"}
+    end
   end
 end

data/lib/ken/property.rb

@@ -4,24 +4,78 @@ module Ken
     # initializes a resource by json result
     def initialize(data, type)
       raise "error" unless data.kind_of?(Hash)
-
       @data = data
       @type = type
       self
     end
     
+    # @api public
     def id
       @data["id"]
     end
-
+    
+    # @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
     
+    # @api public
+    def reverse_property
+      @data["reverse_property"]
+    end
+    
+    # @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?
+      !%w{
+         /type/id
+         /type/int
+         /type/float
+         /type/boolean
+         /type/text
+         /type/rawstring
+         /type/uri
+         /type/datetime
+         /type/key
+        }.include?(expected_type)
+    end
+    
+    # returns true if the property is a value type
+    # @api public
+    def value_type?
+      !object_type?
+    end
+    
+    # @api public
     def expected_type
       @data["expected_type"]
     end