srs 0.1.1

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/LICENCE.md

@@ -0,0 +1,22 @@
+Copyright (c) 2012, Daniel P. Wright
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,292 @@
+srs
+===
+
+A Spaced Repetition System is a study tool which works by spacing out exercises
+so as to learn in the most efficient manner possible.  Further information can
+be found at the following Wikipedia pages:
+
+ * [Spacing Effect][1]
+ * [Forgetting Curve][2]
+ * [Spaced Repetition][3]
+
+`srs` is a command-line based implementation of the spaced repetition system.  It
+is designed to be highly extensible and to promote the sharing of data for study
+by others.
+
+Installation
+------------
+
+`srs` is distributed as a Gem.  Make sure you have Ruby and RubyGems installed,
+and then type:
+
+    $ gem install srs
+
+Usage
+-----
+
+This first release of `srs` is an _alpha_ release -- it is functionally
+complete, but the user interface is in its very early stages, documentation is
+lacking, and there may be bugs.  With that in mind, read on...
+
+### Initialising a workspace
+
+The first thing you will want to do once you've installed `srs` is to initialise
+a _workspace_.  This is where all the data required for one set of material you
+want to study reside.  It is generally a good idea to group related items
+together -- for example, I have a workspace for Japanese vocabulary, another for
+kanji, and another for poetry and quotations which I'd like to remember.
+
+How you think the things you want to learn should be distributed is a
+personal choice, and you should consider for yourself what will work best for
+you.  For example, some people might prefer to put the Japanese vocabulary and
+the kanji together in one workspace -- that is fine.  Merging or splitting
+workspaces at a later stage is relatively easy, so do experiment!
+
+To initialise a workspace, create a directory and run the following command
+inside it:
+
+    $ srs init
+
+### Adding an exercise
+
+In `srs`, a single item of practice or revision is called an _exercise_.  These
+can be anything -- a flashcard-style question-and-answer, or a more interactive
+form or practice.  What a particular exercise entails depends entirely on what
+it is you want to practice, and for that reason `srs` introduces the concept of
+_models_.
+
+A model is a Ruby class which defines how an exercise is performed.  `srs` comes
+packaged with the most basic kind of model, a flashcard, which is distributed
+under the name `SimpleFlashcard`.  You can create your own models, but for now
+we'll make use of the `SimpleFlashcard` model to get something up and running
+quickly.
+
+A `SimpleFlashcard` exercise comes in two parts:
+
+ * The _data_, which usually contains the actual thing you want to test
+ * The _exercise specification_, which determines how to use that data.
+
+This separation allows you to use the same data for multiple exercises.  In this
+example, we're going to create a "Production" and a "Recognition" card for the
+Japanese word, 勉強, which means "study".
+
+The first thing we need to do is create the DataFile.  `SimpleFlashcard`
+currently expects its data to consist of a series of key-value pairs, separated
+by a colon.  Currently multi-line fields are not supported, though this will
+change in a future version.  Run the following from inside the workspace
+directory you created (The ^D at the end signifies pressing Control-D to send
+the end-of-file marker to `srs`):
+
+    $ srs insert-into data
+    Word: 勉強
+    Pronunciation (Hiragana): べんきょう
+    Pronunciation (Romaji): Benkyou
+    Meaning: Study
+    ^Dc13d1e790ef5e8ced8c96a37a6d014f08ddcb3af
+
+You should see the output after pressing ^D as above,
+`c13d1e790ef5e8ced8c96a37a6d014f08ddcb3af`.  The string itself may be different,
+but it will be a long string of hexadecimal digits.  The `insert-into` command
+reads data in from STDIN and outputs an ID which can be used by other `srs`
+commands to access that data.
+
+We now have data containing four fields related to the word.  We can combine
+these fields in a variety of ways to generate a number of exercises.  Here we'll
+generate two; one to produce the English meaning when shown the word and the
+pronunciation; the other to produce the Japanese word when shown the English.
+Input the following, substituting the value passed into the _Data_ field with
+whatever was output from the previous command:
+
+    $ srs insert-into exercises
+    Data: c13d1e790ef5e8ced8c96a37a6d014f08ddcb3af
+    Model: SimpleFlashcard
+
+    [Word]
+    [Pronunciation (Hiragana)]
+    ---
+    [Meaning]
+    ^D884bd92624411f5bb42ff9abdf84c3e09ba00cab
+
+Note the blank line between the set of key-value pairs and the text below.
+`SimpleFlashcard` expects a series of headers, followed by a blank line,
+followed by some metadata.  The metadata is in two parts: the question, which is
+everything before the "---" string, and the answer, which is everything that
+comes after it.  Any words within square brackets are substituted with the value
+of their corresponding field in the data.
+
+As with the previous command, this command outputs an ID once it has completed.
+Remember this; you will need it later.  Let's add the second exercise:
+
+    $ srs insert-into exercises
+    Data: c13d1e790ef5e8ced8c96a37a6d014f08ddcb3af
+    Model: SimpleFlashcard
+
+    [Meaning]
+    ---
+    [Word]
+    ^Dd930b3fce3d2f988758c7088ea77d9075b8c82bf
+
+As you can see, this is just the same exercise, with the question and answer
+reversed.  Also, we are ignoring pronunciation for this one.
+
+You will notice, neither of these exercises make use of the "Pronunciation (Romaji)"
+field.  The truth is, I don't much like Romaji.  But it is entirely reasonable
+to add fields you won't use as part of the exercises to the data; you may choose
+to create exercises which make use of that data later, or you may just want to
+look it up (for example, you could include the link to a URL where you
+discovered the information).
+
+### Scheduling an exercise
+
+The next thing we must do is schedule the exercises we've just created.  If we
+don't do this, they will never enter the `srs` scheduling system, and so they
+will simply sit there unasked!
+
+There have been a number of spaced repetition algorithms developed over the
+years, perhaps the most famous of which are the [Pimsleur Graduated Recall][4]
+and [SuperMemo 2][5] algorithms.  As with models, `srs` allows you to define
+your own custom spacing algorithm by creating a _scheduler_.  The base
+distribution comes with probably the most popular spacing algorithm
+pre-installed, SuperMemo 2.  We'll use that one.
+
+Type the following, substituting the two ids with the ones returned when you
+inserted the two exercises:
+
+    $ srs schedule -s SuperMemo2 884bd92624411f5bb42ff9abdf84c3e09ba00cab
+    schedule/pending/20120708003132.386
+    $ srs schedule -s SuperMemo2 d930b3fce3d2f988758c7088ea77d9075b8c82bf
+    schedule/pending/20120708003149.754
+
+### Doing some reps -- new exercises
+
+Now that you've scheduled some exercises, you're ready to do some reps.  Let's
+ask `srs` what the next new exercise is which is available for learning:
+
+    $ srs next-new
+    20120708003132.386
+
+The ID of the first exercise you scheduled above should be output.  In order to
+actually test ourselves, we'll need the ID of the exercise we want to run.  We
+can get this from the `Exercise` field stored in the schedule (as always,
+remembering to substitute the example ID below with your own):
+
+    $ srs get-field exercise 20120708003132.386
+    884bd92624411f5bb42ff9abdf84c3e09ba00cab
+
+An exercise ID will be output, which we can feed straight into `do-exercise`:
+
+    $ srs do-exercise a884bd92624411f5bb42ff9abdf84c3e09ba00cab
+    勉強
+    べんきょう
+    >
+
+At this point you are given a prompt.  Let's enter the correct answer, "Study",
+and see what happens:
+
+    > Study
+    Correct.
+    You scored: 1.0
+
+Scores in `srs` are normalised from 0-1, so 1.0 is a full score.  Well done!  We
+still need to enter this into the scheduler so that it knows when next to repeat
+the exercise.  Enter the following to reschedule the exercise.  The ID is the
+_schedule_ ID, not the one for the exercise:
+
+    $ srs reschedule 20120708003132.386 1.0
+    Exercise rescheduled for 2012-07-09 00:00:00 +0900
+
+Excellent!  We'll see this exercise again tomorrow.
+
+It's actually possible to wrap up most of the above in a single line.  The
+following assumes you use a `bash` shell, though other shells may be similar:
+
+    $ SCHEDULE=$(srs next-new); EXERCISE=$(srs get-field exercise $SCHEDULE); srs do-exercise $EXERCISE
+
+This time we'll try answering the question incorrectly:
+
+    Study
+    > 遊ぶ
+    勉強
+    Was your answer: [h] Correct, [j] Close, [k] Wrong, or [l] Very Wrong?
+    > l
+    You scored: 0.0
+
+When you enter a wrong answer, the `SimpleFlashcard` doesn't attempt to judge
+for itself whether or not you were close to the write answer.  Instead, it shows
+you the correct answer and lets you specify how close you thought you were.  In
+this case, we were miles off, so we selected 'l', to fail the exercise
+completely.  Now to reschedule the exercise:
+
+    $ srs reschedule $SCHEDULE 0.0
+    Exercise rescheduled for 2012-07-09 00:00:00 +0900
+    Exercise failed; marked for repetition
+
+Since we failed the exercise, the scheduler has marked it for repetition.  This
+means that once we've finished all our scheduled reps for the day, we will be
+presented with this exercise (and any other failed exercise), to try again until
+we have managed to pass them.  Note that only the first attempt affects the
+interval; subsequent repetitions are simply practice.
+
+### Practice makes perfect!  Repeating exercises
+
+For the most part, you're going to be practicing exercises you've already done
+once.  The flow for this is very similar to the above, except that instead of
+`next-new` we use the `next-due` command.
+
+Before we can use this command, however, we need to update the srs queue:
+
+    $ srs queue
+
+This command tells `srs` to look through the schedules and determine which
+exercises are due for practice.  We can now use `next-due` similarly to the
+way we practised new exercises in the previous section:
+
+    $ SCHEDULE=$(srs next-due); EXERCISE=$(srs get-field exercise $SCHEDULE); srs do-exercise $EXERCISE
+    Study
+    > 勉強
+    Correct.
+    You scored: 1.0
+
+    $ srs reschedule $SCHEDULE 1.0
+    Exercise rescheduled for 2012-07-09 00:00:00 +0900
+
+In this case, since the exercise hard already been scheduled and was simply a
+repetition of a failed exercise, the date matched that which was output
+previously.
+
+Finally, we can confirm that there are no more exercises left to practice:
+
+    $ srs queue
+    $ srs next-due
+
+Contributing
+------------
+
+`srs` is in very early stages and as such there is a _lot_ of work still to do
+on it.  Contributions are welcome!
+
+To contribute, fork the project on github and send me a pull request, or email
+me a patch.  Please bear the following in mind when making contributions:
+
+ * Try and keep individual commits small and self-contained.  If I feel like
+   there is too much going on in a single commit, I may ask you to split it up
+   into multiple commits.
+ * Please write clear, descriptive commit messages.  These should be formatted
+   with a title of `<=` 50 characters, and body text wrapped at 72 characters.
+   I am quite particular about this.
+ * I come from a pretty heavy C++ background.  Ruby style corrections and
+   improvements are very much appreciated!  Please be nice about it.
+
+Copyright
+---------
+
+Copyright (c) 2012 Daniel P. Wright.
+
+This software is released under the Simplified BSD Licence.  See LICENCE.md for
+further details.
+
+[1]: http://en.wikipedia.org/wiki/Spacing_effect
+[2]: http://en.wikipedia.org/wiki/Forgetting_curve
+[3]: http://en.wikipedia.org/wiki/Spaced_repetition
+[4]: http://en.wikipedia.org/wiki/Graduated_interval_recall
+[5]: http://www.supermemo.com/english/ol/sm2.htm

