legato 0.0.10 → 0.1.0

data/README.md

@@ -68,19 +68,19 @@ Here's what google has to say: http://code.google.com/apis/analytics/docs/gdata/
 
 Return entries with exits counts greater than or equal to 2000
 
-    filter :high_exits, lambda {gte(:exits, 2000)}
+    filter :high_exits, &lambda {gte(:exits, 2000)}
 
 Return entries with pageview metric less than or equal to 200
 
-    filter :low_pageviews, lambda {lte(:pageviews, 200)}
+    filter :low_pageviews, &lambda {lte(:pageviews, 200)}
 
 Filters with dimensions
 
-    filter :for_browser, lambda {|browser| matches(:broswer, browser)}
+    filter :for_browser, &lambda {|browser| matches(:browser, browser)}
 
 Filters with OR
 
-    filter :browsers, lambda {|*browsers| browsers.map {|browser| matches(:broswer, browser)}}
+    filter :browsers, &lambda {|*browsers| browsers.map {|browser| matches(:browser, browser)}}
 
 
 ## Using and Chaining Filters ##
@@ -109,7 +109,7 @@ Be sure to pass the appropriate number of arguments matching the lambda for your
 
 For a filter defined like this:
 
-    filter :browsers, lambda {|*browsers| browsers.map {|browser| matches(:broswer, browser)}}
+    filter :browsers, &lambda {|*browsers| browsers.map {|browser| matches(:browser, browser)}}
 
 We can use it like this, passing any number of arguments:
 
@@ -140,6 +140,45 @@ Operators on dimensions:
     substring        => '=@',
     not_substring    => '!@'
 
