tworgy-spaced-repetition 0.2.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Mat Holroyd
+
+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/README.rdoc

@@ -0,0 +1,45 @@
+= Spaced Repetition 
+
+Ruby gem that implements the SM-2 algorithm of SuperMemo. See http://www.supermemo.com/english/ol/sm2.htm for more details.
+
+The plan is to add more algorithms in the future, e.g. Mnemosyne.
+
+== Install
+
+  gem install tworgy-spaced-repetition
+  
+== Usage
+
+The gem provides a mixin which should be added to a class that represents something you want to remember, e.g. a flash card class. The mixin adds several methods (described below) to calculate the date when the next repetition should occur.  
+
+Importantly, the mixin depends on several methods existing on the hosting class.  The mixin should throw an exception if it cannot find the appropriate methods.
+
+  class FlashCardExample 
+    attr_accessor :easiness_factor, :number_repetitions, :quality_of_last_recall, :next_repetition     
+
+    include SuperMemo::SM2
+  end
+
+Create an instance of the object as per usual
+
+  fc = FlashCardExample.new
+
+Reset the data to begin with
+
+  fc.reset_spaced_repetition_data
+  fc.easiness_factor => 2.5  
+  fc.number_repetitions => 0  
+  fc.quality_of_last_recall => nil  
+  fc.next_repetition => Date.today  
+
+Calculate the next interval/date (Note: SM2 expects a number between 0-5)
+  
+  fc.process_recall_result(4)
+
+  fc.repetition_interval => 1 (day)
+  fc.next_repetition => tomorrow (Date.today + 1 day)
+
+== Notes
+
+Currently this gem only includes the SM-2 version of the SuperMemo algorithm. Although more recent versions of the SuperMemo algorithm exist, some popular open source and commercial alternatives to SuperMemo (such as Mnemosyne) base their algorithms on the SM-2 algorithm, as they judge it a superior algorithm to the more recent iterations.  The author of Mnemosyne (the leading open source alternative) makes the point that there is a conflict of interest underlying commercial products like SuperMemo, in that companies have a vested interest in claiming the newer algorithms are better regardless of whether they actually are.  
+

data/Rakefile