data/bin/srs

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+begin
+  require 'srs/cli'
+rescue LoadError
+  require 'rubygems'
+  require 'srs/cli'
+end
+
+exit SRS::CLI.run!(*ARGV)
+

data/lib/srs.rb

@@ -0,0 +1,2 @@
+require 'srs/workspace'
+require 'srs/version'

data/lib/srs/cli.rb

@@ -0,0 +1,43 @@
+require 'srs/cli/init'
+require 'srs/cli/help'
+require 'srs/cli/insert-into'
+require 'srs/cli/schedule'
+require 'srs/cli/do-exercise'
+require 'srs/cli/reschedule'
+require 'srs/cli/queue'
+require 'srs/cli/next-due'
+require 'srs/cli/next-new'
+require 'srs/cli/get-field'
+require 'srs/cli/cat'
+
+module SRS
+	class CLI
+		class << self
+			COMMANDS = { "init"            => :Init,
+			             "insert-into"     => :InsertInto,
+			             "schedule"        => :Schedule,
+			             "do-exercise"     => :DoExercise,
+			             "reschedule"      => :Reschedule,
+			             "queue"           => :Queue,
+			             "next-due"        => :NextDue,
+			             "next-new"        => :NextNew,
+			             "get-field"       => :GetField,
+			             "cat"             => :Cat,
+			             "help"            => :Help }.freeze
+
+			def cmd_to_symbol(command)
+				return COMMANDS[command]
+			end
+
+			def run!(*arguments)
+				command = cmd_to_symbol(arguments.shift)
+				if command
+					return SRS::CLI.const_get(command).new.run!(arguments)
+				else
+					return SRS::CLI::Help.new.run!([])
+				end
+			end
+		end
+	end
+end
+

