garb 0.2.1

data/README.md

@@ -0,0 +1,178 @@
+garb
+====
+
+  by Tony Pitale with much help from Justin Marney, Patrick Reagan and others at Viget Labs
+
+  http://github.com/vigetlabs/garb
+
+Changes
+=======
+
+  Version 0.2.0 makes major changes to the way garb is used to build reports.
+  There is now both a module that gets included for generating defined classes.
+  As well as, slight changes to the way that the Report class can be used.
+
+Description
+-----------
+
+  Provides a Ruby API to the Google Analytics API.
+
+  http://code.google.com/apis/analytics/docs/gdata/gdataDeveloperGuide.html
+
+Basic Usage
+===========
+
+Login
+-----
+  
+    > Garb::Session.login(username, password)
+
+Profiles
+--------
+
+    > Garb::Profile.all
+    > profile = Garb::Profile.all.first
+
+Define a Report Class and Get Results
+-------------------------------------
+
+    class Exits
+      include Garb::Resource
+
+      metrics :exits, :pageviews, :exit_rate
+      dimensions :request_uri
+    end
+
+Parameters
+----------
+
+  * start_date: The date of the period you would like this report to start
+  * end_date: The date to end, inclusive
+  * limit: The maximum number of results to be returned
+  * offset: The starting index
+
+Metrics & Dimensions
+--------------------
+
+  Metrics and Dimensions are very complex because of the ways in which the can and cannot be combined.
+
+  I suggest reading the google documentation to familiarize yourself with this.
+
+  http://code.google.com/apis/analytics/docs/gdata/gdataReferenceDimensionsMetrics.html#bounceRate
+
+  When you've returned, you can pass the appropriate combinations (up to 50 metrics and 2 dimenstions)
+  to garb, as an array, of symbols. Or you can simply push a symbol into the array.
+
+Sorting
+-------
+
+  Sorting can be done on any metric or dimension defined in the request, with .desc reversing the sort.
+
+Building a Report
+-----------------
+
+  Given the class, session, and profile from above we can do:
+
+    Exits.results(profile, :limit => 10, :offset => 19)
+
+  Or, with sorting and filters:
+
+    Exits.results(profile, :limit => 10, :offset => 19) do
+      filter :request_uri.contains => 'season', :exits.gt => 100
+      sort :exits
+    end
+
+  reports will be an array of OpenStructs with methods for the metrics and dimensions returned.
+
+Build a One-Off Report
+----------------------
+
+    report = Garb::Report.new(profile)
+    report.metrics :pageviews
+    report.dimensions :request_uri
+
+    report.filter :request_uri.contains => 'season', :exits.gte => 10
+    report.sort :exits
+
+    report.results
+
+Filtering
+---------
+
+  Google Analytics supports a significant number of filtering options.
+
+  http://code.google.com/apis/analytics/docs/gdata/gdataReference.html#filtering
+
+  We handle filtering as an array of hashes that you can push into, 
+  which will be joined together (AND'd)
+
+  Here is what we can do currently:
+  (the operator is a method on a symbol metric or dimension)
+
+  Operators on metrics:
+
+    :eql => '==',
+    :not_eql => '!=',
+    :gt => '>',
+    :gte => '>=',
+    :lt => '<',
+    :lte => '<='
+
+  Operators on dimensions:
+
+    :matches => '==',
+    :does_not_match => '!=',
+    :contains => '=~',
+    :does_not_contain => '!~',
+    :substring => '=@',
+    :not_substring => '!@'
+    
+  Given the previous example one-off report, we can add a line for filter:
+  
+    report.filters << {:request_uri.eql => '/extend/effectively-using-git-with-subversion/'}
+
+TODOS
+-----
+
+  * Sessions are currently global, which isn't awesome
+  * Single user login is the only supported method currently.
+    Intend to add hooks for using OAuth
+  * Read opensearch header in results
+  * OR joining filter parameters
+
+Requirements
+------------
+
+  libxml
+  happymapper
+
+Install
+-------
+
+    sudo gem install vigetlabs-garb -s http://gems.github.com
+
+License
+-------
+
+  (The MIT License)
+
+  Copyright (c) 2008 Viget Labs
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  'Software'), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be
+  included in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,54 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+
+require 'lib/garb/version'
+
+task :default => :test
+
+spec = Gem::Specification.new do |s|
+  s.name              = 'garb'
+  s.version           = Garb::Version.to_s
+  s.has_rdoc          = false
+  s.summary           = "Google Analytics API Ruby Wrapper"
+  s.authors           = ['Tony Pitale','Justin Marney', 'Patrick Reagan']
+  s.email             = 'tony.pitale@viget.com'
+  s.homepage          = 'http://github.com/vigetlabs/garb'
+  s.files             = %w(README.md Rakefile) + Dir.glob("lib/**/*")
+  s.test_files        = Dir.glob("test/**/*")
+
+  s.add_dependency("jnunemaker-happymapper", [">= 0.2.2"])
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+desc 'Generate the gemspec to serve this Gem from Github'
+task :github do
+  file = File.dirname(__FILE__) + "/#{spec.name}.gemspec"
+  File.open(file, 'w') {|f| f << spec.to_ruby }
+  puts "Created gemspec: #{file}"
+end
+
+begin
+  require 'rcov/rcovtask'
+  
+  desc "Generate RCov coverage report"
+  Rcov::RcovTask.new(:rcov) do |t|
+    t.test_files = FileList['test/**/*_test.rb']
+    t.rcov_opts << "-x lib/garb.rb -x lib/garb/version.rb"
+  end
+rescue LoadError
+  nil
+end
+
+task :default => 'test'
+
+# EOF

