quandl_ruby 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 47bb3190333744823d2bd2af9451ca002fa62642
-  data.tar.gz: 459eca5a698c9f403d82a39ead2e4ff4eb805d83
+  metadata.gz: c0952595cac0796e5898395d4c40c759e0340f68
+  data.tar.gz: beb7d47ca034889c91d39c4f442c63550d7d0911
 SHA512:
-  metadata.gz: 614f1a25a0731764eaca03b6d53fb49ee882993389dfd5b8650bf350105bf10e7ad80ca8a17ad0895409545a837da2d3ad06b1ae3ac90f523704aa360c5d6fe6
-  data.tar.gz: 8a2d905dc84aba3b06b3eaac2ba066a5d190ca834d80f50cf7de07154a382e4ec53cb0c1f8f8b935f6de8dfb1548ff3c7984afaf1b7e308ebf5628ac26ef53a4
+  metadata.gz: 16174ec2d59b403d495e1859e12f5836f7d273a69effb7a42e3c460d8f044c350dafa22520151a6e36e7016f5998d64ed2db38709ca3c6273715acc10642994c
+  data.tar.gz: 910439ff04926038746f133d463dc4e3ae9a8049cafc3e5573ebe0350d00ff11a1bbbfd917bc8fa72737b83bd528fa4f2bda27691b9d1b2a53ff81461377f67c

data/README.md

@@ -57,20 +57,67 @@ All the above classes have the same API:
 #   `:csv`  => parsed CSV into hashes
 #   `:xml`  => a string of unparsed xml
 # Set the format by providing a `:format` key in the options hash
+# Quandl::Class.get is an alias for Quandl::Class.new
 query = Quandl::Class.new(query, options)
 
-# Use instance#get to retrieve data from Quandl
-data = query.get
+# Use instance#data to retrieve data from Quandl
+data = query.data
 
-# Instantiating and then calling the `get` method memoizes the response
-# Pass in `true` to instance#get to clear the cache and reload the data
-data = query.get(true)
+# Instantiating and then calling the `data` method memoizes the response
+# Pass in `true` to instance#data to clear the cache
+data = query.data(true)
+```
+
+
+#### An Alternative to Passing in an Options Hash
+
+You can also pass in options by calling methods on an instance of a `Quandl::Class`:
+
+```ruby
+# This will make more sense if you read through:
+#   http://www.quandl.com/help/api#Data-Manipulation
+gdp = Quandl::Dataset.get('FRED/GDP')
+
+# Corresponds to the `rows` parameter. Aliased as #rows.
+gdp.limit(20)
+
+# Corresponds to the `sort_order` parameter. Aliased as #sort.
+gdp.order(:asc) # Only accepts :asc or :desc
 
-# The following is a shortcut to Class.new(query, options).get,
-# albeit with no build-in memoization:
-data = Quandl::Class.get(query, options)
+# Corresponds to the `column` parameter.
+gdp.column(4)
+
+# Corresponds to the `collapse` parameter. Aliased as #frequency
+# Accepts: :none, :daily, :weekly, :monthly, :quarterly, :annual
+gdp.collapse(:annual)
+
+# Corresponds to the `exclude_headers` parameter.
+gdp.headers(false) # (sets `exclude_headers` to `true`)
+
+# Corresponds to the `trim_start` parameter. Also accepts an instance of Date.
+gdp.start('2010-01-01')
+
+# Corresponds to the `trim_end` parameter. Also accepts an instance of Date.
+gdp.end('2014-01-01')
+
+# Corresponds to the `transformation` parameter.
+# Accepts: :diff, :rdiff, :cumul, :normalize
+gdp.transform(:normalize)
+
+# After all the above, call #metadata or #data to retrieve the respective data
+gdp.metadata # => returns metadata for 'FRED/GDP'
+gdp.data # => returns metadata for 'FRED/GDP'
+
+# If you were to change an option, like below:
+gdp.transform(:rdiff)
+
+# You'll need to call #reload! or pass `true` as an argument to #data or #metadata
+gdp.reload!
+
+gdp.data
 ```
 
+
 ### A Simple Example
 
 ```ruby