data/lib/srs/cli/cat.rb

@@ -0,0 +1,39 @@
+module SRS
+	class CLI
+		class Cat
+			VALID_SECTIONS = ["data", "exercises"].freeze
+			def run!(arguments)
+				if not SRS::Workspace.initialised? then
+					puts "Current directory is not an SRS Workspace"
+					return 3
+				end
+
+				sha1 = arguments.shift
+				sha1_start = sha1[0..1]
+				sha1_rest = sha1[2..-1]
+
+				VALID_SECTIONS.each do |section|
+					datafile = "#{section}/#{sha1_start}/#{sha1_rest}"
+					if File.exists?(datafile) then
+						contents = File.open(datafile, "r"){ |file| file.read }
+						puts contents
+
+						return 0
+					end
+				end
+
+				puts "No content with that ID exists"
+				return 4
+			end
+
+			def help()
+				puts <<-EOF
+srs cat <id>
+
+Outputs the content matching <id>
+					EOF
+			end
+		end
+	end
+end
+

data/lib/srs/cli/do-exercise.rb

@@ -0,0 +1,73 @@
+module SRS
+	class CLI
+		class DoExercise
+			def run!(arguments)
+				if not SRS::Workspace.initialised? then
+					puts "Current directory is not an SRS Workspace"
+					return 3
+				end
+
+				sha1 = arguments.shift
+				sha1_start = sha1[0..1]
+				sha1_rest = sha1[2..-1]
+
+				datafile = "exercises/#{sha1_start}/#{sha1_rest}"
+
+				if not File.exists?(datafile) then
+					puts "No content with that ID exists"
+					return 4
+				end
+
+				headers = {}
+				metadata = ""
+				File.open(datafile, "r") do |file|
+					while( line = file.gets() ) do
+						if line.strip.empty? then
+							break
+						end
+
+						key, *val = line.split(':').map{|e| e.strip}
+						headers[key] = val.join(':')
+					end
+					metadata = file.read
+				end
+
+				runModel(sha1, headers, metadata)
+			end
+
+			def runModel(sha1, headers, metadata)
+				if not headers.has_key?("Model") then
+					puts "Exercise #{sha1} has no model!\n"
+					return nil
+				end
+
+				modelclass = headers.delete("Model")
+
+				begin
+					require "./models/#{modelclass}"
+				rescue LoadError
+					begin
+						require "srs/models/#{modelclass}"
+					rescue LoadError
+						puts "Couldn't find model #{modelclass}."
+						return nil
+					end
+				end
+
+				model = SRS::Models.const_get(modelclass.to_sym).new
+				score = model.run(headers, metadata)
+
+				return score
+			end
+
+			def help()
+				puts <<-EOF
+srs do-exercise <id>
+
+Runs the exercise defined in <id>
+					EOF
+			end
+		end
+	end
+end
+