data/lib/extensions/happymapper.rb

@@ -0,0 +1,67 @@
+require 'libxml'
+
+module HappyMapper
+
+  module ClassMethods
+    include LibXML
+
+    def parse(xml, options = {})
+      # locally scoped copy of namespace for this parse run
+      namespace = @namespace
+
+      if xml.is_a?(XML::Node)
+        node = xml
+      else
+        if xml.is_a?(XML::Document)
+          node = xml.root
+        else
+          node = XML::Parser.string(xml).parse.root
+        end
+
+        root = node.name == tag_name
+      end
+
+      # This is the entry point into the parsing pipeline, so the default
+      # namespace prefix registered here will propagate down
+      namespaces = node.namespaces
+      if namespaces && namespaces.default
+        already_assigned = namespaces.definitions.detect do |defn|
+          namespaces.default && namespaces.default.href == defn.href && defn.prefix
+        end
+        namespaces.default_prefix = DEFAULT_NS unless already_assigned
+        namespace ||= DEFAULT_NS
+      end
+
+      xpath = root ? '/' : './/'
+      xpath += "#{namespace}:" if namespace
+      xpath += tag_name
+      # puts "parse: #{xpath}"
+      
+      nodes = node.find(xpath)
+      collection = nodes.collect do |n|
+        obj = new
+        
+        attributes.each do |attr| 
+          obj.send("#{attr.method_name}=", 
+                    attr.from_xml_node(n, namespace))
+        end
+        
+        elements.each do |elem|
+          obj.send("#{elem.method_name}=", 
+                    elem.from_xml_node(n, namespace))
+        end
+        
+        obj
+      end
+
+      # per http://libxml.rubyforge.org/rdoc/classes/LibXML/XML/Document.html#M000354
+      nodes = nil
+
+      if options[:single] || root
+        collection.first
+      else
+        collection
+      end
+    end
+  end
+end

data/lib/extensions/operator.rb

