swivel 0.0.1

data/CHANGELOG

@@ -0,0 +1,4 @@
+= 0.0.1
+== 4th June, 2007
+
+* An api for swivel.  XML ensues.

data/COPYING

@@ -0,0 +1,18 @@
+Copyright (c) 2007 Swivel
+
+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 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

@@ -0,0 +1,315 @@
+= swivel.rb
+
+Without fancy screencast software, I'm content with this:
+
+     #####   #     #  ###  #     #  #######  #               ######   ######   
+    #     #  #  #  #   #   #     #  #        #               #     #  #     #  
+    #        #  #  #   #   #     #  #        #               #     #  #     #  
+     #####   #  #  #   #   #     #  #####    #               ######   ######   
+          #  #  #  #   #    #   #   #        #         ###   #   #    #     #  
+    #     #  #  #  #   #     # #    #        #         ###   #    #   #     #  
+     #####    ## ##   ###     #     #######  #######   ###   #     #  ######   
+
+(bam!)
+
+swivel.rb is a smallish bit that lets you interface with Swivel's REST API.
+
+== The REST API
+
+TODO: some copy
+
+    ------    -----------                ------------
+    method    uri                        what it does
+    ------    -----------                ------------
+
+    data_columns
+    get       /rest/data_columns         list data_columns
+    get       /rest/data_columns/#{id}   show data_column #{id}
+    put       /rest/data_columns/#{id}   update data_column #{id}
+
+    data_sets
+    post      /rest/data_sets            create a new data_set
+    delete    /rest/data_sets/#{id}      delete data_set #{id}
+    get       /rest/data_sets            list data_sets
+    get       /rest/data_sets/#{id}      show data_set #{id}
+    put       /rest/data_sets/#{id}      update data_set #{id}
+
+    graphs
+    post      /rest/graphs               create a new graph
+    delete    /rest/graphs/#{id}         delete graph #{id}
+    get       /rest/graphs               list graphs
+    get       /rest/graphs/#{id}         show graph #{id}
+    put       /rest/graphs/#{id}         update graph #{id}
+
+    users
+    get       /rest/users                list users
+    get       /rest/users/#{id}          show user #{id}
+    put       /rest/users/#{id}          update user #{id}
+
+TODO: optional parameters for lists, etc.
+TODO: search
+TODO: echo
+
+== Make it go go racer
+
+    $ sudo gem install swivel
+    Successfully installed swivel, version 0.0.1
+    Installing ri documentation for swivel-0.0.1...
+    Installing RDoc documentation for swivel-0.0.1...
+
+    $ irb
+    >> require 'swivel'
+    => true
+    >> swivel = Swivel::Connection.new
+    => #<Swivel::Connection:0xb7a29fb0 ...
+    >> puts swivel.call('/rest/test/echo/howdy')
+    <?xml version="1.0" encoding="UTF-8"?>
+    <response at="Sat, 09 Jun 2007 23:59:29 -0700" success="true">
+    <echo version="0" text="howdy"/>
+    </response>
+    => nil
+
+== Class hierarchy
+
+  * Swivel::Connection
+  * Swivel::Connection::Config
+  * Swivel::Response
+    * Swivel::DataColumn
+    * Swivel::DataSet
+    * Swivel::Graph
+    * Swivel::User
+    * Swivel::List
+  * Swivel::ApiError
+
+== RTF!M
+
+Never fear, it's installed when you install the gem.
+
+    $ ri Swivel
+
+Another nice one:
+
+    $ ri Swivel::Response
+
+== Examples.  Worth a thousand words
+
+Ready, set, ... wait.  Got an API key?  Get an API key (http://swivel.com/api/key).
+Try to keep your API key close to your chest, safely tucked away from prying eyes
+and dangers of the "real world"... dangers like parking tickets and untied shoelaces.
+It's like a password, so don't share it.
+
+    # writes your api key into ~/.swivelrc
+    swivel -k <your api key>
+
+Now, back to it.  Ready, set, go!
+
+    $ irb
+    >> require 'swivel'
+    => true
+
+A Swivel::Connection instance is your main interface to Swivel's API.  The
+connection loads up (and possibly creates) your ~/.swivelrc and sets up
+several parameters, such as your API key, that are used throughout calls to
+Swivel.
+
+    >> swivel = Swivel::Connection.new
+    => #<Swivel::Connection:0xb7a2bb58 @config={:timeout_down=>10, :api_key=>"xxx", :host=>"api.swivel.com", :port=>80, :timeout_up=>200}, headers{"Accept"=>"application/xml"}
+
+Swivel::Connection#call is the method you'll probably use most frequently.
+Send in any REST url (including query strings containing any options) and
+it will try faithfully to get back something useful for you.
+
+In many cases, Swivel::Connection#call will return an object whose class is
+inherited from Swivel::Response.
+
+    # look!  we got a Swivel::DataSet object!  frabjous day!
+    >> data_set = swivel.call '/rest/data_sets/1000000'
+    => #<Swivel::DataSet:0xb79dd688 @response=<response success='true' at='Mon, 04 Jun 2007 04:41:04 -0700'> .... , xml_tag"data-set", docUNDEFINED .... 
+
+Question: what if it can't find an appropriate class to instantiate?  Then it
+just gives you back the XML as a String, trusting that you'll love and care for
+it.
+
+    # Swivel::Connection#call can't find a class to instantiate this time,
+    # so it just sends us XML.
+    >> puts swivel.call('/rest/test/echo/howdy')
+    <?xml version="1.0" encoding="UTF-8"?>
+    <response success="true" at="Mon, 04 Jun 2007 03:34:49 -0700">
+      <echo text="howdy" version="0"/>
+    </response>
+
+But, back to objects.  Swivel::Connection#call often returns objects that
+encapsulate the XML response that the Swivel API sent.
+
+    >> data_set = swivel.call '/rest/data_sets/1000000'
+    => #<Swivel::DataSet:0xb79dd688 @response=<response success='true' at='Mon, 04 Jun 2007 04:41:04 -0700'> .... , xml_tag"data-set", docUNDEFINED .... 
+
+These objects are rich and meaty.  You can poke them and they shall respond,
+surlily.
+
+    >> data_set.id
+    => 1000000
+    >> data_set.user.name
+    => "huned"
+    >> data_set.data_columns[3].name
+    => "by-nc-nd-2.0"
+
+However, these objects are magickal in the ruby way, and they wish to often
+tightly conceal their secrets.  Some standard snooping shall leave you unsatisfied:
+
+    # let's call Swivel::DataSet#id
+    >> data_set.swivel_id
+    => 1000000  # huzzah!
+    # yet... it's not there in the list of methods
+    >> data_set.methods.grep /swivel_id/
+    => []  # what the..?
+
+So how do you know what to call?  At this time, the best way is to inspect
+the inner power-juice, the XML.
+
+    >> puts data_set.to_xml
+    <data-set swivel-id='1000000' version='0'>
+      <name>name?</name>
+      <user swivel-id='1000010'>
+        <name>huned</name>
+      </user>
+      <created-at>Sat, 02 Jun 2007 20:35:45 -0700</created-at>
+      <updated-at>Sat, 02 Jun 2007 20:35:49 -0700</updated-at>
+      <source>
+        <citation>name?</citation>
+        <citation-url/>
+      </source>
+      <rows>367</rows>
+      <columns>7</columns>
+      ...
+    </data-set>
+
+== Constructing URLs
+
+Constructing URLs are free and easy!  (Freeasy... mmm!)
+
+Any object in Swivel has a corresponding page that you can view with your
+browser.
+
+    # get the data_set's id
+    id = data_set.id
+    # get the data_set's resource... turns Swivel::DataSet into 'data_set'
+    resource = data_set.class.name.split('::').last.underscore # => "data_set"
+
+    # copy/paste this url into your browser
+    url = "http://swivel.com/#{resource}s/show/#{id}"
+
+Graphs have pages, but if you want to grab the actual graph image, here's how:
+
+    # as before, we get the id and resource type
+    id = data_set.id
+    resource = data_set.class.name.split('::').last.underscore # => "data_set"
+
+    url = "http://swivel.com/#{resource}s/image/share/#{width}/#{height}"
+
+If you have a specific graph visualization in mind, you can use a complex-er URL that allows you to decorate the image with various options like time scales, aggregation functions, and graph types.
+
+    url = "http://swivel.com/#{resource}s/image/share/#{width}/#{height}/#{limit}/#{scale}/#{graph_type}/#{order_by_direction}/#{time_range}/#{time_scale}/#{aggregation_function}"
+
+TODO: explain it in this here table
+
+    * width
+    * height
+    * limit
+    * scale
+    * graph_type
+    * order_by_direction
+    * time_range
+    * time_scale
+    * aggregation_function
+
+== Something completely different: A tryst at the command line
+
+The command line program lets you query Swivel or upload data into Swivel.
+You get this program when you install the Swivel gem.
+
+    $ which swivel
+    /usr/bin/swivel
+
+It uses a ~/.swivelrc file to remember settings.  If you don't have a
+~/.swivelrc, running the program will create a default one for you.
+
+    $ ls -lh ~/.swivelrc
+    ls: /home/huned/.swivelrc: No such file or directory
+    $ swivel
+    Usage: swivel [options]
+        -h, --host=name                  Swivel hostname or IP address.
+                                         Default: 
+        -p, --port=number                Swivel host's port number.
+                                         Default: 
+        -f, --file=file                  File to upload, append, or replace.
+        -r, --raw=path                   Perform a raw call and print the XML response.
+        -?, --help                       Show this help message.
+        -k, --key=api-key                Set your API key.
+    $ ls -lh ~/.swivelrc 
+    -rw-rw-r-- 1 huned huned 105 Jun  4 05:04 /home/huned/.swivelrc
+
+Note, however, that the api_key setting is blank.  Once you finagle an api key,
+run `swivel -k <your api key>` to update your ~/.swivelrc. (Remember: finagle an api
+key from http://swivel.com/api/key.)
+
+    $ cat ~/.swivelrc 
+    --- 
+    protocol: http://
+    timeout_up: 200
+    api_key: ""
+    timeout_down: 100
+    host: api.swivel.com
+    port: 80
+
+So how about uploading data?
+
+    $ swivel upload "my awesome data" -f data.csv
+    uploaded data_set 1000234
+
+Then your dataset magickally appears online at:
+
+    http://swivel.com/data_sets/show/1000234
+
+Here's the same thing, but via STDIN.  Consuming data from STDIN is a powerful
+little mechanism that lets you rig arbitrary swivel uploads through unix
+process piping (|).
+
+    $ cat data.csv | swivel upload "my awesome data"
+    uploaded data_set 1000234
+
+If you want to append to a data_set you previously uploaded:
+
+    $ cat more_data.csv | swivel append 1000234
+    appended data_set 1000234
+
+And finally, if you want to replace the entire data set with some other,
+fancier data:
+
+    $ cat fancier_data.csv | swivel replace 1000234
+    replaced data_set 1000234
+
+One caveat when appending or replacing:  Your new data must have the same
+column structure as the original data.  Or in other words, your new data must
+have the same column structure as the original data.
+
+In addition to being a fine way to use swivel, the command line program
+serves as a nice example of how you might use swivel.rb.  swivel.rb is the
+piece of code that allows ruby and the swivel api to be superhero and sidekick.
+(Stop here for a moment and visualize that.)
+
+Edit by Visnu: Huned wrote this at 4am.  He tired out right here.
+
+== Feedback
+
+Feedback, comments, and (especially) patches welcome at developer@swivel.com.
+
+== Respek
+
+Respeks to _why, errtheblog, 37signals, our moms, and of course the community.
+Wanna write code with us?  http://swivel.com/about/jobs
+
+== License
+
+This software is licensed under the exact same license as Ruby itself.  Peace
+out.

data/Rakefile

@@ -0,0 +1,80 @@
+#
+# this file (graciously) adapted from hpricot.  (respeks to _why.)
+#
+
+require 'rake'
+require 'rake/clean'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/testtask'
+require 'fileutils'
+include FileUtils
+
+NAME = "swivel"
+REV = `svn info`[/Revision: (\d+)/, 1] rescue nil
+VERS = ENV['VERSION'] || "0.0" + (REV ? ".#{REV}" : "")
+CLEAN.include ['doc', 'pkg']
+RDOC_OPTS = ['--line-numbers', '--title', 'swivel.rb', '--main', 'README', '--inline-source']
+
+desc "Does a full compile, test run"
+task :default => [:package, :test, :rdoc]
+
+desc "Packages up Swivel."
+task :package => [:clean]
+
+desc "Releases packages for all Swivel packages and platforms."
+task :release => [:package]
+
+desc "Run all the tests"
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/test_*.rb']
+  t.verbose = true
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'doc/rdoc'
+  rdoc.options += RDOC_OPTS
+  rdoc.main = "README"
+  rdoc.rdoc_files.add ['README', 'CHANGELOG', 'COPYING', 'lib/*.rb']
+end
+
+spec =
+  Gem::Specification.new do |s|
+    s.name = NAME
+    s.version = VERS
+    s.summary = 'Ruby interface to the Swivel API.'
+    s.description = <<-EOS
+      This gem installs client library for accessing Swivel through it's API.
+    EOS
+
+    s.has_rdoc = true
+    s.rdoc_options += RDOC_OPTS
+    s.extra_rdoc_files = ["README", "CHANGELOG", "COPYING"]
+
+    s.author = 'huned'
+    s.email = 'huned@swivel.com'
+    s.homepage = 'http://swivel.com/developer'
+
+    s.files = %w/COPYING README Rakefile/ + Dir['{lib,bin}/*']
+    s.require_path = "lib"
+    s.bindir = "bin"
+  end
+
+Rake::GemPackageTask.new(spec) do |p|
+  p.need_tar = true
+  p.gem_spec = spec
+end
+
+task "lib" do
+  directory "lib"
+end
+
+task :install do
+  sh %{rake package}
+  sh %{sudo gem install pkg/#{NAME}-#{VERS}}
+end
+
+task :uninstall => [:clean] do
+  sh %{sudo gem uninstall #{NAME}}
+end

data/bin/swivel

@@ -0,0 +1,135 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'active_support' # TODO: make it work w/o this
+require 'optparse'
+require File.dirname(__FILE__) + '/../lib/swivel'
+require 'yaml'
+
+#require 'ruby-debug'
+#Debugger.start
+
+options = Hash.new
+config = Swivel::Connection::Config.new
+config.load
+config.save
+
+ARGV.options do |opts|
+  opts.on '-h', '--host=name', String,
+    "Swivel hostname or IP address.",
+    "Default: #{options[:host]}" do |v| options[:host] = v end
+
+  opts.on '-p', '--port=number', String,
+    "Swivel host's port number.",
+    "Default: #{options[:port]}" do |v| options[:port] = v end
+
+  opts.on '-f', '--file=file', String,
+    "File to upload, append, or replace." do |v|
+      options[:filename] = v
+    end
+
+  opts.on_tail '-r', '--raw=path', String,
+    "Perform a raw call and print the XML response." do |v|
+      puts Swivel::Connection.new(options).call(v, options)
+      exit
+    end
+
+  opts.on_tail '-k', '--key=api-key',
+    "Set your API key." do |v|
+      config = Swivel::Connection::Config.new
+      config.config[:old_api_key] = config.config[:api_key]
+      config.config[:api_key] = v
+      config.save
+      exit
+    end
+
+  opts.on_tail '-?', '--help',
+    "Show this help message." do puts opts; exit end
+
+  opts.parse!
+
+  if ARGV.empty?
+    puts opts
+    exit
+  end
+end
+
+class SwivelHelper
+  def initialize options = Hash.new
+    @swivel = Swivel::Connection.new options
+  end
+
+  def show resource, id
+    resource = resource.pluralize
+    response = @swivel.call "/rest/#{resource}/#{id}"
+  end
+
+  def list resource, options = Hash.new
+    resource = resource.pluralize
+    response = @swivel.call "/rest/#{resource}", options
+  end
+
+  def upload name, options = Hash.new
+    filename = options[:filename]
+    data_set = @swivel.upload :original_asset_name => filename,
+      :original_asset_path => filename,
+      :auto_estimate => true,
+      :data => read(filename),
+      :name => name,
+      :citation => $0,
+      :display_tags => 'swivel'
+    puts "uploaded #{data_set.id}"
+  end
+
+  def append id, options = Hash.new
+    filename = options[:filename]
+    data_set = @swivel.append :id => id,
+      :original_asset_name => filename,
+      :original_asset_path => filename,
+      :auto_estimate => true,
+      :data => read(filename)
+    puts "appended #{data_set.id}"
+  end
+
+  def replace id, options = Hash.new
+    filename = options[:filename]
+    data_set = @swivel.replace :id => id,
+      :original_asset_name => filename,
+      :original_asset_path => filename,
+      :auto_estimate => true,
+      :data => read(filename)
+    puts "replaced #{data_set.id}"
+  end
+
+  private
+    def read filename = nil
+      if filename
+        open filename, 'r' do |f|
+          f.readlines.join
+        end
+      else
+        readlines.join
+      end
+    end
+end
+
+helper = SwivelHelper.new options
+action = ARGV.shift
+resource = ARGV.shift
+id = ARGV.shift
+
+case action.downcase
+when 'list'
+  helper.list resource, options
+when 'show'
+  helper.show resource, id
+when 'upload'
+  name = resource
+  helper.upload name, options
+when 'append', 'replace'
+  id = resource
+  helper.send action.to_sym, id, options
+else
+  puts "#{action} not supported"
+  exit
+end

data/lib/swivel.rb

@@ -0,0 +1,464 @@
+require 'rubygems'
+require 'active_support' # TODO: make this work w/o active_support?
+require 'base64'
+require 'cgi'
+require 'cobravsmongoose'
+require 'fileutils'
+require 'net/http'
+require 'rexml/document'
+require 'yaml'
+
+class String
+
+  # Returns true if the string looks numeric
+  #   '1283.22'.numeric? # => true
+  #   'howdy'.numeric? # => false
+
+  def numeric?
+    (self =~ /^-?\d+(\.\d+|\d*)$/) != nil
+  end
+
+  # Returns the string with '_' translated to '-'
+  #   'data_set'.dashify  # => "data-set"
+
+  def dashify
+    self.tr('_', '-')
+  end
+
+  # Returns the string with '-' translated to '_'
+  #   'data-set'.undashify  # => "data_set"
+
+  def undashify
+    self.tr('-', '_')
+  end
+
+  # Returns a string as a suitable xml tag by underscoring and dashifying.  Not
+  # perfect, but serves its purpose.
+  #   'DataSet'.to_xml_tag # => "data-set"
+
+  def to_xml_tag
+    self.underscore.dashify
+  end
+end
+
+class Hash
+
+  # Returns a query string generated from keys and values.  CGI escaped, of course.
+  #   { :name => 'huned', :year => 2007 }.to_query_string # => "name=huned&year=2007"
+
+  def to_query_string
+    keys.map do |k|
+      "#{CGI.escape k.to_s}=#{CGI.escape self[k].to_s}"
+    end.join('&')
+  end
+end
+
+#
+# =Swivel
+#
+# ==Overview
+#
+# Create a new connection to swivel.  Grabs options from ~/.swivelrc, creating
+# it if necessary.
+#
+#   swivel = Swivel::Connection.new
+#
+# Get data from Swivel
+#
+#   # show a data_set's name
+#   data_set = swivel.call '/rest/data_sets/1000001'
+#   data_set.name # => "American Longevity"
+#
+#   # list data_sets' names
+#   data_sets = swivel.call '/rest/data_sets'
+#   data_sets.collect do |data_set|
+#     data_set.name
+#   end
+#
+#   # show a data_column's name
+#   data_column = swivel.call '/rest/data_columns/1000343'
+#   data_column.name # => "Average Per Capita Income"
+#
+#   # list data_columns' names
+#   data_columns = swivel.call '/rest/data_columns'
+#   data_columns.collect do |data_column|
+#     data_column.name
+#   end
+#
+#   # show a user's name
+#   user = swivel.call '/rest/user/1000010'
+#   user.name # => "huned"
+#
+#   # list users' names
+#   users = swivel.call '/rest/users'
+#   users.collect do |user|
+#     user.name
+#   end
+#
+#   # show a graph's name
+#   graph = swivel.call '/rest/graphs/5119232'
+#   graph.name # => "Vinyl to Ipods"
+#
+#   # list graphs' names
+#   graphs = swivel.call '/rest/graphs'
+#   graphs.collect do |graph|
+#     graph.name
+#   end
+#
+# Upload data
+#
+#   # upload a new data_set
+#   data_set = swivel.upload {...}
+#
+#   # append to an existing data_set
+#   data_set = swivel.append {...}.merge(:id => orig_data_set_id, :mode => 'append')
+#
+#   # replace data for an existing data_set
+#   data_set = swivel.append {...}.merge(:id => orig_data_set_id, :mode => 'replace')
+#
+# TODO: SwQL
+#
+# TODO: constructing URLs for csvs, html pages, etc
+#
+# TODO: object cache {in memory, on filesystem}
+#
+
+module Swivel
+
+  class ApiError < StandardError; end
+
+  # Encapsulates XML that Swivel returns from an API call.  Generally, you'll
+  # never need to instantiate a Swivel::Response object.  Use one of its subclasses
+  # instead:
+  #
+  # * Swivel::List
+  # * Classes defined with metaprogrammatically (and so unseen in rdoc)
+  #   * Swivel::DataSet
+  #   * Swivel::DataColumn
+  #   * Swivel::Graph
+  #   * Swivel::User
+  #
+
+  class Response
+
+    attr_accessor :refreshed_at
+
+    # Instantiate from XML returned from Swivel.
+    def initialize xml = nil, connection = nil
+      @connection = connection
+      @xml_tag = self.class.name.split('::').last.to_xml_tag
+      @doc = REXML::Document.new xml
+      if @response = REXML::XPath.first(@doc, '/response')
+        if error = REXML::XPath.first(@doc, '/response/error')
+          message = error.attribute('message').to_s
+          code = error.attribute('code').to_s
+          raise ApiError, "#{message} (#{code})"
+        end
+        # if it's a full response, strip away the outer cruft
+        @doc = REXML::Document.new @response.elements[1].to_s
+      end
+    end
+
+    # Most of the work in processing responses from Swivel happens here.  It's
+    # pretty flexible in what it returns:
+    #
+    # * text from attributes
+    #     data_set = swivel.call '/rest/data_sets/1005309'
+    #     data_set.to_xml # => "<data-set swivel-id=\"1005309\"> ..."
+    #
+    #     # invokes method_missing
+    #     data_set.id # => 1005309
+    # * text from elements
+    #     data_set = swivel.call '/rest/data_sets/1005309'
+    #     data_set.to_xml # => "<data-set ...><name>Swivel API</name> ..."
+    #
+    #     # invokes method_missing
+    #     data_set.name # => "Swivel API"
+    # * objects that inherit from Swivel::Response (including Swivel::List)
+    #     data_set = swivel.call '/rest/data_sets/1005309'
+    #     data_set.to_xml # => "<data-set ...><user swivel-id=\"1000010\"> ..."
+    #
+    #     # invokes method_missing
+    #     data_set.user.class # => Swivel::User
+
+    def method_missing method_id
+      select_element = "/#{@xml_tag}/#{method_id.to_s.to_xml_tag}"
+      select_attribute = "/#{@xml_tag}/@#{method_id.to_s.to_xml_tag}"
+      select_list = "/#{@xml_tag}/list[@resource=\"#{method_id.to_s.singularize.to_xml_tag}\"]"
+
+      if el = REXML::XPath.first(@doc, select_element)
+        if el.attribute('swivel-id')
+          Response.class_for(el.name).new(el.to_s, @connection)
+        elsif el.has_elements?
+          CobraVsMongoose.xml_to_hash el.to_s
+        else
+          value_for el.text
+        end
+      elsif el = REXML::XPath.first(@doc, select_attribute)
+        value_for el.to_s
+      elsif el = REXML::XPath.first(@doc, select_list)
+        Swivel::List.new el.to_s, @connection
+      else
+        raise NoMethodError, "#{method_id} isn't a method of #{self.class.name}"
+      end
+    rescue Exception => e
+      if @retried || @refreshed_at
+        raise e
+      else
+        @retried = true
+        refresh! true
+        retry
+      end
+    end
+
+    # Returns the unique id in swivel for this object.  Ids are unique
+    # for each resource.
+    #   user = swivel.call '/rest/users/1000010'
+    #   user.id # => 1000010
+    #   user.id == user.swivel_id # => true
+
+    def id
+      swivel_id
+    end
+
+    # Refreshes the object's content from Swivel.
+    #
+    #   data_set = swivel.call '/rest/data_sets/1005309'
+    #   user = data_set.user
+    #   user.refresh! # populate the object fully from Swivel
+
+    def refresh! force = false
+      if @connection && (force || @refreshed_at.blank?)
+        refreshed = @connection.call "/rest/#{@xml_tag.undashify}s/#{id}"
+        if refreshed.is_a? self.class
+          @doc = REXML::Document.new refreshed.to_xml
+          @refreshed_at = Time.now
+        end
+      end
+      self
+    end
+
+    # Returns the underlying XML string for this object as a string.
+    #   user = swivel.call '/rest/users/1000010'
+    #   puts user.to_xml
+
+    def to_xml
+      @doc.to_s
+    end
+
+    protected
+      # Return an appropriate Swivel::Response subclass for the given resource.
+      #   Swivel::Response.class_for 'data-set' # => Swivel::DataSet
+      #   Swivel::Response.class_for 'data_set' # => Swivel::DataSet
+      #   Swivel::Response.class_for 'list' # => Swivel::List
+
+      def self.class_for resource
+        "Swivel::#{resource.undashify.classify}".constantize
+      rescue
+        nil
+      end
+
+      def value_for s #:nordoc:
+        s.numeric? ? s.to_i : s
+      end
+  end
+
+  %w/DataColumn DataSet Graph User/.each do |class_name|
+    class_eval <<-LAZY
+      class #{class_name} < Response; end
+    LAZY
+  end
+
+  # Encapsulates lists of resources.  Typically, items contained within the list are
+  # subclasses of Swivel::Response.
+  #
+  #   data_sets = swivel.call '/rest/data_sets'
+  #   data_sets.class # => Swivel::List
+  #   data_sets.collect do |d| d.class end # => [Swivel::DataSet, Swivel::DataSet, ...]
+  #
+  #   users = swivel.call '/rest/users'
+  #   users.class # => Swivel::List
+  #   users.collect do |u| u.class end # => [Swivel::User, Swivel::User, ...]
+
+  class List < Response
+ 
+    # Instantiate a new Swivel::List.  Calls super, then does a bit more extra processing.
+    def initialize *args
+      super *args
+      unless @processed
+        @list = Array.new
+        resource = @doc.elements[1].attributes['resource']
+        selector = "/list/#{resource}"
+        REXML::XPath.each @doc, selector do |e|
+          @list << Response.class_for(resource).new(e.to_s, @connection)
+        end
+        @processed = true
+      end
+    end
+
+    def refresh!
+      self # don't call refresh! on a list
+    end
+
+    # Delegates methods to the underlying Array instance.  Allows you to
+    # call Array methods on a Swivel::List.
+    #
+    #   data_sets = swivel.call '/rest/data_sets'
+    #   # try some Array methods...
+    #   data_sets.length.is_a? Integer # => true
+    #   data_sets.first.is_a? Swivel::DataSet #=> true
+
+    def method_missing method_id, *args, &block
+      @list.send method_id, *args, &block
+    end
+  end
+
+  class Connection
+
+    # Encapsulates ~/.swivelrc configuration files.  swivelrc files are just yaml text,
+    # so you're encouraged to manually edit.
+    #
+    # Load a ~/.swivelrc configuration, creating a default one if it doesn't exist.
+    #   config = Swivel::Config.new
+    #
+    # Load configuration from a different file
+    #   config.load 'different_configuration.yml'
+    #
+    # Save configuration to file
+    #   config.save
+    #
+
+    class Config
+      CONFIG_DIR = ENV['HOME']
+      CONFIG_FILE = '.swivelrc'
+      DEFAULT_CONFIG = { :api_key => '', :protocol => 'http://',
+        :host => 'api.swivel.com', :port => 80,
+        :timeout_up => 200, :timeout_down => 100 }
+
+      attr_accessor :config
+
+      # Returns the hash that stores the configuration settings.
+      def config
+        @config ||= self.load
+      end
+
+      # Loads a configuration, which is then accessible through config.
+      def load filename = nil
+        filename ||= CONFIG_DIR + '/' + CONFIG_FILE
+        @filename = filename
+        dir = File.dirname @filename
+        FileUtils::mkdir_p dir unless File.exist? dir
+        @config =
+          unless File.exist? @filename
+            DEFAULT_CONFIG
+          else
+            YAML::load_file @filename
+          end
+      end
+
+      # Saves a configuration to the same file from which it was loaded.
+      def save
+        open @filename, 'w+' do |f|
+          YAML::dump @config, f
+        end
+      end
+    end
+
+    attr_accessor :config
+
+    # Instantiate a connection to Swivel.  Use the connection to query or upload,
+    # append, or replace data.  Passed in options will take precedence over values
+    # set in ~/.swivelrc.
+
+    def initialize options = Hash.new
+      @config = Config.new.config
+      @config.keys.each do |key|
+        @config[key] = options[key] if options.has_key? key
+      end
+      @headers = options[:headers] || Hash.new
+      @headers.merge! 'Accept' => 'application/xml'
+      if @config.has_key?(:api_key) && !@config[:api_key].blank?
+        encoded = Base64.encode64(':' + @config[:api_key])
+        @headers.merge! 'Authorization' => "Basic #{encoded}"
+      end
+    end
+
+    # Call Swivel's REST endpoint.  This method actually performs the HTTP stuff
+    # that you need. and returns objects constructed from the returned XML.  If an
+    # appropriate class is not available, just returns the XML string.
+    #
+    #   # returns an object that's a subclass of Swivel::Response
+    #   user = swivel.call '/rest/users/1000010'
+    #   user.class # => Swivel::User
+    #
+    #   users = swivel.call '/rest/users'
+    #   users.class # => Swivel::List
+    #
+    #   # returns a string (because an appropriate Swivel::Response subclass doesn't exist)
+    #   echo = swivel.call '/rest/test/echo/howdy'
+    #   echo.class # => String
+
+    def call path, params = Hash.new, method = :get
+      xml =
+        Net::HTTP.start @config[:host], @config[:port] do |http|
+          request = "Net::HTTP::#{method.to_s.camelize}".constantize.new path, @headers
+          if [:delete, :post, :put].include? method
+            http.read_timeout = @config[:timeout_up]
+            http.request request, params.to_query_string
+          else
+            http.read_timeout = @config[:timeout_down]
+            http.request request
+          end
+        end.body
+      doc = REXML::Document.new xml
+      Response.class_for(doc.root.elements[1].name).new xml, self
+    rescue Exception => e
+      xml || nil
+    end
+
+    # Performs an upload, append, or replace.  Set options[:mode] to one of "initial",
+    # "append", or "replace".  If unset, options[:mode] defaults to "initial".  Append
+    # and replace can also be called directly, without setting options[:mode].
+    #
+    # In order to append or replace a data_set, you must be the owner of the data.
+    # The new data must conform to the same column structure as the original data.
+    #
+    # In order to upload (including replace and append), you must have a valid api key.
+    #
+    # TODO: outline required and optional parameters.  give a few examples.
+    #
+    # TODO: elaborate on requirements/assumptions for replace and append modes.
+    #
+    # TODO: limitations and crap?
+    #
+    #   # upload a file to swivel
+    #   data_set = swivel.upload {...}
+    #
+    #   # append to a data_set already in Swivel
+    #   data_set = swivel.append {...}
+    #
+    #   # replace underlying data in a data_set that already exists on Swivel
+    #   data_set = swivel.replace {...}
+
+    def upload options = Hash.new
+      options[:mode] ||= 'initial'
+      uri, method =
+        case options[:mode]
+        when 'append', 'replace'
+          ["/rest/data_sets/#{options[:id]}", :put]
+        else
+          ['/rest/data_sets', :post]
+        end
+      call uri, options, method
+    end
+
+    %w/append replace/.each do |mode|
+      class_eval <<-LAZY
+        def #{mode} options = Hash.new
+          options[:mode] = "#{mode}"
+          upload options
+        end
+      LAZY
+    end
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.2
+specification_version: 1
+name: swivel
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+date: 2007-06-15 00:00:00 -07:00
+summary: Ruby interface to the Swivel API.
+require_paths: 
+- lib
+email: huned@swivel.com
+homepage: http://swivel.com/developer
+rubyforge_project: 
+description: This gem installs client library for accessing Swivel through it's API.
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- huned
+files: 
+- COPYING
+- README
+- Rakefile
+- lib/swivel.rb
+- bin/swivel
+- CHANGELOG
+test_files: []
+
+rdoc_options: 
+- --line-numbers
+- --title
+- swivel.rb
+- --main
+- README
+- --inline-source
+extra_rdoc_files: 
+- README
+- CHANGELOG
+- COPYING
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+