data/lib/srs/cli/get-field.rb

@@ -0,0 +1,56 @@
+module SRS
+	class CLI
+		class GetField
+			def run!(arguments)
+				if not SRS::Workspace.initialised? then
+					puts "Current directory is not an SRS Workspace"
+					return 3
+				end
+
+				field = arguments.shift
+				id = arguments.shift
+
+				is_schedule = (id =~ /\d{14}\.\d{3}/)
+
+				filename = ""
+				if is_schedule then
+					filename = "schedule/#{id}"
+					filename = "schedule/pending/#{id}" if not File.exists?(filename)
+				else
+					filename = "exercises/#{id}"
+				end
+
+				if not File.exists?(filename) then
+					puts "No content with that ID exists"
+					return 4
+				end
+
+				File.open(filename, "r") do |file|
+					while( line = file.gets() ) do
+						if line.strip.empty? then
+							break
+						end
+
+						key, *val = line.split(':').map{|e| e.strip}
+						if key.casecmp(field) == 0 then
+							puts val.join(':')
+							return 0
+						end
+					end
+				end
+
+				puts "Content #{id} does not contain field \"#{field}\"."
+				return 4
+			end
+
+			def help()
+				puts <<-EOF
+srs get-field <field-name> <content-id>
+
+Returns the value of the field <field-name> from content <content-id>
+					EOF
+			end
+		end
+	end
+end
+

data/lib/srs/cli/help.rb

@@ -0,0 +1,44 @@
+require 'srs/cli'
+
+module SRS
+	class CLI
+		class Help
+			def run!(arguments)
+				if arguments.empty?
+					summary
+				else
+					command = SRS::CLI::cmd_to_symbol(arguments.first)
+					if command
+						SRS::CLI.const_get(command).new.help()
+					else
+						summary
+					end
+				end
+				return 0
+			end
+
+			def help()
+			end
+
+			def summary()
+				puts "Usage: srs <command> [args]"
+				puts
+				puts "Available commands are:"
+				puts "    init          Initialise an SRS workspace"
+				puts "    insert-into   Insert data into the workspace"
+				puts "    schedule      Schedule an exercise"
+				puts "    do-exercise   Perform a rep on an exercise"
+				puts "    reschedule    Update an exercise schedule based on score"
+				puts "    queue         Queue due exercises"
+				puts "    next-due      Retrieve the next due exercise from the queue"
+				puts "    next-new      Retrieve the next available untested exercise"
+				puts "    get-field     Retrieve a field by name from a schedule or exercise"
+				puts "    cat           Output data contained within the workspace"
+				puts
+				puts "See 'srs help <command>' for more information on a specific command."
+			end
+		end
+	end
+end
+
+

data/lib/srs/cli/init.rb

