swivel 0.0.8 → 0.0.15

data/README

@@ -16,7 +16,8 @@ swivel.rb is a smallish bit that lets you interface with Swivel's REST API.
 
 == The REST API
 
-TODO: some copy
+The Swivel API is mostly RESTful.  You can read and write many kinds of
+resources.  Here's the list.
 
     ------    -----------                ------------
     method    uri                        what it does
@@ -46,9 +47,13 @@ TODO: some copy
     get       /rest/users/#{id}          show user #{id}
     put       /rest/users/#{id}          update user #{id}
 
-TODO: optional parameters for lists, etc.
-TODO: search
-TODO: echo
+    (non-RESTful methods)
+    get       /rest/test/echo/#{text}    echo some text
+    get       /rest/search               search for stuff
+
+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].
 
 == Make it go go racer
 
@@ -87,13 +92,14 @@ Never fear, it's installed when you install the gem.
 
     $ ri Swivel
 
-Another nice one:
+Other nice ones:
 
+    $ ri Swivel::Connection
     $ ri Swivel::Response
 
 == Examples.  Worth a thousand words
 
-Ready, set, ... wait.  Got an API key?  Get an API key (http://swivel.com/api/key).
+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.
@@ -101,6 +107,9 @@ It's like a password, so don't share it.
     # writes your api key into ~/.swivelrc
     swivel -k <your api key>
 
+(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!)
+
 Now, back to it.  Ready, set, go!
 
     $ irb
@@ -223,6 +232,14 @@ TODO: explain it in this here table
     * time_scale
     * aggregation_function
 
+== Uploading Data
+
+  See Swivel::Connection#upload
+
+== Create Graphs
+
+  TODO
+
 == Something completely different: A tryst at the command line
 
 The command line program lets you query Swivel or upload data into Swivel.
@@ -250,8 +267,8 @@ It uses a ~/.swivelrc file to remember settings.  If you don't have a
     -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.)
