kpi 0.5.1 → 0.5.2

data/README.rdoc

@@ -22,62 +22,108 @@ Add to your Gemfile:
 and run in console in project directory:
 
   $ bundle
+  
+=== Rails 2.x
 
-== Configuration
-
-Create config/initializers/kpi.rb:
-
-  KPI.configure do |c|
-    c.app_name = "Your App Name"
-    c.mail_from = "Your App KPI Service <kpi@example.com>"
-    c.mail_to = "your@email.com"
-  end
+This gem is tested with Rails 2.3.8.
 
 == Defining report
 
 Example report in app/models/daily_kpi_report.rb:
 
-  class DailyKpiReport < KPI::Report::Base
+  class DailyKpiReport < KPI::Report
     def users_count
-      return ["Users count", User.count, "Total users count"]
+      result "Users count", User.count, :description => "Total users count"
     end
     
     def today_registrations_count
-      return ["Today registrations count", User.where("created_at > ?", @time - 24.hours)]
+      result "Today registrations count", User.where("created_at > ?", @time - 24.hours)
+    end
+    
+    def total_income
+      result "Total income", Order.sum(:total), :unit => 'EUR'
+    end
+    
+    def today_income
+      result "Total income", Order.where(:created_at => today).sum(:total), :unit => 'EUR'
+    end
+    
+    private
+    
+    def today
+      ((time - 24.hours)..time)
     end
   end
 
-Each defined method should return an array containing 2 or 3 elements:
-* KPI title
+Each defined method should return a KPI::Entry object with following accessors:
+* name
 * value
-* optional description
+* description
+* unit
+
+A collection of KPI::Entry is available through Enuberable: Report#entries
 
 It is important, if your indicator depends on current time (last 24 hours, last week),
 to rely on @time instance variable instead of Time.now. This lets you to generate report
 for every moment in history:
 
-  report = DailyKpiReport.new(2.days.ago)
-
-== Sending report
-
-To collect all statistics and send an email to you just call:
-
-  DailyKpiReport.collect_and_send!
+  report = DailyKpiReport.new(:time => 2.days.ago)
+
+=== Merged reports
+
+You can create merged report from two or more reports of the same type. Look at examples:
+
+    > today = DailyKpiReport.new
+    > today.users_count.value
+    # => 20
+    > today.today_income.value
+    # => 350
+    > yesterday = DailyKpiReport.new(:time => 1.day.ago)
+    > yesterday.users_count.value
+    # => 16
+    > yesterday.today_income.value
+    # => 250
+    > diff = KPI::MergedReport.new(today, yesterday) do |today, yesterday|
+    >   KPI::Entry.new "$$ (change)", today - yesterday
+    > end
+    > avg = KPI::MergedReport.new(today, yesterday) do |*entries|
+    >   KPI::Entry.new "$$ (avg)", entries
+    > end
+    > diff.users_count.value
+    # => 4
+    > avg.today_income.value
+    # => 300
+    > avg.today_income.unit
+    # => "EUR"
+
+More reports can be passed to constructor of Merged report:
+    avg = KPI::MergedReport.new(week_now, week_last, week_next_to_last) do |*entries|
+      # ...
+    end
 
 == Other
 * You can override report title by overriding title method in report:
-    class DailyKpiReport < KPI::Report::Base
+    class DailyKpiReport < KPI::Report
       def title; "Your daily report"; end
       # ...
     end
 * You can use Whenever gem to generate periodic reports
-
+* Private methods are not considered as indicator methods and can be used as helper methods:
+    class WeeklyReport < KPI::Report
+      # ...
+      private
+      
+      def week_range
+        t_prev_mon_begin = time - (time.wday-1)*24*60*60 - time.hour*60*60 - time.min*60 - time.sec
+        t_next_sun_end = t_prev_mon_begin + 7*24*60*60 - 1
+        (t_prev_mon_begin..t_next_sun_end)
+      end
+    end
 == Todo
 
 * Generators for configuration and reports
 * Database persistence - storing reports in different databases: PostgreSQL & Mongo prioritized
-* Controllers & views allowing to review stored reports
-* More tests ;)
+* Support for "result" helper in block passed to constructor of MergedReport
 
 
 == Contributing to KPI

data/app/models/kpi/entry.rb

@@ -1,15 +1,16 @@
 module KPI
   class Entry
-    attr_reader :name, :value, :description
+    attr_reader :name, :value, :description, :unit
     def initialize(*args)
       options = args.extract_options!
       raise ArgumentError, "Wrong number of arguments (#{args.count} of 2)" unless args.count == 2
       @name, @value = args
       @description = options[:description]
+      @unit = options[:unit]
     end
     
     def to_a
-      [@title, @value, @description].compact
+      [@title, @value, @description, @unit].compact
     end
   end
 end

data/app/models/kpi/merged_report.rb

@@ -28,9 +28,12 @@ module KPI
     def method_missing(name, *args)
       result = @compare.call(*@reports.map(&name.to_sym))
       orginal = @reports.first.send(name.to_sym)
-      description = (orginal.description ? result.description.gsub("$$", orginal.description) : nil)
+      description = (orginal.description && result.description ? result.description.gsub("$$", orginal.description) : nil)
 