@@ -0,0 +1,58 @@
+require 'optparse'
+require 'srs/workspace'
+
+module SRS
+	class CLI
+		class Init
+			def initialize
+				@options = {}
+				@opts = OptionParser.new do |o|
+					o.banner = <<-EOF.gsub /^\s+/, ""
+						srs init [options] [dirname]
+
+						Initialises a workspace in directory [dirname].  A `.srs/` folder will be
+						created containing the default configuration files.  A skeleton directory
+						structure may also be created (this is undecided as yet).
+
+						If no [dirname] is passed, uses the current directory.
+						EOF
+
+					o.on('-f', '--force', 'Initialise workspace even if the directory is not empty') do
+						@options[:force] = true
+					end
+				end
+			end
+
+			def run!(arguments)
+				begin
+					@opts.parse!(arguments)
+					@options[:dir_name] = arguments.shift
+				rescue OptionParser::InvalidOption => e
+					@options[:invalid_argument] = e.message
+				end
+
+				if @options[:dir_name] == nil then
+					@options[:dir_name] = "./"
+				end
+
+				begin
+					SRS::Workspace.create(@options[:dir_name], @options[:force])
+				rescue SRS::Workspace::AlreadyInitialisedError => e
+					puts "SRS is already initialised in #{@options[:dir_name]}."
+					return 2
+				rescue SRS::Workspace::FolderNotEmptyError => e
+					puts "The current folder is not empty!"
+					puts "Run 'srs init --force' to initialise in this folder anyway."
+					return 1
+				end
+
+				0
+			end
+
+			def help()
+				puts @opts
+			end
+		end
+	end
+end
+

data/lib/srs/cli/insert-into.rb

@@ -0,0 +1,48 @@
+require 'fileutils'
+require 'digest/sha1'
+
+module SRS
+	class CLI
+		class InsertInto
+			VALID_SECTIONS = ["data", "exercises"].freeze
+			def run!(arguments)
+				if not SRS::Workspace.initialised? then
+					puts "Current directory is not an SRS Workspace"
+					return 3
+				end
+
+				section = arguments.shift()
+				if section == nil or !VALID_SECTIONS.include?(section) then
+					help()
+					return 4
+				end
+
+				data = STDIN.read()
+				sha1 = Digest::SHA1.hexdigest data
+				sha1_start = sha1[0..1]
+				sha1_rest = sha1[2..-1]
+				datafile = "#{section}/#{sha1_start}/#{sha1_rest}"
+
+				if not File.exists?(datafile) then
+					FileUtils::mkdir_p("#{section}/#{sha1_start}")
+					File.open(datafile, 'w') {|f| f.write(data)}
+				end
+
+				puts sha1
+
+				return 0
+			end
+
+			def help()
+				puts <<-EOF
+srs insert-into <section>
+
+Reads the contents from stdin and inserts it into the appropriate section in the
+workspace.  <section> can be one of "data", "exercise", or "schedule".  Returns
+the id used to access that exercise.
+				EOF
+			end
+		end
+	end
+end
+

data/lib/srs/cli/next-due.rb

@@ -0,0 +1,44 @@
+module SRS
+	class CLI
+		class NextDue
+			def run!(arguments)
+				if not SRS::Workspace.initialised? then
+					puts "Current directory is not an SRS Workspace"
+					return 3
+				end
+
+				ws = SRS::Workspace.new
+
+				schedule = nil
+				if File.exists? "#{ws.dotsrs}/QUEUED" then
+					File.open("#{ws.dotsrs}/QUEUED", "r") do |queued_file|
+						schedule = queued_file.gets
+					end
+				end
+
+				if schedule == nil then
+					if File.exists? "#{ws.dotsrs}/REPEAT" then
+						File.open("#{ws.dotsrs}/REPEAT", "r") do |repeat_file|
+							schedule = repeat_file.gets
+						end
+					end
+				end
+
+				if not schedule == nil then
+					puts File.basename schedule
+				end
+
+				return 0
+			end
+
+			def help()
+				puts <<-EOF
+srs next-due
+
+Prints out the id of the next due schedule.  Prints nothing if nothing is due.
+					EOF
+			end
+		end
+	end
+end
+

data/lib/srs/cli/next-new.rb

@@ -0,0 +1,29 @@
+module SRS
+	class CLI
+		class NextNew
+			def run!(arguments)
+				if not SRS::Workspace.initialised? then
+					puts "Current directory is not an SRS Workspace"
+					return 3
+				end
+
+				new_schedules = Dir["schedule/pending/*"].sort
+				if not new_schedules.empty?
+					puts File.basename new_schedules.first
+				end
+
+				return 0
+			end
+
+			def help()
+				puts <<-EOF
+srs next-new
+
+Prints out the id of the next untested schedule.  Prints nothing if there are no
+pending schedules.
+					EOF
+			end
+		end
+	end
+end
+

data/lib/srs/cli/queue.rb