+## Dynamic Segment
+
+Your query can have a dynamic segment, which works with filter expressions. It
+works like an [advanced
+segment](https://support.google.com/analytics/answer/1033017?hl=en), except you
+don't have to create it beforehand, you can just specify it at query time.
+
+Some of the numbers you'll get will be different from using a filter, since
+[the subset of visits matched happens before dimensions and metrics are
+calculated](http://ga-dev-tools.appspot.com/explorer/) (hover on the `segment`
+parameter to see).
+
+Some metrics and dimensions are not allowed for segments, see the [API
+documentation](https://developers.google.com/analytics/devguides/reporting/core/v3/reference#segment)
+for more details.
+
+### Defining, using and chaining filters
+
+Return entries with exits counts greater than or equal to 2000
+
+    segment :high_exits do
+      gte(:exits, 2000)
+    end
+
+Return entries with pageview metric less than or equal to 200
+
+    segment :low_pageviews do
+      lte(:pageviews, 200)
+    end
+
+You can chain them
+
+    Exit.high_exits.low_pageviews(profile)
+
+and call them directly on the profile
+
+    profile.exit.high_exits.low_pageviews
+
+
 ## Accounts, WebProperties, Profiles, and Goals ##
 
     > Legato::Management::Account.all(user)

data/lib/legato/model.rb

@@ -26,6 +26,18 @@ module Legato
       end
     end
 
+    def segments
+      @segments ||= {}
+    end
+
+    def segment(name, &block)
+      segments[name] = block
+
+      (class << self; self; end).instance_eval do
+        define_method(name) {|*args| Query.new(self).apply_segment_filter(*args, &block)}
+      end
+    end
+
     def set_instance_klass(klass)
       @instance_klass = klass
     end

data/lib/legato/query.rb

@@ -11,6 +11,12 @@ module Legato
       end
     end
 
+    def define_segment_filter(name, &block)
+      (class << self; self; end).instance_eval do
+        define_method(name) {|*args| apply_segment_filter(*args, &block)}
+      end
+    end
+
     def self.define_filter_operators(*methods)
       methods.each do |method|
         class_eval <<-CODE
@@ -24,12 +30,13 @@ module Legato
     attr_reader :parent_klass
     attr_accessor :profile, :start_date, :end_date
     attr_accessor :sort, :limit, :offset, :quota_user #, :segment # individual, overwritten
-    attr_accessor :filters # appended to, may add :segments later for dynamic segments
+    attr_accessor :filters, :segment_filters # combined, can be appended to
 
     def initialize(klass)
       @loaded = false
       @parent_klass = klass
       self.filters = FilterSet.new
+      self.segment_filters = FilterSet.new
       self.start_date = Time.now - MONTH
       self.end_date = Time.now
 
@@ -37,10 +44,9 @@ module Legato
         define_filter(name, &block)
       end
 
-      # may add later for dynamic segments
-      # klass.segment_definitions.each do |name, segment|
-      #   self.class.define_segment(name, segment)
-      # end
+      klass.segments.each do |name, block|
+        define_segment_filter(name, &block)
+      end
     end
 
     def instance_klass
@@ -48,6 +54,14 @@ module Legato
     end
 
     def apply_filter(*args, &block)
+      apply_filter_expression(self.filters, *args, &block)
+    end
+
+    def apply_segment_filter(*args, &block)
+      apply_filter_expression(self.segment_filters, *args, &block)
+    end
+
+    def apply_filter_expression(filter_set, *args, &block)
       @profile = extract_profile(args)
 
       join_character = Legato.and_join_character # filters are joined by AND
@@ -55,7 +69,7 @@ module Legato
       # # block returns one filter or an array of filters
       Array.wrap(instance_exec(*args, &block)).each do |filter|
         filter.join_character ||= join_character # only set when not set explicitly
-        self.filters << filter
+        filter_set << filter
 
         join_character = Legato.or_join_character # arrays are joined by OR
       end
@@ -169,6 +183,10 @@ module Legato
       @sort = Legato::ListParameter.new(:sort, arr)
     end
 
+    def segment
+      "dynamic::#{segment_filters.to_params}" if segment_filters.any?
+    end
+
     # def segment_id
     #   segment.nil? ? nil : "gaid::#{segment}"
     # end
@@ -184,7 +202,7 @@ module Legato
         'end-date' => Legato.format_time(end_date),
         'max-results' => limit,
         'start-index' => offset,
-        # 'segment' => segment_id,
+        'segment' => segment,
         'filters' => filters.to_params, # defaults to AND filtering
         'fields' => REQUEST_FIELDS,
         'quotaUser' => quota_user

data/lib/legato/version.rb

@@ -1,3 +1,3 @@
 module Legato
-  VERSION = "0.0.10"
+  VERSION = "0.1.0"
 end

data/spec/lib/legato/model_spec.rb

@@ -69,6 +69,33 @@ describe "Legato::Model" do
       end
     end
 
+    context "with segments" do
+      before :each do
+        @block = lambda {}
+      end
+
+      it 'creates a class method' do
+        @model.segment :high, &@block
+        @model.respond_to?(:high).should be_true
+      end
+
+      it 'stores the segment' do
+        @model.segment :high, &@block
+        @model.segments[:high].should == @block
+      end
+
+      it 'returns a Query instance for a segment' do
+        query = stub(:apply_segment_filter => "a query")
+        Legato::Query.stubs(:new).returns(query)
+
+        @model.segment :high, &@block
+        @model.high('arg1').should == 'a query'
+
+        Legato::Query.should have_received(:new).with(@model)
+        query.should have_received(:apply_segment_filter).with('arg1')
+      end
+    end
+
     # xit 'has an instance klass'
     # xit 'sets an instance klass'
 

data/spec/lib/legato/query_spec.rb

@@ -20,6 +20,7 @@ describe Legato::Query do
       @klass = Class.new
       @block = lambda {eql(:key, 1000)}
       @klass.stubs(:filters).returns({:high => @block})
+      @klass.stubs(:segments).returns([])
 
       @query = Legato::Query.new(@klass)
     end
@@ -354,6 +355,13 @@ describe Legato::Query do
         @query.to_params['filters'].should == 'filter set parameters'
       end
 
+      it 'includes the dynamic segment' do
+        segment_filters = stub(:to_params => 'segment parameter', :any? => true)
+        @query.stubs(:segment_filters).returns(segment_filters)
+
+        @query.to_params['segment'].should == 'dynamic::segment parameter'
+      end
+
       it 'includes metrics' do
         metrics = Legato::ListParameter.new(:metrics)
         metrics.stubs(:to_params).returns({'metrics' => 'pageviews,exits'})

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legato
 version: !ruby/object:Gem::Version
-  version: 0.0.10
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-07 00:00:00.000000000 Z
+date: 2013-07-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake