RubyGems - swivel - Versions diffs - 0.0.103 → 0.0.146 - Mend

swivel 0.0.103 → 0.0.146

Files changed (6) hide show

data/README +126 -256
data/Rakefile +5 -5
data/bin/swivel +108 -96
data/lib/swivel.rb +204 -69
data/lib/swivel2.rb +11 -0
metadata +6 -4

data/README CHANGED Viewed

@@ -1,336 +1,206 @@
-= swivel.rb
+= swivel2.rb
-Without fancy screencast software, I'm content with this:
+swivel2.rb is a small library that lets you interface with Swivel's REST API.
+We've only run the Swivel gem on Linux and OSX platforms, though it may work on
+others.
-     #####   #     #  ###  #     #  #######  #               ######   ######
-    #     #  #  #  #   #   #     #  #        #               #     #  #     #
-    #        #  #  #   #   #     #  #        #               #     #  #     #
-     #####   #  #  #   #   #     #  #####    #               ######   ######
-          #  #  #  #   #    #   #   #        #         ###   #   #    #     #
-    #     #  #  #  #   #     # #    #        #         ###   #    #   #     #
-     #####    ## ##   ###     #     #######  #######   ###   #     #  ######
+You can always find the latest documentation for the Swivel API online at https://inviteonly.swivel.com/developer
-(bam!)
+== The Swivel API
-swivel.rb is a smallish bit that lets you interface with Swivel's REST API.
+The Swivel API is RESTful.  At this time, you can perform CRUD operations on
+data_set resources, which allows you to get your data into Swivel and keep
+it updated.  You can also retrieve your data as CSV.
-== The REST API
+    -----------    -----------             ------------
+    HTTP Method    URI                     Description
+    -----------    -----------             ------------
-The Swivel API is mostly RESTful.  You can read and write many kinds of
-resources.  Here's the list.
+    POST           /data_sets              Create a new data set (upload data)
+    DELETE         /data_sets/#{id}        Delete data set #{id}
+    GET            /data_sets              List data sets
+    GET            /users/huned/data_sets  List huned's data sets
+    GET            /data_sets/#{id}        Show data_set #{id}
+    PUT            /data_sets/#{id}        Update data_set #{id}
-    ------    -----------                ------------
-    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}
+Most method calls take parameters.  Check out the
+{Swivel API Documentation}[https://inviteonly.swivel.com/developer] for the most up to date documentation.  More REST resources will become available as the Swivel API matures.
-    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}
+== Installing
-    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}
+    $ sudo gem install -y swivel
+    Successfully installed swivel, version 0.0.103
+    Installing ri documentation for swivel-0.0.103...
+    Installing RDoc documentation for swivel-0.0.103...
-    users
-    get       /rest/users                list users
-    get       /rest/users/#{id}          show user #{id}
-    put       /rest/users/#{id}          update user #{id}
+== You need an API key
-    (non-RESTful methods)
-    get       /rest/test/echo/#{text}    echo some text
-    get       /rest/search               search for stuff
+You need an API key to perform any POST, PUT, or DELETE requests.  You must also use an API key to perform a GET request to access your private or shared data.  Get your API key from https://inviteonly.swivel.com/developer.  Please treat your API key as you would a password.
-Most method calls take parameters.  Check out the
-{Swivel API Explorer}[http://swivel.com/api/list] to try calls interactively.
-Also, check out some {sample code}[http://swivel.com/api/code].
+Your API key is stored in ~/.swivelrc along with some other information.  Copy the swivelrc.default provided with this gem to ~/.swivelrc and modify site parameter to include your API key.  Please make sure you set appropriate permissions on your ~/.swivelrc file to prevent others from seeing your API key.
-== Make it go go racer
+An example ~/.swivelrc:
-    $ 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...
+    $ cat ~/.swivelrc
+    --- !ruby/struct:Swivel2::Config
+    site: http://x:<YOUR API KEY>@api.swivel.com
+    timeout_read: 500
+    timeout_write: 1_000
+    extra_params: { noviews: true }
-    $ 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
+TODO: describe what each parameter means.
-== Class hierarchy
+== Examples
-  * Swivel::Connection
-  * Swivel::Connection::Config
-  * Swivel::Response
-    * Swivel::DataColumn
-    * Swivel::DataSet
-    * Swivel::Graph
-    * Swivel::User
-    * Swivel::List
-  * Swivel::ApiError
+=== Basic set up
-== RTF!M
+Before you can use this library, you need to know a bit about the Config and
+Connection classes.  After you set up your ~/.swivelrc, you can run these
+examples through irb.
-Never fear, it's installed when you install the gem.
-    $ ri Swivel
-Other nice ones:
+    $ irb
+    >> require 'swivel2'
+    => true
-    $ ri Swivel::Connection
-    $ ri Swivel::Response
+A Config instance encapsulates important settings stored in your ~/.swivelrc
+file.
-== Examples.  Worth a thousand words
+    >> config = Swivel2::Config.load '/home/huned/.swivelrc'
+    => #<struct Swivel2::Config ...>
-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.
+A Connection instance is your main interface to Swivel's API.  Construct a Connection instance by passing a Config instance into the constructor.
-    # writes your api key into ~/.swivelrc
-    swivel -k <your api key>
+    >> connection = Swivel2::Connection.new config
+    => #<Swivel2::Connection:0xb7b34a54 ...>
-(Did you notice you got a `swivel` at your command line?  Sneaky!  It's part of the
-gem.  And it can query or pipe data into Swivel from your terminal!)
+The Connection class defines post, get, put, and delete methods that you can
+call with paths to REST resources.  These methods automatically send your API
+key with each request.  For example:
-Now, back to it.  Ready, set, go!
+    >> data_sets = connection.get '/data_sets'
-    $ irb
-    >> require 'swivel'
-    => true
+=== Data sets
-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.
+==== Show a data set
-    >> 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"}
+You can show a data set's XML by making a get call to its resource path:
-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.
+    >> data_set = connection.get '/data_sets/1234567'
+    => #<Swivel2::Response::DataSet:0xb79fd244 ...>
-    # 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>
+You don't need to go through the Swivel gem to get a data set's csv.  It's
+simply a GET:
-But, back to objects.  Swivel::Connection#call often returns objects that
-encapsulate the XML response that the Swivel API sent.
+    GET http://api.swivel.com/data_sets/1234567.csv?api_key=<YOUR API KEY>
-    >> 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 ....
+When getting the CSV, you can optionally specify +limit+ and +offset+
+parameters.
-These objects are rich and meaty.  You can poke them and they shall respond,
-surlily.
+==== List data sets
-    >> data_set.id
-    => 1000000
-    >> data_set.user.name
-    => "huned"
-    >> data_set.data_columns[3].name
-    => "by-nc-nd-2.0"
+    >> data_sets = connection.get '/data_sets'
-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:
+You can also list data sets for a specific user.  For example, to list huned's
+data sets:
-    # 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..?
+    >> data_sets = connection.get '/users/huned/data_sets'
-So how do you know what to call?  At this time, the best way is to inspect
-the inner power-juice, the XML.
+When you list data sets, you can optionally provide +limit+ and +offset+
+parameters to page through the results.  For example, to list data sets 11
+through 20:
-    >> 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>
+    >> data_sets = connection.get '/data_sets', :limit => 10, :offset => 10
-== Constructing URLs
+==== Uploading new data
-Constructing URLs are free and easy!  (Freeasy... mmm!)
+You just need a CSV and a name for your data set before you can upload it.
+Without specifying any other options, Swivel will try to figure out the column
+structure and types automatically.
-Any object in Swivel has a corresponding page that you can view with your
-browser.
+    >> params = {'file[data]' => `cat ~/data.csv`, 'data_set[name]' => 'My Data'}
+    >> data_set = connection.post '/data_sets', params
+    => #<Swivel2::Response::DataSet:0xb7e0051c ...>
-    # 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"
+See the {full list of options}[https://inviteonly.swivel.com/api/data_sets] that you can use for POST and PUT to /data_sets.
-    # copy/paste this url into your browser
-    url = "http://swivel.com/#{resource}s/show/#{id}"
+==== Updating an existing data set's attributes
-Graphs have pages, but if you want to grab the actual graph image, here's how:
+    >> params = {'data_set[name]' => 'new name'}
+    >> data_set = connection.put '/data_sets/1234567', params
+    => #<Swivel2::Response::DataSet:0xb7e0051c ...>
-    # as before, we get the id and resource type
-    id = data_set.id
-    resource = data_set.class.name.split('::').last.underscore # => "data_set"
+See the {full list of options}[https://inviteonly.swivel.com/api/data_sets] that you can use for POST and PUT to /data_sets.
-    url = "http://swivel.com/#{resource}s/image/share/#{width}/#{height}"
+==== Appending more data to an existing data set
-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.
+    >> params = {'file[mode]' => 'append', 'file[data]' => `cat ~/more_data.csv`}
+    >> data_set = connection.put '/data_sets/1234567', params
+    => #<Swivel2::Response::DataSet:0xb7e0051c ...>
-    url = "http://swivel.com/#{resource}s/image/share/#{width}/#{height}/#{limit}/#{scale}/#{graph_type}/#{order_by_direction}/#{time_range}/#{time_scale}/#{aggregation_function}"
+See the {full list of options}[https://inviteonly.swivel.com/api/data_sets] that you can use for POST and PUT to /data_sets.  Caveat:  Your new data must have the same column structure as the original data.
-TODO: explain it in this here table
+==== Replacing data for an existing data set
-    * width
-    * height
-    * limit
-    * scale
-    * graph_type
-    * order_by_direction
-    * time_range
-    * time_scale
-    * aggregation_function
+    >> params = {'file[mode]' => 'replace', 'file[data]' => `cat ~/new_data.csv`}
+    >> data_set = connection.put '/data_sets/1234567', params
+    => #<Swivel2::Response::DataSet:0xb7e0051c ...>
-== Uploading Data
+See the {full list of options}[https://inviteonly.swivel.com/api/data_sets] that you can use for POST and PUT to /data_sets.  Caveat:  Your new data must have the same column structure as the original data.
-  See Swivel::Connection#upload
+==== Deleting a data set
-== Create Graphs
+    >> data_set = connection.delete '/data_sets/1234567'
+    => #<Swivel2::Response::DataSet:0xb7e0051c ...>
-  TODO
+== Quickest way to upload?  The Swivel command line tool
-== Something completely different: A tryst at the command line
+The Swivel command line tool the quickest way to get your data into Swivel and
+keep it updated if you have basic Unix and shell scripting knowledge.
+Installing the Swivel gem also installs a command line tool, /usr/bin/swivel,
+that you can use to upload and update data sets without writing a single line
+of ruby code.
-The command line program lets you query Swivel or upload data into Swivel.
-You get this program when you install the Swivel gem.
+Before using this tool, please set up your ~/.swivelrc as described at the
+beginning of this documentation.
     $ 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}[http://swivel.com/api/key].)
-    $ cat ~/.swivelrc
-    ---
-    protocol: http://
-    timeout_up: 200
-    api_key: ""
-    timeout_down: 100
-    host: api.swivel.com
-    port: 80
+Aside from being useful on its own, the command line tool is also a nice
+example of how to write ruby code that uses this gem.
-So how about uploading data?
+=== Uploading new data
-    $ swivel upload "my awesome data" -f data.csv
-    uploaded data_set 1000234
+    $ cat data.csv | /usr/bin/swivel upload "my data"
+    uploaded 1234567
-Then your dataset magickally appears online at:
+=== Appending more data to an existing data set
-    http://swivel.com/data_sets/show/1000234
+    $ cat more_data.csv | /usr/bin/swivel append 1234567
+    appended 1234567
-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 (|).
+Caveat:  Your new data must have the same column structure as the original data.
-    $ cat data.csv | swivel upload "my awesome data"
-    uploaded data_set 1000234
+=== Replacing data for an existing data set
-If you want to append to a data_set you previously uploaded:
+    $ cat more_data.csv | /usr/bin/swivel replace 1234567
+    replaced 1234567
-    $ cat more_data.csv | swivel append 1000234
-    appended data_set 1000234
+Caveat:  Your new data must have the same column structure as the original data.
-And finally, if you want to replace the entire data set with some other,
-fancier data:
+== More options
-    $ cat fancier_data.csv | swivel replace 1000234
-    replaced data_set 1000234
+    $ /usr/bin/swivel --help
-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 mailto:developer@swivel.com.
-You can rcov swivel.rb by running this from the top level directory:
-    $ rcov -Ilib -t test/test_swivel.rb
-== Respek
+You can rcov this code by running rcov from the top level directory:
-Respeks to _why, errtheblog, 37signals, our moms, and of course the community.
-Wanna write code with us?  {We're hiring!}[http://swivel.com/about/jobs]
+    $ rcov -Ilib -t test/*_test.rb
 == License
-This software is licensed under the exact same license as Ruby itself.  Peace
-out.
+This software is licensed under the exact same license as Ruby itself.

data/Rakefile CHANGED Viewed

@@ -14,7 +14,7 @@ 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']
+RDOC_OPTS = ['--line-numbers', '--title', 'swivel2.rb', '--main', 'README', '--inline-source']
 desc "Does a full compile, test run"
 task :default => [:package, :test, :rdoc]
@@ -28,7 +28,7 @@ task :release => [:package]
 desc "Run all the tests"
 Rake::TestTask.new do |t|
   t.libs << "test"
-  t.test_files = FileList['test/test_*.rb']
+  t.test_files = FileList['test/*_test.rb']
   t.verbose = true
 end
@@ -36,7 +36,7 @@ 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']
+  rdoc.rdoc_files.add ['README', 'CHANGELOG', 'COPYING', 'lib/swivel2.rb', 'lib/swivel2/*.rb']
 end
 spec =
@@ -54,13 +54,13 @@ spec =
     s.author = 'huned'
     s.email = 'huned@swivel.com'
-    s.homepage = 'http://swivel.com/developer'
+    s.homepage = 'http://www.swivel.com/developer'
     s.files = %w/COPYING README Rakefile/ + Dir['{lib,bin}/*']
     s.require_path = "lib"
     s.bindir = "bin"
-    s.executables = ['swivel']
+    s.executables = %w/swivel/
     s.add_dependency 'activesupport'
     s.add_dependency 'cobravsmongoose'

data/bin/swivel CHANGED Viewed

@@ -1,81 +1,110 @@
 #!/usr/bin/env ruby
 require 'rubygems'
-require 'active_support' # TODO: make it work w/o this
+require 'open-uri'
+require 'active_support'
 require 'optparse'
-require 'yaml'
-require File.dirname(__FILE__) + '/../lib/swivel'
+require File.dirname(__FILE__) + '/../lib/swivel2'
+COLUMN_TYPE_HELP = <<-EOS
+Valid types:
+currency: Currency values, including the
+          currency symbol.
+date:     Date values that don't include
+          timestamps.
+datetime: Date and time values.
+float:    Floating point values.  Swivel
+          groks scientific notation!
+integer:  Integer values.
+ignore:   Columns of this type will not
+          be uploaded.
+percent:  Percent values without the "%"
+          symbol.  A value of 0.03 will
+          appear as 3% in Swivel.
+string:   String values.
+EOS
+SWIVELRC = <<-EOS
+Your API key is read from ~/.swivelrc:
+    You need a ~/.swivelrc file before you can use this program!  The contents
+    of your swivelrc file should look like this:
+    --- !ruby/struct:Swivel2::Config
+    site: https://x:<YOUR_API_KEY>@api.swivel.com
+    timeout_read: 500
+    timeout_write: 1_000
+    extra_params: { noviews: true }
+EOS
+EXAMPLES = <<-EOS
+Examples:
+    Upload a data set
+    $ cat data.csv | #{$0} upload 1234567
+    Append data to data set with id 1234567
+    $ cat more_data.csv | #{$0} append 1234567
+    Replace underlying data for data set with id 1234567
+    $ cat new_data.csv | #{$0} replace 1234567
+EOS
 options = Hash.new
-config = Swivel::Connection::Config.new
-config.load
-config.save
+config = Swivel2::Config.load
 ARGV.options do |opts|
-  opts.banner = 'Usage: swivel < list, show, upload, append, replace > [options]'
+  opts.banner = 'Usage: swivel <upload, append, replace> [options]'
   opts.separator ''
   opts.separator 'Options:'
-  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|
+  opts.on '-f', '--file=<file>', String,
+    'File to upload, append, or replace.',
+    'Your actual data is read from this file.',
+    'If omitted, data is read from STDIN.',
+    'OPTIONAL' do |v|
       options[:filename] = v
     end
-  opts.on '-n', '--column-names=column_names', String,
-    "Column names." do |v|
-    options[:column_names] = v
-  end
+  opts.separator ''
-  opts.on '-t', '--column-types=column_types', String,
-    "Column types specification.  Choose from {number, currency, date, percent, text}." do |v|
-      options[:column_types] =
-        v.split(',').collect do |type|
-          case type
-          when /^n/i
-            'NumberDataColumnType'
-          when /^w/i
-            'WholeNumberDataColumnType'
-          when /^c/i
-            'CurrencyDataColumnType'
-          when /^t/i
-            'DateTimeDataColumnType'
-          when /^d/i
-            'DateDataColumnType'
-          when /^p/i
-            'PercentageDataColumnType'
-          else
-            'TextDataColumnType'
-          end
-        end.join ','
-  end
+  opts.on '-c', '--headings=<headings>', String,
+    'Column headings as a comma separated list.',
+    'Example: "Year,Revenue"',
+    'OPTIONAL' do |v|
+      options[:headings] = 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
+  opts.separator ''
+  opts.on *['-t', '--types=<types>', String,
+    'Column types as a comma separated list.',
+    'Example: "date,currency"',
+    COLUMN_TYPE_HELP.split("\n"),
+    'OPTIONAL'].flatten do |v|
+      options[:types] = v
     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
+  opts.separator ''
+  opts.on '-s', '--sep=<separator>', String,
+    'Column separator.',
+    'Example: "," or "\t"',
+    'OPTIONAL' do |v|
+      options[:sep] = v
     end
+  opts.separator ''
   opts.on_tail '-?', '--help',
-    "Show this help message." do puts opts; exit end
+    "Show this help message." do
+      puts opts
+      exit
+    end
   opts.parse!
@@ -86,77 +115,60 @@ ARGV.options do |opts|
 end
 class SwivelHelper
-  def initialize options = Hash.new
-    @swivel = Swivel::Connection.new options
-  end
-  def show resource, id
-    resource = resource.pluralize
-    response = @swivel.call "/#{resource}/#{id}"
-  end
-  def list resource, options = Hash.new
-    resource = resource.pluralize
-    response = @swivel.call "/#{resource}", options
+  def initialize config
+    @swivel = Swivel2::Connection.new config
   end
   def upload name, options = Hash.new
-    filename = options[:filename]
-    opts = {:original_asset_name => filename, :original_asset_path => filename,
-      :name => name, :citation => $0, :display_tags => 'swivel'}
-    opts.merge! column_types(options)
-    data_set = @swivel.upload! opts.merge(:data => read(filename))
+    opts = { 'data_set[name]' => name,
+      'data_set[citation]' => $0,
+      'data_set[public]' => 0,
+      'file[data]' => read(options[:filename]) }
+    opts.merge! 'file[types]' => options[:types] if options[:types]
+    opts.merge! 'file[headings]' => options[:headings] if options[:headings]
+    opts.merge! 'file[sep]' => options[:sep] if options[:sep]
+    data_set = @swivel.post '/data_sets', opts
     puts "uploaded #{data_set.id}"
   end
   def append id, options = Hash.new
-    opts = {:id => id}.merge column_types(options)
-    data_set = @swivel.append! opts.merge(:data => read(options[:filename]))
+    opts = { 'file[mode]' => 'append',
+      'file[data]' => read(options[:filename]) }
+    data_set = update id, opts
     puts "appended #{data_set.id}"
   end
   def replace id, options = Hash.new
-    opts = {:id => id}.merge column_types(options)
-    data_set = @swivel.replace! opts.merge(:data => read(options[:filename]))
+    opts = { 'file[mode]' => 'replace',
+      'file[data]' => read(options[:filename]) }
+    data_set = update id, opts
     puts "replaced #{data_set.id}"
   end
   private
+    def update id, options
+      @swivel.put "/data_sets/#{id}", options
+    end
     def read filename = nil
       if filename
-        open filename, 'r' do |f|
-          f.readlines.join
-        end
+        open filename do |f| f.readlines.join end
       else
         readlines.join
       end
     end
-    def column_types options
-      if options[:column_types].blank?
-        {:auto_estimate => true}
-      else
-        {:column_types => options[:column_types],
-         :column_names => options[:column_names],
-         :column_separator => options[:column_separator] || ','}
-      end
-    end
 end
-helper = SwivelHelper.new options
+helper = SwivelHelper.new config
 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'
+when /upload/i
   name = resource
   helper.upload name, options
-when 'append', 'replace'
+when /append/i, /replace/i
   id = resource
   helper.send action.to_sym, id, options
 else

data/lib/swivel.rb CHANGED Viewed

@@ -11,7 +11,8 @@ require 'yaml'
 class Time
   silence_warnings do
-  RFC822_DATETIME_REGEX = /\w{3}, \d{2} \w{3} \d{4} \d{2}:\d{2}:\d{2} [+-]\d{4}/
+  RFC822_DATETIME_REGEX = /\A\w{3}, \d{2} \w{3} \d{4} \d{2}:\d{2}:\d{2} [+-]\d{4}\Z/
+  XML_DATETIME_REGEX = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}[+\-]\d{2}:\d{2}\Z/
   end
 end
@@ -134,22 +135,22 @@ module Swivel
   class Response
-    attr_accessor :refreshed_at, :disable_auto_refresh
+    attr_accessor :refreshed_at, :disable_auto_refresh, :hash_doc
     def self.resource
       nil
     end
     # Instantiate from XML returned from Swivel.
-    def initialize xml = nil, connection = nil
+    def initialize xml, connection, hashdoc
+      raise 'invalid arguments, either xml or hashdoc needs to be passed in' if hashdoc.nil? && xml.nil?
       @connection = connection
       @disable_auto_refresh = @connection && @connection.disable_auto_refresh
       @xml_tag = self.class.name.demodulize.to_xml_tag
-      @doc = REXML::Document.new xml
-      if @response = REXML::XPath.first(@doc, '/response')
-        # if it's a full response, strip away the outer cruft
-        @doc = REXML::Document.new @response.elements[1].to_s
-      end
+      @hash_doc = hashdoc
+      @hash_doc ||= CobraVsMongoose.xml_to_hash xml
+      @hash_doc = @hash_doc['response'] if @hash_doc.is_a?(Hash) && @hash_doc['response']
+      @hash_doc = @hash_doc[self.class.resource] if @hash_doc.is_a?(Hash) && @hash_doc[self.class.resource]
     end
     # Most of the work in processing responses from Swivel happens here.  It's
@@ -175,24 +176,55 @@ module Swivel
     #     data_set.user.class # => Swivel::User
     def method_missing method_id
-      select_element = "/#{self.class.resource ? self.class.resource : @xml_tag}/#{method_id.to_s.to_xml_tag}"
-      select_attribute = "/#{self.class.resource ? self.class.resource : @xml_tag}/@#{method_id.to_s.to_xml_tag}"
-      select_list = "/#{self.class.resource ? self.class.resource : @xml_tag}/list[@resource=\"#{method_id.to_s.singularize.to_xml_tag}\"]"
+      method_name = method_id.to_s.singularize.to_xml_tag
+      list_name = method_id.to_s.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
+      # 1)look in attributes
+      # 2)look in elements
+      #   2a) if value return it
+      #   2b) if hash return an obj
+      #   2c) if method_name.pluralize, return a list
+      # 3)look in lists
+      if @hash_doc["@#{method_name}"]
+        value_for @hash_doc["@#{method_name}"]
+      elsif @hash_doc[method_name]
+        if @hash_doc[method_name].is_a? Hash
+          if @hash_doc[method_name].has_key?('$')
+            value_for @hash_doc[method_name]['$']
+          elsif @hash_doc[method_name].size == 1 and @hash_doc[method_name].has_key? '@type'
+            nil
+          elsif @hash_doc[method_name].blank?
+            nil
+          else
+            Response.class_for(method_name).new(nil, @connection, @hash_doc[method_name])
+          end
         else
-          value_for el.text
+          value_for @hash_doc[method_name]
         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
+      # 2c) from above - enables rails ActiveRecord::Base#to_xml style lists
+      elsif @hash_doc[list_name].is_a? Hash and
+          @hash_doc[list_name]['@type'] == 'array'
+        member_name = (@hash_doc[list_name].keys.find{|k| !/^@/.match(k) } || list_name.singularize)
+        list = (@hash_doc[list_name][member_name] rescue [])
+        list = [list] unless list.is_a?(Array)
+        # hack to get the gem to parse all array types correctly
+        hack_list = list.map{|i| {member_name => i}}
+        Swivel::List.new nil, @connection, hack_list, member_name, list.size, list.size
+      elsif @hash_doc['list'] && @hash_doc['list'].is_a?(Hash) && @hash_doc['list']['@resource'] == method_name
+        Swivel::List.new nil, @connection, (@hash_doc['list'][method_name].nil? ? [] : @hash_doc['list'][method_name]), method_name, @hash_doc['list']['@count'], @hash_doc['list']['@total']
+      elsif @hash_doc['list'] && @hash_doc['list'].is_a?(Array) && @hash_doc['list'].any?{|h| h['@resource'] == method_name}
+        list_el = @hash_doc['list'].select{|h| h['@resource'] == method_name}.first
+        Swivel::List.new nil, @connection,(list_el[method_name].nil? ? [] : list_el[method_name]), method_name, list_el['@count'], list_el['@total']
+      elsif @hash_doc[method_name.pluralize]
+        if @hash_doc[method_name.pluralize].has_key?('$')
+          value_for @hash_doc[method_name.pluralize]['$']
+        else
+          @hash_doc[method_name.pluralize]
+        end
+      else
         raise NoMethodError, "#{method_id} isn't a method of #{self.class.name}"
       end
     rescue Exception => e
@@ -200,7 +232,7 @@ module Swivel
         nil
       else
         @retried = true
-        refresh! true
+#        refresh! true
         retry
       end
     end
@@ -223,7 +255,7 @@ module Swivel
     #   user.id == user.swivel_id # => true
     def id
-      swivel_id
+      method_missing(:id) or swivel_id
     end
     # Same as id method, added to make Swivel objects play well with url_for
@@ -239,16 +271,16 @@ module Swivel
     #   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 "/#{@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
+#    def refresh! force = false
+#      if @connection && (force || @refreshed_at.blank?)
+#        refreshed = @connection.call "/#{@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 '/users/1000010'
@@ -283,8 +315,13 @@ module Swivel
       end
       def value_for s #:nordoc:
-        if s.match Time::RFC822_DATETIME_REGEX
-          Time.parse s
+        if s.match Time::RFC822_DATETIME_REGEX or
+          s.match Time::XML_DATETIME_REGEX
+          begin
+            Time.parse s
+          rescue ArgumentError => e
+            DateTime.parse s
+          end
         elsif s.numeric?
           s.to_i
         else
@@ -293,21 +330,56 @@ module Swivel
       end
   end
-  class Annotation < Response; end
-  class Comment < Response; end
-  class Page < Response; end
-  class PageAsset < Response; end
-  class Prose < Response; end
+  class Annotation < Response
+    def self.resource
+      'annotation'
+    end
+  end
+  class Comment < Response
+    def self.resource
+      'comment'
+    end
+  end
+  class Invitation < Response
+    def self.resource
+      'invitation'
+    end
+  end
+  class Page < Response
+    def self.resource
+      'page'
+    end
+  end
+  class PageAsset < Response
+    def self.resource
+      'page-asset'
+    end
+  end
+  class Prose < Response
+    def self.resource
+      'prose'
+    end
+  end
   class Permission < Response
+    def self.resource
+      'permission'
+    end
     %w/accessor accessable/.each do |thing|
       define_method thing.to_sym do
         unless instance_variable_get "@#{thing}".to_sym
           c =
             begin
               dashified = thing.dasherize
-              o = REXML::XPath.first(@doc, "/permission/#{dashified}").elements[1]
-              Response.class_for(o.name).new o.to_s
+              if @hash_doc[dashified]
+                raise 'unexpected document, expecting only one key to be name here' if @hash_doc[dashified].keys.size != 1
+                resource = @hash_doc[dashified].keys.first
+                h = @hash_doc[dashified][resource]
+                Response.class_for(resource).new nil, @connection, h
+              else
+                nil
+              end
             rescue
               warn e
               nil
@@ -320,14 +392,24 @@ module Swivel
   end
   class Activity < Response
+    def self.resource
+      'activity'
+    end
     %w/source subject verb direct_object prepositional_object/.each do |part|
       define_method part.to_sym do
         unless instance_variable_get "@#{part}".to_sym
           c =
             begin
               dashified = part.dasherize
-              o = REXML::XPath.first(@doc, "/activity/#{dashified}").elements[1]
-              Response.class_for(o.name).new o.to_s
+              if @hash_doc[dashified]
+                raise 'unexpected document, expecting only one key to be name here' if @hash_doc[dashified].keys.size != 1
+                resource = @hash_doc[dashified].keys.first
+                h = @hash_doc[dashified][resource]
+                Response.class_for(resource).new nil, @connection, h
+              else
+                nil
+              end
             rescue
               warn e
               nil
@@ -346,6 +428,9 @@ module Swivel
     #
     #   data_set = swivel.data_set id
     #   data_set.append! :data => `/tmp/append.csv`
+    def self.resource
+      'data-set'
+    end
     def append! options = Hash.new
       options.merge! :mode => 'append', :id => self.id
@@ -380,6 +465,9 @@ module Swivel
   end
   class Visual < Response
+    def self.resource
+      'visual'
+    end
     ## Forms the url for an image.
     def image_url options={}
@@ -392,35 +480,43 @@ module Swivel
   end
   class User < Response
-    def admin?
-      admin.to_b
-    rescue
-      false
+    def self.resource
+      'user'
     end
     def to_param
       name
     end
   end
   class Group < Response
-    def members
-      @members ||=
-        begin
-          o = REXML::XPath.first(@doc, "/group/members").elements[1]
-          Response.class_for(o.name).new o.to_s
-        rescue
-          warn e
-          nil
-        end
+    def self.resource
+      'group'
     end
     def to_param
       (!slug.blank? and slug) or super.to_param
     end
+    def permission_for(member)
+      raise 'group has no permissions' unless permissions
+      perm = permissions.find do |p|
+        p.accessor_id == member.id and
+        p.accessor_type == member.class.name.sub(/^Swivel::/,'')
+      end
+      perm
+    end
+    def has_admin?(member)
+      permission = permission_for(member)
+      permission and permission.rights == ::Permission::WRITE
+    end
+    def has_member?(member)
+      !!permission_for(member)
+    end
   end
   class Graph < Response
+    def self.resource
+      'graph'
+    end
     def image_url options = Hash.new
       host, port = @connection.config[:host], @connection.config[:port]
       port = port == 80 ? '' : ":#{port}"
@@ -478,16 +574,19 @@ module Swivel
   class List < Response
+    attr_accessor :resource, :count, :total
     # Instantiate a new Swivel::List.  Calls super, then does a bit more extra processing.
-    def initialize *args
-      super *args
+    def initialize xml, connection, hashdoc, resource, count, total
+      super(xml, connection, hashdoc)
       unless @processed
+        @count = count.nil? ? 0 : count.to_i
+        @total = total.nil? ? 0 : total.to_i
         @list = Array.new
-        resource = @doc.elements[1].attributes['resource']
-        resource ||= @doc.elements[1].elements[1].name
-        selector = "/list/#{resource}"
-        REXML::XPath.each @doc, selector do |e|
-          @list << Response.class_for(resource).new(e.to_s, @connection)
+        @hash_doc ||= []
+        @hash_doc = [@hash_doc] if !@hash_doc.is_a?(Array)
+        @hash_doc.each do |h|
+          @list << Response.class_for(resource).new(nil, @connection, h)
         end
         @processed = true
       end
@@ -521,6 +620,9 @@ module Swivel
   class ApiError < StandardError; end
   class Error < Response
+    def self.resource
+      'error'
+    end
     def raise
       super ApiError, message, backtrace.split("\n")
     end
@@ -595,6 +697,10 @@ module Swivel
       @headers.merge! 'Accept' => 'application/xml'
     end
+    def inspect
+      super.sub /:api_key=>"[^"]*"/, ':api_key=>[FILTERED]'
+    end
     # Keep track of how many calls have been made.  Note that this means
     # multiple Swivel::Connection instances increment the same call count
     # if those Swivel::Connections run within the same thread.
@@ -660,11 +766,40 @@ module Swivel
       end
       @@calls << {:url => path, :time => elapsed_time}
       body = response.body
+      log "#{config[:host]}:#{config[:port]}/#{path}"
       log body
       case response.content_type
       when 'application/xml'
         doc = REXML::Document.new body
-        Response.class_for(doc.root.elements[1].name).new body, self
+        if doc.root.elements[1].name.downcase == 'list'
+          h = CobraVsMongoose.xml_to_hash body
+          h = h["response"] if h["response"]
+          resource = h['list']['@resource']
+          count = h['list']['@count']
+          total = h['list']['@total']
+          h = h['list'][resource]
+          h ||= []
+          List.new nil, self, h, resource, count, total
+        # 2c) enables rails ActiveRecord::Base#to_xml style lists (at root)
+        elsif doc.root.elements.to_a.size == 1 and
+            doc.root.elements[1].attributes['type'] == 'array'
+          h = CobraVsMongoose.xml_to_hash body
+          h = h["response"] if h["response"]
+          list_name = doc.root.elements[1].name
+          member_name = (h[list_name].keys.find{|k| !/^@/.match(k) } || list_name.singularize)
+          list = h[list_name][member_name] || []
+          list = [list] unless list.is_a?(Array)
+          total = (doc.root.attributes['total'].to_i rescue list.size)
+          # hack to get the gem to parse all array types correctly
+          hack_list = list.map{|i| {member_name => i}}
+          Swivel::List.new nil, @connection, hack_list, member_name, list.size, total
+        else
+          Response.class_for(doc.root.elements[1].name).new body, self, nil
+        end
       when 'text/csv', 'text/plain'
         body
       else

data/lib/swivel2.rb ADDED Viewed

@@ -0,0 +1,11 @@
+require 'rubygems'
+require 'active_support'
+require File.dirname(__FILE__) + '/../vendor/activesupport-2.0.2-/lib/active_support/core_ext/module/attr_accessor_with_default'
+require File.dirname(__FILE__) + '/../vendor/activesupport-2.0.2-/lib/active_support/core_ext/object/misc'
+require File.dirname(__FILE__) + '/../vendor/activeresource-2.0.2-/lib/active_resource'
+require File.dirname(__FILE__) + '/swivel2/config'
+require File.dirname(__FILE__) + '/swivel2/connection'
+require File.dirname(__FILE__) + '/swivel2/formats'
+require File.dirname(__FILE__) + '/swivel2/performance'
+require File.dirname(__FILE__) + '/swivel2/response'

metadata CHANGED Viewed

@@ -3,13 +3,13 @@ rubygems_version: 0.9.4
 specification_version: 1
 name: swivel
 version: !ruby/object:Gem::Version
-  version: 0.0.103
-date: 2007-10-18 00:00:00 -07:00
+  version: 0.0.146
+date: 2008-01-10 00:00:00 -08:00
 summary: Ruby interface to the Swivel API.
 require_paths:
 - lib
 email: huned@swivel.com
-homepage: http://swivel.com/developer
+homepage: http://www.swivel.com/developer
 rubyforge_project:
 description: This gem installs client library for accessing Swivel through it's API.
 autorequire:
@@ -32,6 +32,8 @@ files:
 - COPYING
 - README
 - Rakefile
+- lib/swivel2.rb
+- lib/swivel2
 - lib/swivel.rb
 - bin/swivel
 - CHANGELOG
@@ -40,7 +42,7 @@ test_files: []
 rdoc_options:
 - --line-numbers
 - --title
-- swivel.rb
+- swivel2.rb
 - --main
 - README
 - --inline-source