@@ -0,0 +1,68 @@
+require 'date'
+
+module SRS
+	class CLI
+		class Queue
+			def run!(arguments)
+				if not SRS::Workspace.initialised? then
+					puts "Current directory is not an SRS Workspace"
+					return 3
+				end
+
+				queued = {}
+				repeat = []
+
+				Dir["schedule/*"].each do |filename|
+					next if File.directory?(filename)
+
+					schedule = {}
+					File.open(filename, "r") do |file|
+						while( line = file.gets() ) do
+							if line.strip.empty? then
+								break
+							end
+
+							key, *val = line.split(':').map{|e| e.strip}
+							schedule[key] = val.join(':')
+						end
+
+						if( schedule["Repeat"] == "true" ) then
+							repeat << filename
+						else
+							due = DateTime.parse(schedule["Due"])
+							if( due < DateTime.now ) then
+								queued[filename] = due
+							end
+						end
+					end
+				end
+
+				ws = SRS::Workspace.new
+
+				File.open("#{ws.dotsrs}/QUEUED", "w") do |queued_file|
+					queued.sort_by{ |key, value| value }
+					queued.each do |filename, due|
+						queued_file.puts filename
+					end
+				end
+
+				File.open("#{ws.dotsrs}/REPEAT", "w") do |repeat_file|
+					repeat.each do |filename|
+						repeat_file.puts filename
+					end
+				end
+
+				return 0
+			end
+
+			def help()
+				puts <<-EOF
+srs queue
+
+Queues exercises for review.
+					EOF
+			end
+		end
+	end
+end
+

data/lib/srs/cli/reschedule.rb

@@ -0,0 +1,94 @@
+require 'fileutils'
+
+module SRS
+	class CLI
+		class Reschedule
+			def run!(arguments)
+				if not SRS::Workspace.initialised? then
+					puts "Current directory is not an SRS Workspace"
+					return 3
+				end
+
+				schedule_id = arguments.shift
+				score = arguments.shift.to_f
+
+				is_new = false;
+				schedulefile = "schedule/#{schedule_id}"
+
+				if not File.exists?(schedulefile) then
+					schedulefile = "schedule/pending/#{schedule_id}"
+					is_new = true
+					if not File.exists?(schedulefile) then
+						puts "No content with that ID exists"
+						return 4
+					end
+				end
+
+				headers = {}
+				File.open(schedulefile, "r") do |file|
+					while( line = file.gets() ) do
+						if line.strip.empty? then
+							break
+						end
+
+						key, *val = line.split(':').map{|e| e.strip}
+						headers[key] = val.join(':')
+					end
+				end
+
+				if not headers.has_key?("Scheduler") then
+					puts "Schedule #{schedule_id} has no scheduler!\n"
+					return 6
+				end
+
+				exercise = headers.delete("Exercise")
+				schedulername = headers.delete("Scheduler")
+
+				scheduler = getScheduler(schedulername)
+				headersOut = is_new ? scheduler.first_rep(score) : scheduler.rep(score, headers)
+
+				FileUtils.rm_rf( schedulefile )
+
+				fileOut = "schedule/#{schedule_id}"
+				File.open(fileOut, "w") do |file|
+					file.puts "Exercise: #{exercise}"
+					file.puts "Scheduler: #{schedulername}"
+					headersOut.each do |key, value|
+						file.puts "#{key}: #{value.to_s}"
+					end
+				end
+
+				puts "Exercise rescheduled for #{headersOut["Due"]}"
+				puts "Exercise failed; marked for repetition" if headersOut["Repeat"]
+
+				return 0
+			end
+
+			def getScheduler(schedulername)
+				begin
+					require "./schedulers/#{schedulername}"
+				rescue LoadError
+					begin
+						require "srs/schedulers/#{schedulername}"
+					rescue LoadError
+						puts "Couldn't find scheduler #{schedulername}."
+						return nil
+					end
+				end
+
+				SRS::Schedulers.const_get(schedulername.to_sym).new
+			end
+
+			def help()
+				puts <<-EOF
+srs reschedule <id> <score>
+
+Rescedules the exercise being set by schedule id according to the score
+supplied.  Makes use of the scheduler defined for that schedule.  The score
+passed in will typically be that returned from do-exercise.
+					EOF
+			end
+		end
+	end
+end
+

data/lib/srs/cli/schedule.rb

