basuco 0.0.3

data/.gitignore

@@ -0,0 +1,24 @@
+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
+Gemfile.lock

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in basuco.gemspec
+gemspec

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,318 @@
+h1. Basuco (In Dev)
+
+h2. Introduction
+
+Basuco is a rails3 update in the form of a gem for the original Ken plugin.
+
+It provides simple syntax to interact with the freebase api, and wraps responses in handy ruby objects.
+
+h2. Installation
+
+<pre>
+<code>
+  $ gem install basuco
+</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/.
+
+With no registration you get 100K API calls per 24 hours, and more is available along with writing through registration.
+
+h3. Fetching a Resource
+
+Interaction with freebase occurs in three major ways. 
+
+First and most obvious is searching which will return collections built of resources, in turn built of properties.
+<pre><code>x = Basuco::Search.new</code></pre>
+Second is trans. The trans section is used for getting large chunks of text and images with their guid's.
+<pre><code>x = Basuco::Trans.new</code></pre>
+Lastly comes the Api for non-functional methods like logging in or checking the status of the api. 
+<pre><code>x = Basuco::Api.new</code></pre>
+
+Lets start with an example:
+
+<pre>
+<code>
+  x = Basuco::Search.new
+  x.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
+  
+  # alternatively you can access them directly
+  resource.attribute('/music/artist/album') # => #<Attribute property="/music/artist/album">
+</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>
+
+
+h3. Topic API
+
+Please first have a look at the official "Topic HTTP API documentation":http://www.freebase.com/docs/topic_api . 
+
+The API provides general meta-data such as name, description, links and images for a given topic,
+as well as all properties directly related to that topic in the graph.
+The API wraps a series of MQL queries that are needed to get this data, which otherwise must be performed separately.
+So for gaining common interest information about a specific topic the Topic API is a way faster alternative to mqlread.
+
+The latest update of Ken provides an easy way to access Freebase Topics using Ruby.
+As usual Ken wraps the JSON result of the web service to convenient Ruby Objects.
+
+For now Ken only returns simple properties. Support for so called mediator properties (aka 'CVT') will be added later.
+To be honest, I just don't know how to wrap them appropriately using the existing Ken object model. Any API ideas are welcome, btw! ;)
+However, in the meanwhile you can access CVT's by using the plain JSON result returned by the low level Ken.session.topic method.
+
+
+The API for Topics is quite the same as for Resources.
+
+<pre>
+<code>
+t = Ken::Topic.get("/en/new_order")
+  # => <Topic id="/en/new_order" name="New Order">
+    
+t.types
+  # => [ #<Type id="/music/artist" name="Musical Artist">, #<Type id="/music/musical_group" name="Musical Group">, ... ]
+
+t.views
+  # => [ #<View type="/music/artist">, #<View type="/music/musical_group">, ... ]
+    
+t.properties
+  # => [ #<Property id="/music/artist/similar_artist" expected_type="/music/artist">, ... ]
+
+t.attributes
+  # => [ #<Attribute property="/music/artist/similar_artist">, #<Attribute property="/music/artist/album">, ... ]
+
+</code>
+</pre>
+
+Additionally you can access some general meta-data, most importantly the topic's description which otherwise would need an additional request to the raw service.
+
+<pre>
+<code>
+
+t.name # => "New Order"
+t.description # => "New Order were an English musical group formed in 1980 by Bernard Sumner ... "
+t.aliases # => [ "NewOrder", "Englandneworder" ]
+t.webpages # => [ {"url"=>"http://en.wikipedia.org/wiki/index.html?curid=22146", "text"=>"Wikipedia"}, ... ]
+t.url # => "http://www.freebase.com/view/en/new_order"
+t.thumbnail => "http://api.freebase.com/api/trans/image_thumb/en/new_order"
+
+</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
+* Accessing Topics using the new Freebase Topic API
+
+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/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/basuco.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "basuco/version"
+
+Gem::Specification.new do |s|
+  s.name        = "basuco"
+  s.version     = Basuco::VERSION
+  s.authors     = ["Caleb Bron"]
+  s.email       = [""]
+  s.homepage    = "https://github.com/cbron/basuco"
+  s.summary     = %q{Freebase Gem}
+  s.description = %q{Transfer information from freebase.com through ruby.}
+
+  s.rubyforge_project = "basuco"
+
+  s.add_development_dependency "rspec"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+end

data/examples/artist.rb

@@ -0,0 +1,20 @@
+require 'rubygems'
+require 'pathname'
+
+EXAMPLES_ROOT = Pathname(__FILE__).dirname.expand_path
+require EXAMPLES_ROOT.parent + 'lib/basuco'
+
+session = Basuco::Search.new
+
+resource = session.get('/en/tiesto') #basically everything starts with /en/
+
+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