@@ -0,0 +1,20 @@
+# Concept from dm-core
+class Operator
+  attr_reader :target, :operator, :prefix
+  
+  def initialize(target, operator, prefix=false)
+    @target   = target.to_ga
+    @operator = operator
+    @prefix = prefix
+  end
+  
+  def to_ga
+    @prefix ? "#{operator}#{target}" : "#{target}#{operator}"
+  end
+  
+  def ==(rhs)
+    target == rhs.target &&
+    operator == rhs.operator &&
+    prefix == rhs.prefix
+  end
+end

data/lib/extensions/string.rb

@@ -0,0 +1,13 @@
+class String
+  def underscored
+    self.gsub(/([A-Z])/, '_\1').downcase
+  end
+  
+  def lower_camelized
+    self.gsub(/(_)(.)/) { $2.upcase }
+  end
+  
+  def to_ga
+    "ga:#{self}"
+  end
+end

data/lib/extensions/symbol.rb

@@ -0,0 +1,36 @@
+class Symbol
+  # OPERATORS
+
+  def self.operator(operators)
+    operators.each do |method, operator|
+      class_eval <<-CODE
+        def #{method}
+          Operator.new(self, '#{operator}')
+        end
+      CODE
+    end
+  end
+
+  # Sorting
+  def desc
+    Operator.new(self, '-', true)
+  end
+
+  operator  :eql => '==',
+            :not_eql => '!=',
+            :gt => '>',
+            :gte => '>=',
+            :lt => '<',
+            :lte => '<=',
+            :matches => '==',
+            :does_not_match => '!=',
+            :contains => '=~',
+            :does_not_contain => '!~',
+            :substring => '=@',
+            :not_substring => '!@'
+
+  # Metric filters  
+  def to_ga
+    "ga:#{self.to_s.lower_camelized}"
+  end
+end

data/lib/garb.rb

@@ -0,0 +1,70 @@
+$:.unshift File.expand_path(File.dirname(__FILE__))
+
+require 'net/http'
+require 'net/https'
+require 'rubygems'
+require 'cgi'
+require 'ostruct'
+require 'happymapper'
+
+require 'garb/version'
+require 'garb/authentication_request'
+require 'garb/data_request'
+require 'garb/session'
+require 'garb/profile'
+require 'garb/report_parameter'
+require 'garb/report_response'
+require 'garb/resource'
+require 'garb/report'
+
+require 'extensions/string'
+require 'extensions/operator'
+require 'extensions/symbol'
+require 'extensions/happymapper'
+
+module Garb
+  # :stopdoc:
+  GA = "http://schemas.google.com/analytics/2008"
+
+  VERSION = '0.1.2'
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+  # :startdoc:
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    VERSION
+  end
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args )
+    args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args )
+    args.empty? ? PATH : ::File.join(PATH, args.flatten)
+  end
+
+  # Utility method used to rquire all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+        ::File.join(::File.dirname(fname), dir, '*', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb}
+  end
+end  # module Garb
+
+# EOF

data/lib/garb/authentication_request.rb

@@ -0,0 +1,46 @@
+module Garb
+  class AuthenticationRequest
+    class AuthError < StandardError;end
+    
+    URL = 'https://www.google.com/accounts/ClientLogin'
+    
+    def initialize(email, password)
+      @email = email
+      @password = password
+    end
+    
+    def parameters
+      {
+        'Email'       => @email,
+        'Passwd'      => @password,
+        'accountType' => 'HOSTED_OR_GOOGLE',
+        'service'     => 'analytics',
+        'source'      => 'vigetLabs-garb-001'
+      }
+    end
+    
+    def uri
+      URI.parse(URL)
+    end
+    
+    def send_request      
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      http.request(build_request) do |response|
+        raise AuthError unless response.is_a?(Net::HTTPOK)
+      end
+    end
+    
+    def build_request
+      post = Net::HTTP::Post.new(uri.path)
+      post.set_form_data(parameters)
+      post
+    end
+    
+    def auth_token
+      send_request.body.match(/^Auth=(.*)$/)[1]
+    end
+    
+  end
+end