@@ -0,0 +1,69 @@
+require 'fileutils'
+
+module SRS
+	class CLI
+		class Schedule
+			def initialize
+				@options = {}
+				@opts = OptionParser.new do |o|
+					o.banner = <<-EOF.gsub /^\s+/, ""
+						srs schedule [options] <exercise>
+
+						Schedules an exercise.
+						EOF
+
+					o.on('-s', '--scheduler SCHEDULER_NAME', 'Specifies which scheduler to use') do |s|
+						@options[:scheduler] = s
+					end
+				end
+			end
+
+			def run!(arguments)
+				if not SRS::Workspace.initialised? then
+					puts "Current directory is not an SRS Workspace"
+					return 3
+				end
+
+				begin
+					@opts.parse!(arguments)
+					@options[:exercise] = arguments.shift()
+				rescue OptionParser::InvalidOption => e
+					@options[:invalid_argument] = e.message
+				end
+
+				if @options[:exercise] == nil then
+					help()
+					return 4
+				end
+
+				if @options[:scheduler] == nil then
+					puts "No scheduler specified."
+					return 5
+				end
+
+				t = Time.now
+				filename = "schedule/pending/#{t.strftime("%Y%m%d%H%M%S.%L")}"
+
+				if File.exists?(filename) then
+					puts "Cannot schedule two items within a millisecond.  Try again."
+					return 6
+				end
+
+				FileUtils::mkdir_p("schedule/pending")
+				File.open(filename, 'w') do |f|
+					f.puts "Exercise: #{@options[:exercise]}"
+					f.puts "Scheduler: #{@options[:scheduler]}"
+				end
+
+				puts filename
+
+				return 0
+			end
+
+			def help()
+				puts @opts
+			end
+		end
+	end
+end
+

data/lib/srs/models/SimpleFlashcard.rb

@@ -0,0 +1,85 @@
+require "stringio"
+
+module SRS
+	module Models
+		class SimpleFlashcard
+			def initialize()
+			end
+
+			def run(headers, metadata)
+				data = headers.delete("Data")
+
+				sha1_start = data[0..1]
+				sha1_rest = data[2..-1]
+
+				datafile = "data/#{sha1_start}/#{sha1_rest}"
+
+				if not File.exists?(datafile) then
+					puts "No content with that ID exists"
+					return 4
+				end
+
+				self.load(datafile)
+
+				score = 0.0
+				StringIO.open(metadata) do |metadata|
+					while( line = metadata.gets() ) do
+						break if line.strip == "---"
+						line.gsub!(/\[([^\]]+)\]/) { "#{@fields[$1]}" }
+						puts line
+					end
+					answer = metadata.read.strip.gsub!(/\[([^\]]+)\]/) { "#{@fields[$1]}" }
+
+					print "> "
+					attempt = STDIN.gets().strip
+
+					if( attempt == answer ) then
+						puts "Correct."
+						score = 1.0
+					else
+						puts answer
+
+						for i in 0..0
+							puts "Was your answer: [h] Correct, [j] Close, [k] Wrong, or [l] Very Wrong?"
+							print "> "
+
+							case STDIN.gets().strip
+							when "h"
+								score = 1.0
+							when "j"
+								score = 0.8
+							when "k"
+								score = 0.4
+							when "l"
+								score = 0.0
+							else
+								redo
+							end
+						end
+					end
+				end
+
+				puts "You scored: " + score.to_s
+
+				return score
+			end
+
+			def load(datafile)
+				@fields = {}
+				File.open(datafile, "r") do |file|
+					while( line = file.gets() ) do
+						if line.strip.empty? then
+							break
+						end
+
+						keyval = line.split(':').map{|e| e.strip}
+						key = keyval[0]
+						val = keyval[1]
+
+						@fields[key] = val
+					end
+				end
+			end
+		end
+	end
+end

data/lib/srs/schedulers/SuperMemo2.rb

@@ -0,0 +1,72 @@
+# Based on the SuperMemo 2 algorithm as described here:
+# http://www.supermemo.com/english/ol/sm2.htm
+require 'date'
+
+module SRS
+	module Schedulers
+		class SuperMemo2
+			DEFAULT_EF = 2.5
+			MIN_EF = 1.3
+			FIRST_INTERVAL = 1
+			SECOND_INTERVAL = 6
+			ITERATION_RESET_BOUNDARY = 3.0 / 5.0
+			REPEAT_BOUNDARY = 4.0 / 5.0
+
+			def initialize()
+			end
+
+			def first_rep(score)
+				fields = {
+					"Due"           => (Date.today + FIRST_INTERVAL).to_time,
+					"Repeat"        => score < REPEAT_BOUNDARY ? true : false,
+					"E-Factor"      => adjust_efactor(DEFAULT_EF, score),
+					"Interval"      => FIRST_INTERVAL,
+					"Iteration"     => 1
+				}
+
+				return fields
+			end
+
+			def rep(score, fields)
+				ef = fields["E-Factor"].to_f
+				interval = fields["Interval"].to_i
+				iteration = fields["Iteration"].to_i
+				repeat = (fields["Repeat"] == "true")
+
+				if not repeat then
+					iteration = 0 if score < ITERATION_RESET_BOUNDARY
+					case iteration
+					when 0
+						interval = FIRST_INTERVAL
+					when 1
+						interval = SECOND_INTERVAL
+					else
+						interval = adjust_interval(interval, ef)
+					end
+
+					ef = adjust_efactor(ef, score)
+				end
+
+				fields["Due"] = (Date.today + interval).to_time
+				fields["Repeat"] = score < REPEAT_BOUNDARY ? true : false
+				fields["E-Factor"] = ef
+				fields["Interval"] = interval
+				fields["Iteration"] = iteration + 1
+
+				return fields
+			end
+
+			def adjust_efactor(ef, score)
+				q = score * 5
+				adjusted_efactor = ef + (0.1-(5.0 - q) * (0.08 + (5.0 - q) * 0.02))
+
+				adjusted_efactor < MIN_EF ? MIN_EF : adjusted_efactor
+			end
+
+			def adjust_interval(interval, ef)
+				(interval * ef).round
+			end
+		end
+	end
+end
+