data/lib/quandl/dataset.rb

@@ -1,35 +1,38 @@
 module Quandl
   class Dataset
-    attr_accessor :set, :options, :data
+    attr_accessor :query, :options
 
-    def self.get(params, options = {})
-      instance = new(params, options)
-      instance.get
-      if block_given?
-        yield(instance.data)
-      else
-        instance.data
-      end
+    include Quandl::Filter
+
+    def self.get(*params)
+      new(*params)
     end
 
-    def initialize(params, options = {})
-      @set = params
+    def initialize(query, options = {})
+      @query = query
       @options = options
     end
 
-    def get(reload = false)
-      if !data || reload
-        raw_data = Quandl::Request.new('datasets', {
-          dataset: set,
-          options: options
-        }).get
-        self.data = Quandl.parse(raw_data, (options[:format] || :json).to_sym)
-      end
-      if block_given?
-        yield(data)
-      else
-        data
+    [:data, :metadata].each do |data|
+      define_method(data) do |bust_cache = false|
+        cache = instance_variable_get "@#{data}"
+        if cache && !bust_cache
+          cache
+        else
+          reload!
+          instance_variable_get "@#{data}"
+        end
       end
     end
+
+    def reload!
+      raw_data = Quandl::Request.new('datasets', {
+        dataset: query,
+        options: options
+      }).get
+      response = Quandl.parse(raw_data, (options[:format] || :json).to_sym)
+      @data = response.delete(:data)
+      @metadata = response
+    end
   end
 end

data/lib/quandl/favorites.rb

@@ -1,35 +1,18 @@
 module Quandl
-  class Favorites
-    attr_reader :auth_token, :options, :data
-
-    def self.get(options = {})
-      instance = new(options)
-      instance.get
-      if block_given?
-        yield(instance.data)
-      else
-        instance.data
-      end
-    end
-
+  class Favorites < Quandl::Dataset
     def initialize(options = {})
-      @auth_token = options.delete(:auth_token) || Quandl.configuration.auth_token
+      @query = options.delete(:auth_token) || Quandl.configuration.auth_token
       @options = options
     end
 
-    def get(reload = false)
-      if !data || reload
-        raw_data = Quandl::Request.new('current_user/collections/datasets/favourites', {
-          options: options,
-          auth_token: auth_token
-        }).get
-        self.data = Quandl.parse(raw_data, (options[:format] || :json).to_sym)
-      end
-      if block_given?
-        yield(data)
-      else
-        data
-      end
+    def reload!
+      raw_data = Quandl::Request.new('current_user/collections/datasets/favourites', {
+        auth_token: query,
+        options: options
+      }).get
+      response = Quandl.parse(raw_data, (options[:format] || :json).to_sym)
+      @data = response.delete(:data)
+      @metadata = response
     end
   end
 

data/lib/quandl/filter.rb

@@ -0,0 +1,52 @@
+module Quandl
+  module Filter
+    def limit(n)
+      @options[:rows] = n
+      self
+    end
+
+    alias_method :rows, :limit
+
+    def order(direction)
+      @options[:sort_order] = direction.to_sym if [:asc, :desc].include? direction.to_sym
+      self
+    end
+
+    alias_method :sort, :order
+
+    def column(n)
+      @options[:column] = n
+      self
+    end
+
+    def collapse(frequency)
+      if [:none, :daily, :weekly, :monthly, :quarterly, :annual].include? frequency.to_sym
+        @options[:collapse] = frequency.to_sym
+      end
+      self
+    end
+
+    def transform(transformation)
+      if [:diff, :rdiff, :cumul, :normalize].include? transformation.to_sym
+        @options[:transformation] = transformation.to_sym
+      end
+      self
+    end
+
+    def headers(request)
+      @options[:exclude_headers] = !request
+      self
+    end
+
+    [:start, :end].each do |filter|
+      define_method(filter) do |datetime|
+        if datetime.is_a?(String) && match_data = datetime.match(/(\d{4}).(\d{2}).(\d{2})/)
+          @options["trim_#{filter}".to_sym] = match_data[1..3].join('-')
+        elsif datetime.is_a?(Date)
+          @options["trim_#{filter}".to_sym] = datetime.to_s
+        end
+        self
+      end
+    end
+  end
+end