-      KPI::Entry.new(result.name.gsub("$$", orginal.name), result.value, :description => description)
+      KPI::Entry.new(result.name.gsub("$$", orginal.name),
+                     result.value,
+                     :description => description,
+                     :unit => (result.unit || orginal.unit))
     end
   end
 end

data/app/models/kpi/report.rb

@@ -8,8 +8,8 @@ module KPI
     blacklist :initialize, :collect!, :entries, :time, :title, :defined_kpis, :result
  
     def initialize(*args)
-      options = args.extract_options!
-      @time = options[:time] || Time.now
+      @options = args.extract_options!
+      @time = @options[:time] || Time.now
     end
     attr_reader :time
  

data/test/unit/kpi/entry_tesr.rb

@@ -28,5 +28,13 @@ describe "KPI::Entry" do
         assert_equal("desc", @entry.description)
       end
     end
+    
+    describe "when unit given" do
+      before { @entry = KPI::Entry.new "Income", 1294.23, :description => "EUR" }
+    
+      it "returns description" do
+        assert_equal("EUR", @entry.unit)
+      end
+    end
   end
 end

data/test/unit/kpi/merged_report_test.rb

@@ -14,7 +14,7 @@ describe "KPI::MergedReport" do
       end
 
       def test_kpi_2
-        result "title 2 ", @return*2
+        result "title 2 ", @return*2, :unit => 'EUR'
       end
     end
     class AnotherReport < KPI::Report
@@ -54,10 +54,10 @@ describe "KPI::MergedReport" do
 
   describe "when two reports given for average" do
     before do
-      report1 = TestKpi.new(2)
-      report2 = TestKpi.new(8)
+      @report1 = TestKpi.new(2)
+      @report2 = TestKpi.new(8)
 
-      @average = KPI::MergedReport.new(report1, report2) do |*entries|
+      @average = KPI::MergedReport.new(@report1, @report2) do |*entries|
         average = entries.map(&:value).sum / entries.size
         KPI::Entry.new "Average $$", average, :description => "$$ (average)"
       end
@@ -74,6 +74,18 @@ describe "KPI::MergedReport" do
     it "should change $$ in description to indicator descripiton" do
       assert_equal "description (average)", @average.test_kpi.description
     end
+    
+    it "should have unit" do
+      assert_equal "EUR", @average.test_kpi_2.unit
+    end
+    
+    it "should allow to override unit" do
+      @merged = KPI::MergedReport.new(@report1, @report2) do |*entries|
+        KPI::Entry.new "merged $$", 1, :unit => "$"
+      end
+      assert_equal '$', @merged.test_kpi.unit
+      assert_equal '$', @merged.test_kpi_2.unit
+    end
 
     it "should return nil description when no description" do
       assert_nil @average.test_kpi_2.description

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: kpi
 version: !ruby/object:Gem::Version 
-  hash: 9
+  hash: 15
   prerelease: 
   segments: 
   - 0
   - 5
-  - 1
-  version: 0.5.1
+  - 2
+  version: 0.5.2
 platform: ruby
 authors: 
 - Artur Roszczyk
@@ -15,12 +15,12 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-13 00:00:00 +02:00
+date: 2011-05-14 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  type: :runtime
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  name: actionmailer
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -30,12 +30,12 @@ dependencies:
         - 2
         - 3
         version: "2.3"
-  name: actionmailer
-  version_requirements: *id001
   prerelease: false
-- !ruby/object:Gem::Dependency 
   type: :runtime
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  requirement: *id001
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -45,12 +45,12 @@ dependencies:
         - 2
         - 3
         version: "2.3"
-  name: activesupport
-  version_requirements: *id002
   prerelease: false
+  type: :runtime
+  requirement: *id002
 - !ruby/object:Gem::Dependency 
-  type: :development
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  name: minitest
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -59,12 +59,12 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  name: minitest
-  version_requirements: *id003
   prerelease: false
-- !ruby/object:Gem::Dependency 
   type: :development
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  requirement: *id003
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  version_requirements: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -74,12 +74,12 @@ dependencies:
         - 1
         - 0
         version: "1.0"
-  name: bundler
-  version_requirements: *id004
   prerelease: false
-- !ruby/object:Gem::Dependency 
   type: :development
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  requirement: *id004
+- !ruby/object:Gem::Dependency 
+  name: jeweler
+  version_requirements: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -90,12 +90,12 @@ dependencies:
         - 5
         - 2
         version: 1.5.2
-  name: jeweler
-  version_requirements: *id005
   prerelease: false
-- !ruby/object:Gem::Dependency 
   type: :development
-  requirement: &id006 !ruby/object:Gem::Requirement 
+  requirement: *id005
+- !ruby/object:Gem::Dependency 
+  name: rcov
+  version_requirements: &id006 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -104,9 +104,9 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  name: rcov
-  version_requirements: *id006
   prerelease: false
+  type: :development
+  requirement: *id006
 description: This gem helps you to track key indicators in your Rails app.
 email: artur.roszczyk@gmail.com
 executables: []
@@ -165,7 +165,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.5.2
 signing_key: 
 specification_version: 3
 summary: Key Performance Indicators for Rails 3.x