data/lib/srs/version.rb

@@ -0,0 +1,3 @@
+module SRS
+	VERSION = "0.1.0"
+end

data/lib/srs/workspace.rb

@@ -0,0 +1,46 @@
+require 'fileutils'
+
+module SRS
+	class Workspace
+		class AlreadyInitialisedError < StandardError
+		end
+		class FolderNotEmptyError < StandardError
+		end
+
+		attr_reader :root, :dotsrs
+
+		def initialize(dirname=".")
+			if not SRS::Workspace.initialised?(dirname) then return nil end
+			@root = dirname
+			@dotsrs = File.join(dirname,'.srs')
+			self
+		end
+
+		def self.create(dirname, force=false)
+			dotsrs_dir = File.join(dirname,'.srs/')
+
+			if( SRS::Workspace.initialised?(dirname) ) then
+				raise AlreadyInitialisedError
+				return nil
+			end
+
+			FileUtils.mkdir_p(dirname)
+
+			if( !force ) then
+				if( Dir.entries(dirname).length > 2 ) then
+					raise FolderNotEmptyError
+					return nil
+				end
+			end
+
+			Dir.mkdir(dotsrs_dir)
+			Dir.mkdir(File.join(dirname, "data"))
+
+			return SRS::Workspace.new(dirname)
+		end
+
+		def self.initialised?(dirname=".")
+			Dir.exists?(File.join(dirname,'.srs/'))
+		end
+	end
+end

data/srs.gemspec

@@ -0,0 +1,24 @@
+Gem::Specification.new do |s|
+	s.name         = 'srs'
+	s.version      = '0.1.1'
+	s.date         = '2011-07-07'
+	s.authors      = ["Daniel P. Wright"]
+	s.email        = 'dani@dpwright.com'
+	s.homepage     = 'https://github.com/dpwright/srs'
+	s.license      = 'Simplified BSD'
+
+	s.summary      = "A highly extensible command-line spaced repetition system"
+	s.description  = <<-EOF
+	A Spaced Repetition System is a study tool which works by spacing out
+	exercises so as to learn in the most efficient manner possible.
+
+	srs is a command-line based implementation of the spaced repetition system.
+	It is designed to be highly extensible and to promote the sharing of data
+	for study by others.
+	EOF
+
+	s.files            = `git ls-files`.split("\n").reject {|path| path =~ /\.gitignore$/ }
+	s.executables      = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+	s.rdoc_options     = ["--charset=UTF-8"]
+	s.require_path     = "lib"
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: srs
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+  prerelease: 
+platform: ruby
+authors:
+- Daniel P. Wright
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-07-07 00:00:00.000000000 Z
+dependencies: []
+description: ! "\tA Spaced Repetition System is a study tool which works by spacing
+  out\n\texercises so as to learn in the most efficient manner possible.\n\n\tsrs
+  is a command-line based implementation of the spaced repetition system.\n\tIt is
+  designed to be highly extensible and to promote the sharing of data\n\tfor study
+  by others.\n"
+email: dani@dpwright.com
+executables:
+- srs
+extensions: []
+extra_rdoc_files: []
+files:
+- .rspec
+- LICENCE.md
+- README.md
+- bin/srs
+- lib/srs.rb
+- lib/srs/cli.rb
+- lib/srs/cli/cat.rb
+- lib/srs/cli/do-exercise.rb
+- lib/srs/cli/get-field.rb
+- lib/srs/cli/help.rb
+- lib/srs/cli/init.rb
+- lib/srs/cli/insert-into.rb
+- lib/srs/cli/next-due.rb
+- lib/srs/cli/next-new.rb
+- lib/srs/cli/queue.rb
+- lib/srs/cli/reschedule.rb
+- lib/srs/cli/schedule.rb
+- lib/srs/models/SimpleFlashcard.rb
+- lib/srs/schedulers/SuperMemo2.rb
+- lib/srs/version.rb
+- lib/srs/workspace.rb
+- srs.gemspec
+homepage: https://github.com/dpwright/srs
+licenses:
+- Simplified BSD
+post_install_message: 
+rdoc_options:
+- --charset=UTF-8
+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 highly extensible command-line spaced repetition system
+test_files: []