adamsalter-ken 0.1.1

data/.gitignore

@@ -0,0 +1,23 @@
+test_log
+pkg
+pkg/*
+*/pkg/*
+bundle
+bundle/*
+doc
+*.log
+log
+!log*.rb
+*/log
+log/*
+*/log/*
+coverage
+*/coverage
+lib/dm-more.rb
+*.db
+nbproject
+.DS_Store
+rspec_report.html
+*.swp
+_Yardoc
+*/ri

data/History.txt

@@ -0,0 +1,3 @@
+=== 0.0.1 / not released
+
+  * Birthday!

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Michael Aufreiter
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.textile

@@ -0,0 +1,264 @@
+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.
+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.
+
+You can navigate the Freebase Graph using a rubyish syntax.
+Also you can 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>
+
+In your Ruby files add:
+
+<pre>
+<code>
+  require 'rubygems'
+  gem 'michael-ken'
+  require 'ken'
+</code>
+</pre>
+
+
+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 Type's 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.
+
+h3. 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.
+
+h3. 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>
+
+h3. Fetching multiple Resources using a query
+
+As of now you can ask for multiple Resources by specifying a query.
+
+<pre>
+<code>
+  resources = Ken.all(:name => "Apple", :type => "/music/album")
+  # => [#<Resource id="/guid/9202a8c04000641f80000000031dae7c" name="Apple">,
+        #<Resource id="/guid/9202a8c04000641f8000000007ce31ec" name="Apple">]
+</code>
+</pre>
+
+Keep in mind that only the top level of the query is mapped to a Collection of Resource Objects.
+So asking for values in a nested level does not make sense. Use nested statements just for
+lowering the top level result.
+
+However you can instead navigate the normal way to figure out that values.
+_But won't that require another query to triggered? Certainly._
+
+Let's look at a nested query:
+
+<pre>
+<code>
+  query = {
+    :directed_by => "George Lucas",
+    :starring => [
+      {
+        :actor => "Harrison Ford"
+      }
+    ],
+    :type => "/film/film"
+  }
+  
+  resources = Ken.all(query)
+  # => [#<Resource id="/en/star_wars_episode_iv_a_new_hope" name="Star Wars Episode IV: A New Hope">,
+        #<Resource id="/en/american_graffiti" name="American Graffiti">,
+        #<Resource id="/en/the_star_wars_holiday_special" name="The Star Wars Holiday Special">]
+</code>
+</pre>
+
+h3. Access properties attributes directly
+
+Ken is primarily designed for inspecting resources in a generic way, what's ideal for domain independent browsing applications.
+However, there are legitimate situations where you already know what you want to access.
+
+That's why I now added direct Property/Attribute access, but only on a Type/View level:
+
+<pre>
+<code>
+  resource = Ken.get('/en/new_order')
+  type = resource.types[1] # => #<Type id="/music/artist" name="Musical Artist">
+  # because we know _/music/artist_ has a _genre_ property we can access that directly
+  type.genre # => #<Property id="/music/artist/genre" expected_type="/music/genre" unique="false" object_type="true">
+</code>
+</pre>
+
+The same works for views:
+
+<pre>
+<code>
+  resource = Ken.get('/en/new_order')
+  view = resource.views[1] # => #<View type="/music/artist">
+  # because we know _/music/artist_ has a _genre_ property we can access attribute directly as well
+  view.genre # => #<Attribute property="/music/artist/genre">
+</code>
+</pre>
+
+If you rather want to query based on Types and access Properties/Attributes directly you can consider using
+Chris "Eppsteins Freebase Library":http://github.com/chriseppstein/freebase/tree/master as an alternative. 
+
+
+h3. Low Level API
+
+Sometimes you may want to do specific queries instead of inspecting Resources as a whole.
+In such a case you would want to use Ken's low level API.
+
+_mqlread_ works like the regular _mqlread service_, except that you are able to pass ruby hashes instead of JSON.
+And you don't have to deal with HTTP, parameter encoding and parsing JSON.
+
+<pre>
+<code>
+  artists = Ken.session.mqlread([{
+    :type => "/music/artist",
+    :id => nil, 
+    :"/common/topic/webpage" => [{:uri => nil}], 
+    :home_page => [{:uri => nil}], 
+    :limit => 2
+  }])  
+  
+  # => [
+         {"type"=>"/music/artist", "home_page"=>[{"uri"=>"http://www.massiveattack.co.uk/"}], "id"=>"/en/massive_attack", "/common/topic/webpage"=>[{"uri"=>"http://musicmoz.org/Bands_and_Artists/M/Massive_Attack/"}, {"uri"=>"http://www.discogs.com/artist/Massive+Attack"}, {"uri"=>"http://www.massiveattackarea.com/"}, {"uri"=>"http://www.massiveattack.co.uk/"}, {"uri"=>"http://www.massiveattack.com/"}]},
+         {"type"=>"/music/artist", "home_page"=>[{"uri"=>"http://www.apartment26.com/"}], "id"=>"/en/apartment_26", "/common/topic/webpage"=>[{"uri"=>"http://www.discogs.com/artist/Apartment+26"}, {"uri"=>"http://musicmoz.org/Bands_and_Artists/A/Apartment_26/"}, {"uri"=>"http://www.apartment26.com/"}]}
+       ]
+</code>
+</pre>
+
+h2. Project Status
+
+h3. Features
+
+* Fetching of single Resources
+* Fetching of multiple Resources by specifying a query
+* Accessing Properties/Attributes directly (on a type/view level)
+* Type inspection
+* Attribute inspection
+* Low Level API (mqlread)
+* Rails and Merb support
+* Views on Resources to group Attributes based on the Resource's types
+
+h3. Roadmap
+
+# More tests
+# 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

@@ -0,0 +1,76 @@
+= Ken
+
+* http://www.github.com/michael/ken
+
+== DESCRIPTION:
+
+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:
+
+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:
+
+resource = Ken.get('/en/new_order') # => <Resource id="/en/new_order" name="New Order">
+
+== REQUIREMENTS:
+
+- Ruby >=1.8.x
+- RubyGems >=1.2.x
+- Extlib >=0.9.x
+
+== INSTALL:
+
+$ gem sources -a http://gems.github.com (you only have to do this once)
+$ sudo gem install michael-ken
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Michael Aufreiter
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,58 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "ken"
+    gem.summary = %Q{Ruby API for Accessing the Freebase}
+    gem.email = "ma[at]zive[dot]at"
+    gem.homepage = "http://github.com/michael/ken"
+    gem.authors = ["michael"]
+    gem.add_dependency('extlib')
+    gem.add_dependency('json')
+    gem.add_dependency('addressable')
+    # gem.files = FileList["[A-Z]*.*"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "ken #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.1

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,28 @@
+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', '*****')
+
+artists = Ken.session.mqlread([{
+  :type => "/music/artist",
+  :id => nil, 
+  :"/common/topic/webpage" => [{:uri => nil}], 
+  :home_page => [{:uri => nil}], 
+  :limit => 50
+}])
+
+artists.each do |artist|
+  artist["/common/topic/webpage"].each do |webpage|
+    puts webpage["uri"]
+  end
+  
+  artist["home_page"].each do |homepage|
+    puts homepage["uri"]
+  end
+end

data/ken.gemspec

@@ -0,0 +1,88 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{ken}
+  s.version = "0.1.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["michael"]
+  s.date = %q{2009-08-12}
+  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.4}
+  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/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