@@ -0,0 +1,45 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "tworgy-spaced-repetition"
+    gem.summary = %Q{Spaced repetition algorithms and mixins}
+    gem.description = %Q{A collection of spaced-reptetition algorithms and mixins e.g. SuperMemo}
+    gem.email = "code@tworgy.com"
+    gem.homepage = "http://github.com/matholroyd/tworgy-spaced-repetition"
+    gem.authors = ["Mat Holroyd"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.files = %w(LICENSE README.rdoc Rakefile) + Dir.glob("{lib,spec}/**/*")
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "tworgy-spaced-repetition #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/spaced-repetition/sm2.rb

@@ -0,0 +1,69 @@
+module SuperMemo
+
+  # This module can be used as a mixin to add the algorithms as used by 
+  # SuperMemo 2 (typically referred to as SM2).  
+  # 
+  # See the README for more information.
+  module SM2
+    
+    def SM2.extended(obj)
+      obj.check_spaced_repetition_methods
+    end
+  
+    def reset_spaced_repetition_data
+      self.easiness_factor = 2.5  
+      self.number_repetitions = 0  
+      self.quality_of_last_recall = nil  
+      self.repetition_interval = nil
+      self.next_repetition = Date.today  
+    end
+
+    def process_recall_result(quality_of_recall)
+      DBC.require(quality_of_recall >= 0)
+      DBC.require(quality_of_recall <= 5)
+      
+      if quality_of_recall < 3    
+        self.number_repetitions = 0 
+      else
+        self.number_repetitions += 1
+        self.easiness_factor = calculate_easiness_factor(easiness_factor, quality_of_recall)
+      end
+      
+      case number_repetitions
+      when 0
+        self.repetition_interval = 0
+      when 1
+        self.repetition_interval = 1
+      when 2
+        self.repetition_interval = 6
+      else
+        self.repetition_interval = repetition_interval * easiness_factor
+      end
+      
+      self.next_repetition = Date.today + repetition_interval
+    end
+
+    def check_spaced_repetition_methods
+      begin
+        send(:easiness_factor)
+        send(:number_repetitions)
+        send(:quality_of_last_recall)
+        send(:next_repetition)
+        send(:repetition_interval)
+      rescue NoMethodError => e
+        DBC.assert(false, e.message)
+      end
+    end
+    
+    private 
+    
+    def calculate_easiness_factor(easiness_factor, quality_of_recall)
+      q = quality_of_recall
+      ef_old = easiness_factor
+
+      result = ef_old - 0.8 + (0.28*q) - (0.02*q*q)
+      result < 1.3 ? 1.3 : result
+    end
+    
+  end
+end

data/lib/tworgy-spaced-repetition-testing.rb

@@ -0,0 +1 @@
+# require 'tworgy/testing'

data/lib/tworgy-spaced-repetition.rb

@@ -0,0 +1 @@
+require 'spaced-repetition/sm2'

data/spec/lib/spaced-repetition/sm2_spec.rb

@@ -0,0 +1,81 @@
+require File.expand_path(File.dirname(__FILE__) + '../../../spec_helper')
+
+describe SuperMemo::SM2 do
+  
+  describe 'include mixin' do
+
+    it 'should work fine when including' do
+      class Temp
+        attr_accessor :easiness_factor, :number_repetitions, :quality_of_last_recall, :next_repetition, :repetition_interval
+        include SuperMemo::SM2
+      end
+      
+      t = Temp.new
+      t.check_spaced_repetition_methods
+    end
+
+    it 'should raise DBC exception if class including is missing fields' do
+      class Temp2 
+        include SuperMemo::SM2
+      end
+      t = Temp2.new
+
+      lambda {
+        t.check_spaced_repetition_methods
+      }.should raise_error(DBC::AssertconditionException)
+    end
+
+  end
+  
+  describe 'exclude mixin' do
+    
+    before :each do
+      @flash_card = {
+        :easiness_factor => nil, 
+        :number_repetitions => nil, 
+        :quality_of_last_recall => nil,
+        :next_repetition => nil,
+        :repetition_interval => nil,
+        :question => "Who is the most awesome of them all?",
+        :answer => 'Me!'
+      }.ostructify
+
+      @flash_card.extend SuperMemo::SM2
+      @flash_card.reset_spaced_repetition_data
+    end
+    
+    it 'should raise DBC exception if class extended is missing fields' do
+      lambda { nil.extend SuperMemo::SM2 }.should raise_error(DBC::AssertconditionException)
+    end
+    
+    it 'should initialize values' do
+      @flash_card.easiness_factor.should == 2.5  
+      @flash_card.number_repetitions.should == 0  
+      @flash_card.repetition_interval.should == nil  
+      @flash_card.quality_of_last_recall.should == nil  
+      @flash_card.next_repetition.should == Date.today  
+    end
+    
+    it 'should schedule next repetition for tomorrow if repetition_interval = 0 and quality_of_last_recall = 4' do
+      @flash_card.process_recall_result(4)
+      
+      @flash_card.number_repetitions.should == 1
+      @flash_card.repetition_interval.should == 1
+      @flash_card.next_repetition.should == (Date.today + 1)
+      @flash_card.easiness_factor.should be_close(2.5, 0.01)
+    end
+
+    it 'should schedule next repetition for 6 days if repetition_interval = 1 and quality_of_last_recall = 4' do
+      @flash_card.process_recall_result(4)
+      @flash_card.process_recall_result(4)
+      
+      @flash_card.number_repetitions.should == 2
+      @flash_card.repetition_interval.should == 6
+      @flash_card.next_repetition.should == (Date.today + 6)
+      @flash_card.easiness_factor.should be_close(2.5, 0.01)
+    end
+    
+  end
+
+
+end

data/spec/lib/spaced-repetition/testing_spec.rb

@@ -0,0 +1,17 @@
+require File.expand_path(File.dirname(__FILE__) + '../../../spec_helper')
+
+describe 'rspec helper' do
+  # it 'should capture nothing' do
+  #   capture_stderr {
+  #     1 + 1
+  #     1.to_s
+  #   }.should == ""
+  # end 
+  #  
+  # it 'should capture errors on stderr' do
+  #   capture_stderr {
+  #     [].id
+  #   }.should =~ /Object#id will be deprecated/
+  # end
+  # 
+end

data/spec/spec.opts

@@ -0,0 +1 @@
+--color

data/spec/spec_helper.rb

@@ -0,0 +1,13 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'rubygems'
+require 'tworgy-ruby'
+require 'tworgy-spaced-repetition'
+require 'tworgy-spaced-repetition-testing'
+require 'spec'
+require 'spec/autorun'
+
+Spec::Runner.configure do |config|
+  
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification 
+name: tworgy-spaced-repetition
+version: !ruby/object:Gem::Version 
+  version: 0.2.0
+platform: ruby
+authors: 
+- Mat Holroyd
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-02-22 00:00:00 +11:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.9
+    version: 
+description: A collection of spaced-reptetition algorithms and mixins e.g. SuperMemo
+email: code@tworgy.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- LICENSE
+- README.rdoc
+- Rakefile
+- lib/spaced-repetition/sm2.rb
+- lib/tworgy-spaced-repetition-testing.rb
+- lib/tworgy-spaced-repetition.rb
+- spec/lib/spaced-repetition/sm2_spec.rb
+- spec/lib/spaced-repetition/testing_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/matholroyd/tworgy-spaced-repetition
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Spaced repetition algorithms and mixins
+test_files: 
+- spec/lib/spaced-repetition/sm2_spec.rb
+- spec/lib/spaced-repetition/testing_spec.rb
+- spec/spec_helper.rb