acts_as_flashcard 0.1.0

data/Gemfile

@@ -0,0 +1,17 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+gem "activerecord"
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.1"
+end
+
+group :test do
+  gem "shoulda"
+  gem "sqlite3-ruby"
+  gem "railties"
+end

data/README.rdoc

@@ -0,0 +1,37 @@
+= acts_as_flashcard
+
+acts_as_flashcard is an adaptation of the Anki ( http://ichi2.net/anki/ ) algorithm for ruby on rails application.
+
+== Requirements
+
+Rails3 (for Rails2 version please check the corresponding branches)
+Has been tested with ruby 1.9.1
+
+== Installation
+
+gem install acts_as_flashcard
+
+== Example
+
+class Card < ActiveRecord::Base
+  acts_as_flashcard :scope => :user_id
+end
+
+card = Card.create
+card.answered!(4)
+
+== Contributing to acts_as_flashcard
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2010 Bastien Vaucher. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,47 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "acts_as_flashcard"
+  gem.homepage = "http://github.com/bastien/acts_as_flashcard"
+  gem.license = "GNU"
+  gem.summary = "flashcard space repetition algorithm"
+  gem.description = "act_as_flashcard is an adaptation of the Anki space repetition algorithm for rails applications"
+  gem.email = "bastien.vaucher@gmail.com"
+  gem.authors = ["Bastien Vaucher"]
+  gem.add_dependency 'activerecord'
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "acts_as_flashcard #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/acts_as_flashcard.gemspec

@@ -0,0 +1,70 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{acts_as_flashcard}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Bastien Vaucher"]
+  s.date = %q{2010-11-26}
+  s.description = %q{act_as_flashcard is an adaptation of the Anki space repetition algorithm for rails applications}
+  s.email = %q{bastien.vaucher@gmail.com}
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    "GNU-LICENCE",
+    "Gemfile",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "acts_as_flashcard.gemspec",
+    "install.rb",
+    "lib/acts_as_flashcard.rb",
+    "lib/generators/flashcard/USAGE",
+    "lib/generators/flashcard/flashcard_generator.rb",
+    "lib/generators/flashcard/templates/add_flashcards_fields_migration.rb",
+    "lib/generators/flashcard/templates/create_flashcards_migration.rb",
+    "tasks/acts_as_flashcard_tasks.rake",
+    "test/acts_as_flashcard_test.rb",
+    "test/flashcards_migration_generator_test.rb",
+    "test/test_helper.rb",
+    "uninstall.rb"
+  ]
+  s.homepage = %q{http://github.com/bastien/acts_as_flashcard}
+  s.licenses = ["GNU"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{flashcard space repetition algorithm}
+  s.test_files = [
+    "test/acts_as_flashcard_test.rb",
+    "test/flashcards_migration_generator_test.rb",
+    "test/test_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<activerecord>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.5.1"])
+      s.add_runtime_dependency(%q<activerecord>, [">= 0"])
+    else
+      s.add_dependency(%q<activerecord>, [">= 0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.5.1"])
+      s.add_dependency(%q<activerecord>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<activerecord>, [">= 0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.5.1"])
+    s.add_dependency(%q<activerecord>, [">= 0"])
+  end
+end
+

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/acts_as_flashcard.rb

@@ -0,0 +1,201 @@
+#ActsAsFlashcard
+module Flashcard                         #:nodoc:
+  module Base                 #:nodoc:
+    
+    def self.included(base)         #:nodoc:
+      base.extend ClassMethods
+    end
+    
+    MAX_SCHEDULE_TIME = 1825
+    INITIAL_FACTOR = 2.5
+    EASY_INTERVAL_MIN = 7
+    EASY_INTERVAL_MAX = 9
+    MID_INTERVAL_MIN = 3
+    MID_INTERVAL_MAX = 5
+    HARD_INTERVAL_MIN = 0.333
+    HARD_INTERVAL_MAX = 0.5
+    DELAY = 600
+    FACTOR_FOUR = 1.3
+    
+    #  successive    :integer         default(0)
+    #  repetitions   :integer         default(0)
+    #  yes_count     :integer         default(0)
+    #  no_count      :integer         default(0)
+    #  factor        :float           default(2.5)
+    #  last_factor   :float           default(2.5)
+    #  interval      :integer         default(0)
+    #  last_interval :float           default(0.0)
+    #  due           :datetime
+    #  combined_due  :integer         default(0)
+    
+    module ClassMethods
+      
+      def acts_as_flashcard(options = {})
+        configuration = {:scope => "1 = 1"}
+        configuration.update(options) if options.is_a?(Hash)
+
+        configuration[:scope] = "#{configuration[:scope]}_id".to_sym if configuration[:scope].is_a?(Symbol) && configuration[:scope].to_s !~ /_id$/
+
+        if configuration[:scope].is_a?(Symbol)
+          scope_condition_method = %(
+            def scope_condition
+              if #{configuration[:scope].to_s}.nil?
+                "#{configuration[:scope].to_s} IS NULL"
+              else
+                "#{configuration[:scope].to_s} = \#{#{configuration[:scope].to_s}}"
+              end
+            end
+          )
+        else
+          scope_condition_method = "def scope_condition() \"#{configuration[:scope]}\" end"
+        end
+        
+        class_eval <<-EOV
+          include Flashcard::Base::InstanceMethods
+          
+          def acts_as_flashcard_class
+            ::#{self.name}
+          end
+          
+          #{scope_condition_method}
+          
+          before_create  :initialize_due_date
+        EOV
+      end
+    end
+    
+    module InstanceMethods
+      
+      # ease: 0 - 4
+      #
+      def answered!(ease)
+        increment_repetitions(ease)
+        last_delay_secs = (Time.now - self.combined_due).to_f
+        last_delay    = last_delay_secs / 86400.0
+        self.interval = next_interval(ease) unless last_delay >= 0 # keep last interval if reviewing early
+        last_due      = self.due
+        self.due      = next_due(ease)
+        update_factor(ease) if last_delay >= 0
+        min_of_other_cards = acts_as_flashcard_class.minimum('interval', :conditions => "#{scope_condition} AND id != #{self.id}")
+        space = min_of_other_cards.nil? ? 0 : [min_of_other_cards, self.interval].min
+        space = space * 0.1.day
+        space = [space, 60].max
+        space = Time.now + space
+        self.combined_due = [space, due].max
+        save
+      end
+      
+      private 
+      
+      # Set the due date to today when the card is created
+      #
+      def initialize_due_date
+        self.due = Time.now
+      end
+      
+      # Increments the count of time this card has been reviewed,
+      # How many times it hasn't been answered wrong successively
+      # as well as the amount of time it has been answered right and wrong
+      #
+      def increment_repetitions(ease)
+        self.repetitions += 1
+        if ease > 1
+          self.successive += 1
+        else
+          self.successive = 0
+        end
+        if self.repetitions > 1
+          if ease < 2
+            self.no_count += 1
+          else
+            self.yes_count += 1
+          end
+        end
+      end
+      
+      def delay
+        return 0 if repetitions == 0
+        if self.combined_due <= Time.now.to_f
+          return Time.now - self.due
+        else
+          return Time.now - self.combined_due
+        end
+      end
+
+      def next_interval(ease)
+        current_delay = delay.to_i
+        current_interval = self.interval
+        if current_delay < 0 && self.successive > 0
+          current_interval = [self.last_interval, self.interval + current_delay].max
+          if current_interval < MID_INTERVAL_MIN
+            current_interval = 0
+          end
+          current_delay = 0
+        end
+        if ease == 1
+          current_interval *= DELAY
+          current_interval = 0 if current_interval < HARD_INTERVAL_MIN
+        elsif current_interval == 0
+          case ease
+            when 2 then current_interval = rand(HARD_INTERVAL_MAX - HARD_INTERVAL_MIN) + HARD_INTERVAL_MIN
+            when 3 then current_interval = rand(MID_INTERVAL_MAX - MID_INTERVAL_MIN) + MID_INTERVAL_MIN
+            when 4 then current_interval = rand(EASY_INTERVAL_MAX - EASY_INTERVAL_MIN) + EASY_INTERVAL_MIN
+          end
+        else
+          if current_interval < HARD_INTERVAL_MAX && current_interval > 0.166
+            mid = MID_INTERVAL_MIN + MID_INTERVAL_MAX / 2
+            current_interval *= (mid / current_interval / self.factor)
+            case ease
+              when 2 then current_interval = (current_interval + current_delay/4) * 1.2
+              when 3 then current_interval = (current_interval + current_delay/2) * self.factor
+              when 4 then current_interval = (current_interval + current_delay) * self.factor * FACTOR_FOUR
+            end
+            fuzz = (rand(10) + 95).to_f / 100.0
+            current_interval *= fuzz
+          end
+        end
+        return [MAX_SCHEDULE_TIME, current_interval].min     
+      end
+      
+      # Average factor among all the cards
+      #
+      def average_factor
+        avg_factor =  acts_as_flashcard_class.average("factor", :conditions => "#{scope_condition} AND id != #{self.id}")
+        return avg_factor ||= INITIAL_FACTOR
+      end
+
+      def update_factor(ease)
+        self.last_factor = self.factor
+        if repetitions == 0
+          self.factor = averageFactor
+        end
+        if being_learnt? && ([0, 1, 2].include?(ease))
+          self.factor -= 0.20 if (self.successive > 0) && (ease != 2)
+        else
+          case ease
+            when 0..1 then self.factor -= 0.20
+            when 2 then self.factor -= 0.15
+            when 4 then self.factor += 0.10
+          end
+        end
+        self.factor = [1.3, self.factor].max
+      end
+
+      def next_due(ease)
+        if ease == 1
+          return Time.now + DELAY
+        else
+          return Time.now + self.interval.day
+        end
+      end
+
+      def being_learnt?
+        self.interval < EASY_INTERVAL_MIN
+      end
+      
+    end
+    
+  end
+end
+
+::ActiveRecord::Base.send :include, Flashcard::Base

data/lib/generators/flashcard/USAGE

@@ -0,0 +1,5 @@
+Description:
+ Adds a migration file for the flashcard model
+ 
+Usage:
+  script/generate flashcard FLASHCARDMODEL

data/lib/generators/flashcard/flashcard_generator.rb

@@ -0,0 +1,25 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+class FlashcardGenerator < Rails::Generators::NamedBase
+  include Rails::Generators::Migration
+  
+  def self.source_root
+    File.join(File.dirname(__FILE__), 'templates')
+  end
+  
+  def self.next_migration_number(dirname)
+    Time.now.strftime("%Y%m%d%H%m%s")
+  end
+  
+  def install_flashcards
+    if File.exists?("#{destination_root}/db/schema.rb") && 
+       File.read("#{destination_root}/db/schema.rb") =~ /create_table \"#{table_name}\"/
+      migration_template("add_flashcards_fields_migration.rb","db/migrate/add_flashcards_fields.rb")
+    else
+      migration_template("create_flashcards_migration.rb","db/migrate/create_flashcards.rb")
+    end
+  end
+  
+  
+end

data/lib/generators/flashcard/templates/add_flashcards_fields_migration.rb

@@ -0,0 +1,27 @@
+class <%= @migration_class_name %> < ActiveRecord::Migration
+  def self.up
+    add_column :<%= table_name %>, :successive, :integer, :default => 0
+    add_column :<%= table_name %>, :repetitions,  :integer, :default => 0
+    add_column :<%= table_name %>, :yes_count,    :integer, :default => 0
+    add_column :<%= table_name %>, :no_count,     :integer, :default => 0
+    add_column :<%= table_name %>, :factor,       :float,   :default => 2.5
+    add_column :<%= table_name %>, :last_factor,  :float,   :default => 2.5
+    add_column :<%= table_name %>, :interval,     :integer, :default => 0
+    add_column :<%= table_name %>, :last_interval,:float,   :default => 0
+    add_column :<%= table_name %>, :due,          :datetime
+    add_column :<%= table_name %>, :combined_due, :integer, :default => 0
+  end
+
+  def self.down
+    remove_column :<%= table_name %>, :successive
+    remove_column :<%= table_name %>, :repetitions
+    remove_column :<%= table_name %>, :yes_count
+    remove_column :<%= table_name %>, :no_count
+    remove_column :<%= table_name %>, :factor
+    remove_column :<%= table_name %>, :last_factor
+    remove_column :<%= table_name %>, :interval
+    remove_column :<%= table_name %>, :last_interval
+    remove_column :<%= table_name %>, :due
+    remove_column :<%= table_name %>, :combined_due
+  end
+end

data/lib/generators/flashcard/templates/create_flashcards_migration.rb

@@ -0,0 +1,20 @@
+class <%= @migration_class_name %> < ActiveRecord::Migration
+  def self.up
+    create_table "<%= table_name %>" do |t|
+      t.column :successive,   :integer, :default => 0
+      t.column :repetitions,  :integer, :default => 0
+      t.column :yes_count,    :integer, :default => 0
+      t.column :no_count,     :integer, :default => 0
+      t.column :factor,       :float,   :default => 2.5
+      t.column :last_factor,  :float,   :default => 2.5
+      t.column :interval,     :integer, :default => 0
+      t.column :last_interval,:float,   :default => 0
+      t.column :due,          :datetime
+      t.column :combined_due, :integer, :default => 0
+    end
+  end
+
+  def self.down
+    drop_table "<%= table_name %>"
+  end
+end

data/tasks/acts_as_flashcard_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :acts_as_flashcard do
+#   # Task goes here
+# end

data/test/acts_as_flashcard_test.rb

@@ -0,0 +1,130 @@
+require File.dirname(__FILE__) + '/test_helper.rb'
+
+$:.unshift File.dirname(__FILE__) + "/../lib"
+#require File.dirname(__FILE__) + "/../init"
+
+ActiveRecord::Base.establish_connection(:adapter => "sqlite3", :database => ":memory:")
+ActiveRecord::Migration.verbose = false
+
+def setup_db
+  ActiveRecord::Schema.define(:version => 1) do
+    create_table :cards do |t|
+      t.column :successive, :integer, :default => 0
+      t.column :repetitions, :integer, :default => 0
+      t.column :yes_count, :integer, :default => 0
+      t.column :no_count, :integer, :default => 0
+      t.column :factor, :float, :default => 2.5
+      t.column :last_factor, :float, :default => 2.5
+      t.column :interval, :integer, :default => 0
+      t.column :last_interval, :float, :default => 0
+      t.column :due, :datetime
+      t.column :combined_due, :integer, :default => 0
+      t.column :created_at, :datetime      
+      t.column :updated_at, :datetime
+    end
+  end
+end
+
+def teardown_db
+  ActiveRecord::Base.connection.tables.each do |table|
+    ActiveRecord::Base.connection.drop_table(table)
+  end
+end
+
+class Card < ActiveRecord::Base
+  acts_as_flashcard
+end
+
+
+class ActsAsFlashcardTest < Test::Unit::TestCase
+  
+  def setup
+     setup_db
+   end
+
+   def teardown
+     teardown_db
+   end
+  
+  def test_due_date_updated_after_correct_answer
+    card = Card.create
+    due_before = card.due
+    card.answered!(4)
+    assert_equal (card.due > due_before), true
+  end
+  
+  def test_factor_should_increase_when_answered_right
+    card = Card.create(:repetitions => 5)
+    factor_before = card.factor
+    card.answered!(4)
+    assert_equal card.factor, factor_before + 0.10
+  end
+  
+  def test_factor_should_decrease_when_answered_wrong_if_not_learnt
+    card = Card.create(:interval => 7.5)
+    factor_before = card.factor
+    card.answered!(1)
+    assert_equal card.factor, factor_before - 0.20
+  end
+  
+  def test_should_return_the_average_actor
+    [1,2,3,4,5].each {|i| Card.create(:factor => i)}
+    card = Card.create
+    avg = card.__send__(:average_factor)
+    assert_equal avg, 3
+  end
+  
+  def test_when_answered_0_no_count_should_increase
+    card = Card.create(:repetitions => 3, :successive => 2, :no_count => 1, :yes_count => 3)
+    card.answered!(0)
+    assert_equal card.repetitions, 4
+    assert_equal card.successive, 0
+    assert_equal card.no_count, 2
+    assert_equal card.yes_count, 3
+  end
+  
+  def test_when_answered_2_yes_count_should_increase
+    card = Card.create(:repetitions => 3, :successive => 2, :no_count => 1, :yes_count => 3)
+    card.answered!(2)
+    assert_equal card.repetitions, 4
+    assert_equal card.successive, 3
+    assert_equal card.no_count, 1
+    assert_equal card.yes_count, 4
+  end
+  
+  def test_update_increase_combined_due
+    card = Card.create()
+    combined_due_before = card.combined_due
+    card.answered!(2)
+    assert card.combined_due > combined_due_before
+    combined_due_before = card.combined_due
+    card.answered!(4)
+    assert card.combined_due > combined_due_before
+    combined_due_before = card.combined_due
+    card.answered!(3)
+    assert card.combined_due < combined_due_before
+    combined_due_before = card.combined_due
+    card.answered!(2)
+    assert card.combined_due < combined_due_before
+  end
+  
+  def test_increase_interval_when_right
+    card = Card.create()
+    card.answered!(2)
+    card.answered!(2)
+    interval_before = card.interval
+    card.answered!(4)
+    card.answered!(4)
+    assert card.interval > interval_before
+  end
+  
+  def test_decrease_interval_when_wrong
+    card = Card.create()
+    card.answered!(2)
+    card.answered!(4)
+    interval_before = card.interval
+    card.answered!(1)
+    assert card.interval >= interval_before
+  end
+  
+end

data/test/flashcards_migration_generator_test.rb

@@ -0,0 +1,49 @@
+require File.dirname(__FILE__) + '/test_helper.rb'
+#require 'rails/generators'
+require 'generators/flashcard/flashcard_generator'
+
+class MigrationGeneratorTest < Test::Unit::TestCase
+  
+  def test_install_flashcard
+    FlashcardGenerator.start(["some_name_nobody_is_likely_to_ever_use_in_a_real_migration"], :destination_root => @destination)
+    new_file = (file_list - @original_files).first
+    assert_match /create_flashcards/, new_file
+    assert_match /create_table :some_name_nobody_is_likely_to_ever_use_in_a_real_migrations do |t|/, File.read(new_file)
+  end
+  
+  def test_add_flashcard_fields
+    create_schema_file
+    FlashcardGenerator.start(["some_name_nobody_is_likely_to_ever_use_in_a_real_migration"], :destination_root => @destination)
+    new_file = (file_list - @original_files).first
+    assert_match /add_flashcards_fields/, new_file
+    assert_match /add_column :some_name_nobody_is_likely_to_ever_use_in_a_real_migrations/, File.read(new_file)
+  end
+  
+  def setup
+    @destination = File.join('tmp', 'test_app')
+    @source = FlashcardGenerator.source_root
+    @original_files = file_list
+  end
+  
+  def teardown
+    FileUtils.rm_rf(@destination)
+  end
+  
+  private
+    
+  def file_list
+    Dir.glob(File.join(@destination, "db", "migrate", "*"))
+  end
+  
+  def create_schema_file
+    FileUtils.mkdir_p(@destination)
+    Dir.mkdir(File.join(@destination, "db"))
+    File.open(File.join(@destination, "db", "schema.rb"), 'w') do |f|
+      f.write("ActiveRecord::Schema.define(:version => 20100201214414) do\n")
+      f.write("\tcreate_table \"some_name_nobody_is_likely_to_ever_use_in_a_real_migrations\", :force => true do |t|\n")
+      f.write("\t\tt.integer  \"user_id\"\n")
+      f.write("\tend\nend")
+    end
+  end
+  
+end

data/test/test_helper.rb

@@ -0,0 +1,21 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'test/unit'
+# require 'shoulda'
+require 'active_record'
+require 'sqlite3'
+
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'acts_as_flashcard'
+
+class Test::Unit::TestCase
+end

data/uninstall.rb

@@ -0,0 +1 @@
+# Uninstall hook code here