data/lib/quandl/metadata.rb

@@ -1,6 +1,6 @@
 module Quandl
   class Metadata < Quandl::Dataset
-    def initialize(params = {}, options = {})
+    def initialize(query, options = {})
       options[:exclude_data] = true
       super
     end

data/lib/quandl/multiset.rb

@@ -1,35 +1,13 @@
 module Quandl
-  class Multiset
-    attr_accessor :sets, :options, :data
-
-    def self.get(datasets, options = {})
-      instance = new(datasets, options)
-      instance.get
-      if block_given?
-        yield(instance.data)
-      else
-        instance.data
-      end
-    end
-
-    def initialize(datasets, options = {})
-      @sets = datasets
-      @options = options
-    end
-
-    def get
-      if !data || reload
-        raw_data = Quandl::Request.new('multisets', {
-          datasets: sets,
-          options: options
-        }).get
-        self.data = Quandl.parse(raw_data, (options[:format] || :json).to_sym)
-      end
-      if block_given?
-        yield(data)
-      else
-        data
-      end
+  class Multiset < Quandl::Dataset
+    def reload!
+      raw_data = Quandl::Request.new('multisets', {
+        datasets: query,
+        options: options
+      }).get
+      response = Quandl.parse(raw_data, (options[:format] || :json).to_sym)
+      @data = response.delete(:data)
+      @metadata = response
     end
   end
 end

data/lib/quandl/parse.rb

@@ -2,11 +2,9 @@ require 'json'
 require 'csv'
 
 module Quandl
-
   CSV::Converters[:blank_to_nil] = Proc.new do |field|
     field && field.empty? ? nil : field
   end
-
   def self.parse(data, format)
     case format
     when :json

data/lib/quandl/search.rb

@@ -1,35 +1,13 @@
 module Quandl
-  class Search
-    attr_accessor :query, :options, :data
-
-    def self.get(query, options = {})
-      instance = new(query, options)
-      instance.get
-      if block_given?
-        yield(instance.data)
-      else
-        instance.data
-      end
-    end
-
-    def initialize(query, options = {})
-      @query = query
-      @options = options
-    end
-
-    def get
-      if !data || reload
-        raw_data = Quandl::Request.new('datasets', {
-          query: query,
-          options: options
-        }).get
-        self.data = Quandl.parse(raw_data, (options[:format] || :json).to_sym)
-      end
-      if block_given?
-        yield(data)
-      else
-        data
-      end
+  class Search < Quandl::Dataset
+    def reload!
+      raw_data = Quandl::Request.new('datasets', {
+        query: query,
+        options: options
+      }).get
+      response = Quandl.parse(raw_data, (options[:format] || :json).to_sym)
+      @data = response.delete(:data)
+      @metadata = response
     end
   end
 end

data/lib/quandl/version.rb

@@ -1,3 +1,3 @@
 module Quandl
-  VERSION = '0.1.2'
+  VERSION = '0.2.0'
 end

data/lib/quandl.rb

@@ -1,6 +1,7 @@
 require_relative 'quandl/version'
 require_relative 'quandl/configuration'
 require_relative 'quandl/parse'
+require_relative 'quandl/filter'
 require_relative 'quandl/dataset'
 require_relative 'quandl/metadata'
 require_relative 'quandl/multiset'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quandl_ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Kash Nouroozi
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-20 00:00:00.000000000 Z
+date: 2014-08-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -54,6 +54,7 @@ files:
 - lib/quandl/configuration.rb
 - lib/quandl/dataset.rb
 - lib/quandl/favorites.rb
+- lib/quandl/filter.rb
 - lib/quandl/metadata.rb
 - lib/quandl/multiset.rb
 - lib/quandl/parse.rb