nps 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in nps.gemspec
+gemspec

data/README.md

@@ -0,0 +1,119 @@
+# Nps
+
+A Net Promoter Score (NPS) calculator; does exactly as it says on the tin.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'nps'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install nps
+
+## Usage
+
+### Introduction
+Firstly, create a new survey:
+```
+require 'nps'
+
+survey = Nps::Survey.new
+```
+
+### Voting
+Voting is simply achieved by:
+```
+# Promoter vote
+survey.vote!(10)
+
+# Passive vote
+survey.vote!(8)
+
+# Detractor vote
+survey.vote!(6)
+```
+
+### NPS Calculation
+The NPS score can be calculated by:
+```
+# Calculate the NPS score
+survey.score
+```
+
+It is also useful to know the percentage of votes in each category:
+```
+# Show the percentage of promoters, passives and detractors
+survey.percentage_of_promoters
+survey.percentage_of_passives
+survey.percentage_of_detractors
+```
+
+### Ballot Adaptor
+
+By default NPS comes with an in-memory adapter `NPS::Ballot` for storing NPS votes. You can also optionally configure NPS to use a different adapter to store your votes in a database or another persistance store:
+
+```
+  Nps.configure do |config|
+    config.ballot_adaptor = YourBallotAdapter
+  end
+```
+To use a different adapter you must implement the same API as `NPS::Ballot`.
+
+```
+  class YourBallotAdaptor
+
+    # Public: Initialize a Net Promoter Score ballot to store votes cast
+    # on a survey.
+    def initialize
+
+    end
+
+    # Public: Cast a vote with a given NPS value.
+    #
+    # value - The value of the vote on the NPS scale.
+    # opts - A hash of meta data associated with the vote (default: {}) 
+    def vote!(value, opts = {})
+
+    end
+
+    # Public: Whether any votes have been cast.
+    def any_votes?
+
+    end
+
+    # Public: The total number of votes that have been cast.
+    def total_votes
+
+    end
+
+    # Public: Find the votes that have been cast with a
+    # NPS value in the range.
+    #
+    # range - The range of NPS values.
+    def find_votes(range)
+
+    end
+
+    # Public: Count the votes that have been cast with a
+    # NPS value in the range.
+    #
+    # range - The range of NPS values.
+    def count_votes(range)
+
+    end
+  end
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/nps.rb

@@ -0,0 +1,28 @@
+require 'ostruct'
+
+require "nps/version"
+require "nps/calculator"
+require "nps/survey"
+require "nps/ballot"
+require "nps/configuration"
+
+module Nps
+  extend self
+
+  attr_accessor :configuration
+
+  # Public: Set custom configuration options
+  # such as how to store the NPS votes.
+  #
+  # Examples:
+  #   Nps.configure do |config|
+  #     config.ballot_adaptor = YourBallotAdaptor
+  #   end
+  #
+  def configure
+    self.configuration ||= Nps::Configuration.new
+    yield(configuration) if block_given?
+  end
+
+  Nps.configure
+end

data/lib/nps/ballot.rb

@@ -0,0 +1,46 @@
+module Nps
+  class Ballot
+
+    # Public: Initialize a Net Promoter Score ballot to store votes cast
+    # on a survey.
+    def initialize
+      @votes = []
+    end
+
+    # Public: Cast a vote with a given NPS value.
+    #
+    # value - The value of the vote on the NPS scale.
+    # opts - A hash of meta data associated with the vote (default: {}) 
+    def vote!(value, opts = {})
+      vote = OpenStruct.new(:value => value.to_f, :options => opts)
+      @votes << vote
+      vote
+    end
+
+    # Public: Whether any votes have been cast.
+    def any_votes?
+      total_votes != 0
+    end
+
+    # Public: The total number of votes that have been cast.
+    def total_votes
+      @votes.count
+    end
+
+    # Public: Find the votes that have been cast with a
+    # NPS value in the range.
+    #
+    # range - The range of NPS values.
+    def find_votes(range)
+      @votes.select { |vote| range.include?(vote.value) }
+    end
+
+    # Public: Count the votes that have been cast with a
+    # NPS value in the range.
+    #
+    # range - The range of NPS values.
+    def count_votes(range)
+      find_votes(range).count
+    end
+  end
+end

data/lib/nps/calculator.rb

@@ -0,0 +1,48 @@
+module Nps
+  class Calculator
+
+    # Internal: Initialize a Net Promoter Score (NPS) calculator
+    #
+    # ballot - a ballot of votes in the NPS survey.
+    def initialize(ballot)
+      @ballot = ballot
+    end
+
+    # Internal: The Net Promoter Score (NPS) calculated from the ballot.
+    def score
+      percentage_of_promoters - percentage_of_detractors
+    end
+
+    # Internal: The percentage of promoter votes in the ballot.
+    def percentage_of_promoters
+      @ballot.any_votes? ? ((promoters.to_f / @ballot.total_votes.to_f) * 100.0).round(2) : 0.0
+    end
+
+    # Internal: The percentage of passive votes in the ballot.
+    def percentage_of_passives
+      @ballot.any_votes? ? ((passives.to_f / @ballot.total_votes.to_f) * 100.0).round(2) : 0.0
+    end
+
+    # Internal: The percentage of detractor votes in the ballot.
+    def percentage_of_detractors
+      @ballot.any_votes? ? ((detractors.to_f / @ballot.total_votes.to_f) * 100.0).round(2) : 0.0
+    end
+
+    private
+
+    # Internal: The number of promoters in the ballot.
+    def promoters
+      @ballot.count_votes(9..10)
+    end
+
+    # Internal: The number of passives in the ballot.
+    def passives
+      @ballot.count_votes(7..8)
+    end
+
+    # Internal: The number of detractors in the ballot.
+    def detractors
+      @ballot.count_votes(0..6)
+    end
+  end
+end

data/lib/nps/configuration.rb

@@ -0,0 +1,13 @@
+module Nps
+  class Configuration
+
+    # Public: Retrieve or assign a ballot adaptor to store the NPS votes.
+    attr_accessor :ballot_adaptor
+
+    # Public: Initialize a new configuration for the library
+    # with the default behaviour.
+    def initialize
+      @ballot_adaptor = Nps::Ballot
+    end
+  end
+end

data/lib/nps/survey.rb

@@ -0,0 +1,54 @@
+module Nps
+  class Survey
+
+    attr_reader :ballot
+
+    # Public: Initialize a Net Promoter Score (NPS) survey
+    #
+    # Example:
+    #   survey = Nps::Survey.new
+    #   survey.vote!(10)
+    #   survey.score
+    #
+    def initialize
+      @ballot = Nps.configuration.ballot_adaptor.new
+    end
+
+    # Public: The Net Promoter Score (NPS) for the survey.
+    def score
+      calculator.score
+    end
+
+    # Public: The percentage of promoter votes in the survey.
+    def percentage_of_promoters
+      calculator.percentage_of_promoters
+    end
+
+    # Public: The percentage of passive votes in the survey.
+    def percentage_of_passives
+      calculator.percentage_of_passives
+    end
+
+    # Public: The percentage of detractor votes in the survey.
+    def percentage_of_detractors
+      calculator.percentage_of_detractors
+    end
+
+    # Public: Add a vote to the survey with the given value
+    #
+    # value - The value of the vote on the NPS scale (0..10)
+    # opts - A hash of meta data associated with the vote (default: {})
+    def vote!(value, opts = {})
+      ballot.vote!(value, opts)
+    end
+
+    private
+
+    # Internal: The Net Promoter Score Calculator
+    def calculator
+      Nps::Calculator.new(ballot)
+    end
+  end
+
+end
+

data/lib/nps/version.rb

@@ -0,0 +1,3 @@
+module Nps
+  VERSION = "0.0.1"
+end

data/nps.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'nps/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "nps"
+  spec.version       = Nps::VERSION
+  spec.authors       = ["Murray Summers"]
+  spec.email         = ["murray.sum@gmail.com"]
+  spec.description   = %q{Net Promoter Score (NPS) is a customer loyalty metric allowing customer satisfaction to be compared over time and business sector.}
+  spec.summary       = %q{A Net Promoter Score (NPS) calculator}
+  spec.homepage      = "https://github.com/murraysum/nps"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency 'rspec'
+end

data/spec/ballot_spec.rb

@@ -0,0 +1,111 @@
+require 'spec_helper'
+
+describe Nps::Ballot do
+  
+  describe 'initialize' do
+    before :each do
+      @ballot = Nps::Ballot.new
+    end
+
+    it 'have no promoter votes' do
+      @ballot.count_votes(9..10).should == 0
+    end
+
+    it 'have no passive votes' do
+      @ballot.count_votes(7..8).should == 0
+    end
+
+    it 'have no detractor votes' do
+      @ballot.count_votes(0..6).should == 0
+    end
+
+    it 'have no votes' do
+      @ballot.any_votes?.should be_false
+    end
+
+    it 'have no votes in all categories' do
+      @ballot.total_votes.should == 0
+    end
+  end
+
+  describe 'promoter vote' do
+    before :each do
+      @ballot = Nps::Ballot.new
+      @ballot.vote!(10)
+    end
+
+    it 'have a promoters vote' do
+      @ballot.count_votes(9..10).should == 1
+    end
+
+    it 'have no passive votes' do
+      @ballot.count_votes(7..8).should == 0
+    end
+
+    it 'have no detractor votes' do
+      @ballot.count_votes(0..6).should == 0
+    end
+
+    it 'have votes' do
+      @ballot.any_votes?.should be_true
+    end
+
+    it 'have one vote' do
+      @ballot.total_votes.should == 1
+    end
+  end
+
+  describe 'passive vote' do
+    before :each do
+      @ballot = Nps::Ballot.new
+      @ballot.vote!(8)
+    end
+
+    it 'have no promoter votes' do
+      @ballot.count_votes(9..10).should == 0
+    end
+
+    it 'have a passive vote' do
+      @ballot.count_votes(7..8).should == 1
+    end
+
+    it 'have no detractor votes' do
+      @ballot.count_votes(0..6).should == 0
+    end
+
+    it 'have votes' do
+      @ballot.any_votes?.should be_true
+    end
+
+    it 'have one vote' do
+      @ballot.total_votes.should == 1
+    end
+  end
+
+  describe 'detractor vote' do
+    before :each do
+      @ballot = Nps::Ballot.new
+      @ballot.vote!(6)
+    end
+
+    it 'have no promoter votes' do
+      @ballot.count_votes(9..10).should == 0
+    end
+
+    it 'have no passive votes' do
+      @ballot.count_votes(7..8).should == 0
+    end
+
+    it 'have a detractor vote' do
+      @ballot.count_votes(0..6).should == 1
+    end
+
+    it 'have votes' do
+      @ballot.any_votes?.should be_true
+    end
+
+    it 'have one vote' do
+      @ballot.total_votes.should == 1
+    end
+  end
+end

data/spec/calculator_spec.rb

@@ -0,0 +1,135 @@
+require 'spec_helper'
+
+describe Nps::Calculator do
+  describe 'with an empty ballot' do
+    before :each do
+      @ballot = Nps::Ballot.new
+      @calculator = Nps::Calculator.new(@ballot)
+    end
+
+    it 'have a zero score' do
+      @calculator.score.should == 0
+    end
+
+    it 'have zero percentage of promoters' do
+      @calculator.percentage_of_promoters.should == 0
+    end
+
+    it 'have zero percentage of passives' do
+      @calculator.percentage_of_passives.should == 0
+    end
+
+    it 'have zero percentage of detractors' do
+      @calculator.percentage_of_detractors.should == 0
+    end
+  end
+
+  describe 'with a promoter ballot' do
+    before :each do
+      @ballot = Nps::Ballot.new
+      @calculator = Nps::Calculator.new(@ballot)
+      @ballot.vote!(10)
+    end
+
+    it 'have a score' do
+      @calculator.score.should == 100
+    end
+
+    it 'have percentage of promoters' do
+      @calculator.percentage_of_promoters.should == 100
+    end
+
+    it 'have zero percentage of passives' do
+      @calculator.percentage_of_passives.should == 0
+    end
+
+    it 'have zero percentage of detractors' do
+      @calculator.percentage_of_detractors.should == 0
+    end
+  end
+
+  describe 'with a passive ballot' do
+    before :each do
+      @ballot = Nps::Ballot.new
+      @calculator = Nps::Calculator.new(@ballot)
+      @ballot.vote!(7)
+    end
+
+    it 'have a score' do
+      @calculator.score.should == 0
+    end
+
+    it 'have zero percentage of promoters' do
+      @calculator.percentage_of_promoters.should == 0
+    end
+
+    it 'have a percentage of passives' do
+      @calculator.percentage_of_passives.should == 100
+    end
+
+    it 'have zero percentage of detractors' do
+      @calculator.percentage_of_detractors.should == 0
+    end
+  end
+
+  describe 'with a detractor ballot' do
+    before :each do
+      @ballot = Nps::Ballot.new
+      @calculator = Nps::Calculator.new(@ballot)
+      @ballot.vote!(0)
+    end
+
+    it 'have a score' do
+      @calculator.score.should == -100
+    end
+
+    it 'have zero percentage of promoters' do
+      @calculator.percentage_of_promoters.should == 0
+    end
+
+    it 'have zero percentage of passives' do
+      @calculator.percentage_of_passives.should == 0
+    end
+
+    it 'have a percentage of detractors' do
+      @calculator.percentage_of_detractors.should == 100
+    end
+  end
+
+  describe 'with a mixed ballot' do
+    before :each do
+      @ballot = Nps::Ballot.new
+      @calculator = Nps::Calculator.new(@ballot)
+      # Promoters
+      @ballot.vote!(10)
+      @ballot.vote!(9)
+      # Passives
+      @ballot.vote!(8)
+      @ballot.vote!(7)
+      # Detractors
+      @ballot.vote!(6)
+      @ballot.vote!(5)
+      @ballot.vote!(4)
+      @ballot.vote!(3)
+      @ballot.vote!(2)
+      @ballot.vote!(1)
+      @ballot.vote!(0)
+    end
+
+    it 'have a score' do
+      @calculator.score.should == -45.46
+    end
+
+    it 'have a percentage of promoters' do
+      @calculator.percentage_of_promoters.should == 18.18
+    end
+
+    it 'have a percentage of passives' do
+      @calculator.percentage_of_passives.should == 18.18
+    end
+
+    it 'have a percentage of detractors' do
+      @calculator.percentage_of_detractors.should == 63.64
+    end
+  end
+end

data/spec/configuration_spec.rb

@@ -0,0 +1,25 @@
+require 'spec_helper'
+
+describe Nps::Configuration do
+
+  describe 'with default options' do
+    before :each do
+      @configuration = Nps::Configuration.new
+    end
+
+    it 'should set the default ballot adaptor' do
+      @configuration.ballot_adaptor == Nps::Ballot
+    end
+  end
+
+  describe 'with custom options' do
+    before :each do
+      @configuration = Nps::Configuration.new
+      @configuration.ballot_adaptor = Struct
+    end
+
+    it 'should set a custom ballot adaptor' do
+      @configuration.ballot_adaptor == Struct
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+require 'rspec'
+require 'nps'
+
+RSpec.configure do |config|
+  config.color_enabled = true
+  config.formatter = 'documentation'
+end

data/spec/survey_spec.rb

@@ -0,0 +1,39 @@
+require 'spec_helper'
+
+describe Nps::Survey do
+  describe 'with a survey' do
+    before :each do
+      @survey = Nps::Survey.new
+      # Promoters
+      @survey.vote!(10)
+      @survey.vote!(9)
+      # Passives
+      @survey.vote!(8)
+      @survey.vote!(7)
+      # Detractors
+      @survey.vote!(6)
+      @survey.vote!(5)
+      @survey.vote!(4)
+      @survey.vote!(3)
+      @survey.vote!(2)
+      @survey.vote!(1)
+      @survey.vote!(0)
+    end
+
+    it 'have a score' do
+      @survey.score.should == -45.46
+    end
+
+    it 'have a percentage of promoters' do
+      @survey.percentage_of_promoters.should == 18.18
+    end
+
+    it 'have a percentage of passives' do
+      @survey.percentage_of_passives.should == 18.18
+    end
+
+    it 'have a percentage of detractors' do
+      @survey.percentage_of_detractors.should == 63.64
+    end
+  end
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: nps
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Murray Summers
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-02-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Net Promoter Score (NPS) is a customer loyalty metric allowing customer
+  satisfaction to be compared over time and business sector.
+email:
+- murray.sum@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- lib/nps.rb
+- lib/nps/ballot.rb
+- lib/nps/calculator.rb
+- lib/nps/configuration.rb
+- lib/nps/survey.rb
+- lib/nps/version.rb
+- nps.gemspec
+- spec/ballot_spec.rb
+- spec/calculator_spec.rb
+- spec/configuration_spec.rb
+- spec/spec_helper.rb
+- spec/survey_spec.rb
+homepage: https://github.com/murraysum/nps
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: A Net Promoter Score (NPS) calculator
+test_files:
+- spec/ballot_spec.rb
+- spec/calculator_spec.rb
+- spec/configuration_spec.rb
+- spec/spec_helper.rb
+- spec/survey_spec.rb