+run `swivel -k <your api key>` to update your ~/.swivelrc. (Remember: {finagle an api
+key}[http://swivel.com/api/key].)
 
     $ cat ~/.swivelrc 
     --- 
@@ -302,67 +319,18 @@ Edit by Visnu: Huned wrote this at 4am.  He tired out right here.
 
 == Feedback
 
-Feedback, comments, and (especially) patches welcome at developer@swivel.com.
+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
 
 Respeks to _why, errtheblog, 37signals, our moms, and of course the community.
-Wanna write code with us?  http://swivel.com/about/jobs
+Wanna write code with us?  {We're hiring!}[http://swivel.com/about/jobs]
 
 == License
 
 This software is licensed under the exact same license as Ruby itself.  Peace
 out.
-
-upload options
-    mode
-      initial append replace
-
-    auto_estimate
-    ordered_column_names
-    ordered_column_types
-    column_separator
-
-    original_asset_name
-    original_asset_path
-    data (or data_content)
-
-    name
-    color
-    description
-    citation
-    citation_url
-    image_url
-    image_source_url
-    display_tags
-    public_tags
-
-graph options
-    graph_type
-      BarGraph LineGraph HorizontalBarGraph PieGraph ScatterGraph
-    width
-    height
-    limit
-    image_url
-    name
-    description
-    display_tags
-    time_range
-      ???
-    time_scale
-      hourly daily weekly quarterly yearly
-    scale
-      absolute average relative range percent
-
-    variant
-      default thumbnail sparkline preview share
-
-    columns
-    order_by_direction
-      asc desc unsorted alpha
-    order_by_column
-    x_axis_column
-    join_on_columns
-    group_by_columns
-    highlight_columns
-

data/lib/swivel.rb

@@ -59,69 +59,67 @@ end
 # ==Overview
 #
 # Create a new connection to swivel.  Grabs options from ~/.swivelrc, creating
-# it if necessary.
+# it if necessary.  ({Get a Swivel API key}[http://swivel.com/api/key])
 #
 #   swivel = Swivel::Connection.new
 #
 # Get data from Swivel
 #
 #   # show a data_set's name
-#   data_set = swivel.call '/rest/data_sets/1000001'
+#   data_set = swivel.data_set 1000001
 #   data_set.name # => "American Longevity"
 #
 #   # list data_sets' names
-#   data_sets = swivel.call '/rest/data_sets'
+#   data_sets = swivel.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 = swivel.data_column 1000343
 #   data_column.name # => "Average Per Capita Income"
 #
 #   # list data_columns' names
-#   data_columns = swivel.call '/rest/data_columns'
+#   data_columns = swivel.data_columns
 #   data_columns.collect do |data_column|
 #     data_column.name
 #   end
 #
 #   # show a user's name
-#   user = swivel.call '/rest/user/1000010'
+#   user = swivel.user 1000010
 #   user.name # => "huned"
 #
 #   # list users' names
-#   users = swivel.call '/rest/users'
+#   users = swivel.users
 #   users.collect do |user|
 #     user.name
 #   end
 #
 #   # show a graph's name
-#   graph = swivel.call '/rest/graphs/5119232'
+#   graph = swivel.graph 5119232
 #   graph.name # => "Vinyl to Ipods"
 #
 #   # list graphs' names
-#   graphs = swivel.call '/rest/graphs'
+#   graphs = swivel.graphs
 #   graphs.collect do |graph|
 #     graph.name
 #   end
 #
 # Upload data
 #
+#   See Swivel::Connection#upload for a detailed list of options
+#
 #   # 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')
+#   data_set = swivel.append {...}.merge(:id => orig_data_set_id)
 #
 #   # replace data for an existing data_set
-#   data_set = swivel.append {...}.merge(:id => orig_data_set_id, :mode => 'replace')
-#
-# TODO: SwQL
+#   data_set = swivel.replace {...}.merge(:id => orig_data_set_id)
 #
 # TODO: constructing URLs for csvs, html pages, etc
 #
-# TODO: object cache {in memory, on filesystem}
-#
 
 module Swivel
 
@@ -263,14 +261,50 @@ module Swivel
       end
   end
 
-  %w/DataColumn DataSet User/.each do |class_name|
+  %w/DataColumn User/.each do |class_name|
     class_eval <<-LAZY
       class #{class_name} < Response; end
     LAZY
   end
 
+  class DataSet < Response
+    # Append new data to this data_set.  Passed in options must contain
+    # csv data.  This csv data must adhrere to the same column structure
+    # as the originally uploaded data_set.
+    #
+    #   data_set = swivel.data_set id
+    #   data_set.append! :data => `/tmp/append.csv`
+
+    def append! options = Hash.new
+      options.merge! :mode => 'append', :id => self.id
+      raise 'feed me data!' if options[:data].blank?
+      appended_data_set = @connection.upload options
+      @refreshed_at = nil
+      @retried = false
+      @doc = appended_data_set.instance_variable_get :@doc
+      self
+    end
+
+    # Replace data in this data_set.  Passed in options must contain
+    # csv data.  This csv data must adhere to the same column structure
+    # as the originally uploaded data set.
+    #
+    #   data_set = swivel.data_set id
+    #   data_set.replace! :data => `/tmp/replace.csv`
+
+    def replace! options = Hash.new
+      options.merge! :mode => 'replace', :id => self.id
+      raise 'feed me data!' if options[:data].blank?
+      replaced_data_set = @connection.upload options
+      @refreshed_at = nil
+      @retried = false
+      @doc = replaced_data_set.instance_variable_get :@doc
+      self
+    end
+  end
+
   class Graph < Response
-    def image_url options = {}
+    def image_url options = Hash.new
       host = @connection.config[:image_host]
       if variant == 'transient'
         "http://#{host}/graphs/get/#{digest}"
@@ -278,6 +312,47 @@ module Swivel
         "http://#{host}/graphs/image/#{id}"
       end
     end
+
+    # Swivel::Connection#create_graph returns a transient graph that
+    # must be saved in order for it to persist at Swivel.  Only persistent
+    # graphs have page urls at Swivel.
+    #
+    # call save on a transient graph in order to do this.
+    #
+    #   # create a transient graph
+    #   transient_graph = swivel.create_graph {...}
+    #   transient_graph.variant # => 'transient'
+    #   transient_graph.id.blank? # => true
+    #
+    #   # persist the transient graph
+    #   persisted_graph = transient_graph.save
+    #   persisted_graph.variant # => 'default'
+    #   persisted_graph.id.blank? # false
+    #
+    #   # now, you can grab it from swivel whenever
+    #   g = swivel.graph persisted_graph.id
+    #   g.name == persisted_graph.name # => true
+
+    def save!
+      return self unless variant == 'transient'
+      options = {:save => 'true', :digest => self.digest}
+      # PUT /rest/graphs/0 denotes updating a transient graph.  Swivel
+      # will read the digest and save the transient graph that matches
+      # that digest.
+      saved_graph = @connection.call '/rest/graphs/0', options, :put
+      @doc = saved_graph.instance_variable_get :@doc
+      @refreshed_at = nil
+      @retried = false
+      self
+    end
+
+    def add_column! data_column
+      # TODO
+    end
+
+    def remove_column! data_column
+      # TODO
+    end
   end
 
   # Encapsulates lists of resources.  Typically, items contained within the list are
@@ -412,6 +487,24 @@ module Swivel
     #   # returns a string (because an appropriate Swivel::Response subclass doesn't exist)
     #   echo = swivel.call '/rest/test/echo/howdy'
     #   echo.class # => String
+    #
+    # However, calling all of those endpoints is tedious.  For swivel's main objects
+    # there are some helper methods to get stuff:
+    #
+    #    data_set = swivel.data_set 1
+    #    data_set.class  # => Swivel::DataSet
+    #    data_set.id     # => 1
+    #
+    #    data_sets = swivel.data_sets
+    #
+    #    some_graph = swivel.graph 1232132
+    #
+    #    pwn3r = swivel.user 'visnu'
+    #    pwn3r.name     # => 'visnu'
+    #
+    # All these convenience methoods (yeah, methoods) really do is prettify a get call
+    # to:
+    #   /rest/object_type  or /rest/object_type/id
 
     def call path, params = Hash.new, method = :get
       xml =
@@ -428,26 +521,9 @@ module Swivel
       doc = REXML::Document.new xml
       Response.class_for(doc.root.elements[1].name).new xml, self
     rescue Exception => e
-      xml || nil
+      xml.blank? ? nil : xml
     end
 
-    # Calling all of those endpoints is tedious.  For swivel's main objects
-    # there are some helper methods to get stuff:
-    #
-    #    data_set = swivel.data_set 1
-    #    data_set.class  # => Swivel::DataSet
-    #    data_set.id     # => 1
-    #
-    #    data_sets = swivel.data_sets
-    #
-    #    some_graph = swivel.graph 1232132
-    #
-    #    da_bomb = swivel.user 'visnu'
-    #    da_bomb.name    # => 'visnu'
-    #
-    # All these really do is prettify a get call to:
-    #   /rest/object_type  or /rest/object_type/id
-
     %w/ data_columns data_sets graphs users /.each do |obj|
       class_eval <<-LAZY
         def #{obj} options = nil
@@ -468,49 +544,168 @@ module Swivel
       LAZY
     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].
+    DEFAULT_UPLOAD_OPTIONS = {
+      :citation => 'swivel.rb',
+      :citation_url => 'swivel.com/developer',
+      :image_url => 'http://swivel.com/images/logo.png',
+      :image_source_url => 'http://swivel.com',
+      :display_tags => 'swivel api swivel.rb'
+    }
+
+    # Performs an upload, append, or replace to a data_set in Swivel.
+    #   # upload a file to swivel
+    #   data_set = swivel.upload {...}
     #
-    # 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, append, or replace, you must have a valid api key.
+    # {Get a Swivel API key}[http://swivel.com/api/key].
     #
-    # In order to upload (including replace and append), you must have a valid api key.
+    #   # append to a data_set already in Swivel
+    #   more_data = `cat /tmp/more.csv`
+    #   data_set = swivel.append {:data => more_data}.merge(:id => data_set_id)
     #
-    # TODO: outline required and optional parameters.  give a few examples.
+    #   # replace underlying data in a data_set that already exists on Swivel
+    #   new_data = `cat /tmp/new.csv`
+    #   data_set = swivel.replace {:data => new_data}.merge(:id => data_set_id)
     #
-    # TODO: elaborate on requirements/assumptions for replace and append modes.
+    # 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.
     #
-    # TODO: limitations and crap?
+    # required parameters
+    # * options['id'] - data_set id that you want to append/replace.  (append, replace only)
+    # * options['name'] - name for the data_set.  (upload only)
+    # * options['citation'] - citation for the data_set.  e.g., U.N.  (upload only)
+    # * options['data'] - a string of actual csv data.  when appending or replacing data, a header row is optional.  (upload, append, and replace)
+    # * options['display_tags'] - tags for the data_set (upload only)
     #
-    #   # upload a file to swivel
-    #   data_set = swivel.upload {...}
+    # optional parameters (upload only; not for append or replace)
+    # * options['description'] - description for the data_set
+    # * options['citation_url'] - citation url for the data set.  e.g., http://un.org
+    # * options['auto_estimate'] - when true, swivel tries to figure out the column names, column types, and column separator character automatically from the csv data.  when missing or false, you must also supply options['column_names'], options['column_types'], and options['column_separator'].
+    # * options['column_names'] - a comma-separated string of column names.  only send this option when auto_estimate is missing or false.
+    # * options['column_types'] - a comma-separated string of column types.  possible types are DateTimeDataColumn, BooleanDataColumn, CurrencyDataColumn, NumberDataColumn, WholeNumberDataColumn, PercentageDataColumn, TextDataColumn.  only send this option when auto_estimate is missing or false.
+    # * options['column_separator'] - a character.  usually a ','.  only send this option when auto_estimate is false.
+    # * options['image_url'] - a url to an image you'd like to associate with your data_set.
+    # * options['image_source_url'] - a url to the source for your image, for proper attribution.
     #
-    #   # append to a data_set already in Swivel
-    #   data_set = swivel.append {...}
+    # {More examples online}[http://swivel.com/api/code]
     #
-    #   # replace underlying data in a data_set that already exists on Swivel
-    #   data_set = swivel.replace {...}
+    # A few limitations since swivel.rb is yet nascent and in its formative
+    # days.
+    # * You must post data as a string of text.
+    # * Actually, that's it, I think.
 
     def upload options = Hash.new
-      options[:mode] ||= 'initial'
+      opts = options.clone
+      opts[:mode] ||= 'initial'
+
       uri, method =
-        case options[:mode]
+        case opts[:mode]
         when 'append', 'replace'
-          ["/rest/data_sets/#{options[:id]}", :put]
+          opts[:auto_estimate] = true
+          ["/rest/data_sets/#{opts[:id]}", :put]
         else
+          force_auto_estimate =
+            !opts.has_key?(:auto_estimate) && !opts.has_key?(:column_type)
+          opts[:auto_estimate] = true if force_auto_estimate
+          opts.reverse_merge! DEFAULT_UPLOAD_OPTIONS
           ['/rest/data_sets', :post]
         end
-      call uri, options, method
+      call uri, opts, method
     end
+    alias_method :create_data_set, :upload
 
     %w/append replace/.each do |mode|
       class_eval <<-LAZY
         def #{mode} options = Hash.new
-          options[:mode] = "#{mode}"
-          upload options
+          opts = options.clone
+          opts[:mode] = "#{mode}"
+          upload opts
         end
       LAZY
     end
+
+    # Lets you create a transient graph in Swivel.
+    #
+    # If you pass in options[:save] => true, your transient graph will be
+    # immediately saved.
+    #
+    #     # build a transient graph, then save it.
+    #     transient_graph = swivel.create_graph {...}
+    #     graph = transient_graph.save
+    #
+    #     # a faster way of doing the same thing.
+    #     graph = swivel.create_graph {...}.merge(:save => 'true')
+    #
+    # Transient graphs exist in Swivel so you can cheaply play around with
+    # different visualizations, without saving them to Swivel's database.
+    # The idea is to let you quickly create visualizations and discard the
+    # duds and keep the gems.  So, create graphs with impunity!  And just
+    # save the ones you like.
+    #
+    # From an object perspective, the big differences between transient
+    # and persistent graphs are:
+    #
+    #     transient_graph = swivel.create_graph {...}
+    #
+    #     # transient graphs do not have ids.  thus, they are not accessible
+    #     # at their own page at swivel.com.
+    #     transient_graph.id # => nil
+    #
+    #     # transient graphs have a 'transient' variant
+    #     transient_graph.variant # => 'transient'
+    #
+    #     # transient graphs have digests whereas persisted graphs do not.
+    #     # digests act as a unique identifier for transient graphs.  e.g.,
+    #     # you'd use the digest to build urls to the transient graph's image.
+    #     transient_graph.digest.blank? # => false
+    #     transient_graph.image_url.blank? # => false
+    #
+    # Please don't save transient graphs you don't want to end up keeping
+    # around.  It's the most environmentally friendly thing to do.
+    #
+    # required parameters
+    # * options[:graph_type]
+    #   * LineGraph, BarGraph, HorizontalBarGraph, PieGraph, or ScatterGraph
+    #--
+    # TODO: that sucks.  i want: line, bar, hbar, pie, scatter, spark
+    #++
+    # * options[:columns]
+    #   a comma separated list of data_column ids
+    # * options[:x_axis_column]
+    #   the x-axis data_column id
+    #
+    # optional parameters
+    # * options[:join_on_columns]
+    #   a comma separated list of join data_column ids
+    # * options[:group_by_columns]
+    #   a comma separated list of group by data_column ids
+    # * options[:aggregation_function]
+    #   aggregation functions for group_by_columns.
+    #   one of: AvgFunction, ConcatFunction, MaxFunction, MinFunction,
+    #   SumFunction, CountFunction, DistinctCountFunction
+    # * options[:order_by_column]
+    #   a comma separated list of order-by data_column ids
+    # * options[:order_by_direction]
+    #   which sort to apply to the order_by_column.
+    #   one of: ASC, DESC, ALPHABETICAL, UNSORTED
+    # * options[:time_scale]
+    #   time-scale of your X-axis, if applicable.  one of: YEARLY,
+    #   QUARTERLY, MONTHLY, WEEKLY, DAILY, HOURLY, BY_MINUTE, BY_SECOND
+    # * options[:time_range]
+    #   time-range of your X-axis, if applicable.  Swivel understands many
+    #   human readable date/time formats.  Examples:  "3 years ago to now",
+    #   "1 month", "1992-2004".
+    # * options[:scale]
+    #   y-scale of the graph you're creating, if applicable.  one
+    #   of: ABSOLUTE, AVERAGE, RANGE, RELATIVE, PERCENT
+ 
+    def create_graph options = Hash.new, persist = false
+      options.merge! :save => 'true' if persist
+      unless options.has_key? :order_by_column
+        options.merge! :order_by_column => options[:columns].split(',').first,
+          :order_by_direction => 'DESC'
+      end
+      call '/rest/graphs', options, :post
+    end
   end
 end

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.2
 specification_version: 1
 name: swivel
 version: !ruby/object:Gem::Version 
-  version: 0.0.8
-date: 2007-06-28 00:00:00 -07:00
+  version: 0.0.15
+date: 2007-07-01 00:00:00 -07:00
 summary: Ruby interface to the Swivel API.
 require_paths: 
 - lib