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

swivel 0.0.103 → 0.0.146

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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