quiz_master 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f36424722d7858fc0043388e0bcef810ddf656e4
-  data.tar.gz: 64f08b1237efe768726c9074273fda972c751680
+  metadata.gz: 8d62671e4c95a71dec14536a930d4ac5c10797e3
+  data.tar.gz: 96e9ba4259c1ba1a4b07dea794d2d2839e3d68ae
 SHA512:
-  metadata.gz: 7350ceb335a2e36be33902c8a0dde0dc6f423f7eb85f0e7ad5b3291cc77c8e054b21b4162f6364256caa55336f8df78f5cc4a5065564f9dec13c56e470036b8c
-  data.tar.gz: 3a26fba34d62deadce6085e68f3d64fdb38c4bb28dcd4c92d350f1f9d554be36e94f08c0c9a23fafbc8cb02c4c9c9f8656a8f9cd078e1975e0c9016aec1cd1de
+  metadata.gz: e7dc36f5eeb2e7f9789484e5168accf43054459e7d970915ce7b771cef8fbe2335353408a3126b46a767a47a55ec3e663236b9f694be3e9279ac9fe6b2b286b2
+  data.tar.gz: 02781fd91885ce245291bb5c4cce1191546f211a67ecfedad60f999da65d3491efbee186e05b298c5319460e9fca2b5094f24ad56bf258c0e6342338682c7d84

data/.rubocop.yml

@@ -1 +1,6 @@
 # Use the default set of cops as a starting point
+
+# The use of double quotes fits with https://houndci.com (Thoughtbot's code
+# checker), and with Mike Stok's personal preferences.
+Style/StringLiterals:
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -6,6 +6,13 @@
 
 ### Bugs fixed
 
+## 0.0.3 (2014-08-08)
+
+### New features
+
+# [#11](https://github.com/mikestok/quiz_master/issues/11): Make a basic program
+ work
+
 ## 0.0.2 (2014-07-24)
 
 ### New Features

data/README.md

@@ -26,33 +26,65 @@ Or install it yourself as:
 
 ## Usage
 
-At the moment the only working part is a **crude** text formatter:
+As of release 0.0.3 it can generate reordered quizzes like this:
 
 ```ruby
-require 'quiz_master'
+#!/usr/bin/env ruby
 
+require "rubygems"
+require "quiz_master"
 include QuizMaster
 
-q = Question.new(
-  prompt: 'This is the prompt.  It poses the question.',
-  answers: [
-    Answer.new('This is the first answer', '5'),
-    Answer.new('This is the second answer'),
-    Answer.new('This is the third answer', '3'),
-    Answer.new('{{3}} and {{5}}')
-  ]
-)
-
-TextQuestionFormatter.new.format(q, 1)
-# =>
-# 1) This is the prompt.  It poses the question.
-# 
-#   a) This is the first answer
-#   b) This is the second answer
-#   c) This is the third answer
-#   d) (a) and (c)
+quiz_source = Quiz.new(
+  [
+    {
+      prompt: "Who were orignal members of Genesis?",
+      answers: [
+        Answer.new("Phil Collins", false, tag: "phil"),
+        Answer.new("Tony Banks", true),
+        Answer.new("Steve Hackett", false, tag: "steve"),
+        Answer.new("{{phil}} and {{steve}}", false)
+      ]
+    },
+    {
+      prompt: "Which numbers are prime?",
+      answers: [
+        Answer.new("1", false),
+        Answer.new("2", false, tag: "2"),
+        Answer.new("3", false),
+        Answer.new("All of the above except {{2}}", true, anchored: true)
+      ]
+    },
+    {
+      prompt: "What is the colour of a Banana?",
+      answers: [
+        Answer.new("Green", false),
+        Answer.new("Red", false, tag: "red"),
+        Answer.new("Yellow", false),
+        Answer.new("Black", false),
+        Answer.new("Brown", false),
+        Answer.new("Blue", false, tag: "blue"),
+        Answer.new("All of the colours above", false, anchored: true),
+        Answer.new("All of the colours above except {{blue}} and {{red}}", true,
+                   anchored: true)
+      ]
+    }
+  ].map { |q| Question.new(q) })
+
+3.times do
+  answer_reorderings = quiz_source.answer_reordering_vectors
+  question_reordering = quiz_source.question_reordering_vector
+
+  quiz = QuizVariant.new(quiz_source, answer_reorderings, question_reordering)
+
+  puts TextQuestionSheetFormatter.new.format(quiz)
+  puts TextAnswerSheetFormatter.new.format(quiz)
+end
 ```
 
+Generating three (probably) different versions of the same quiz and an answer
+sheet for each.
+
 ## Contributing
 
 1. Fork it ( https://github.com/mikestok/quiz_master/fork )

data/Rakefile

@@ -1,26 +1,26 @@
-require 'bundler/gem_tasks'
-require 'rubocop/rake_task'
-require 'rake/testtask'
-require 'rdoc/task'
+require "bundler/gem_tasks"
+require "rubocop/rake_task"
+require "rake/testtask"
+require "rdoc/task"
 
-task default: [:test]
+task default: %i(rubocop test)
 
-desc 'Run RuboCop on the lib directory'
+desc "Run RuboCop on the lib directory"
 RuboCop::RakeTask.new(:rubocop) do |task|
-  task.patterns = ['Rakefile', 'lib/**/*.rb']
+  task.patterns = %w(Rakefile test/**/*.rb lib/**/*.rb)
   # only show the files with failures
-  task.formatters = ['files']
+  task.formatters = ["clang"]
   # don't abort rake on failure
-  task.fail_on_error = false
+  task.fail_on_error = true
 end
 
 Rake::TestTask.new do |t|
-  t.libs << 'test'
-  t.test_files = FileList['test/**/test_*.rb']
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_spec.rb"]
 end
 
 RDoc::Task.new do |rdoc|
-  rdoc.main = 'README.md'
-  rdoc.rdoc_files.include('README.md', 'CHANGELOG.md', 'lib/**/*.rb')
-  rdoc.options << '--markup=tomdoc'
+  rdoc.main = "README.md"
+  rdoc.rdoc_files.include("README.md", "CHANGELOG.md", "lib/**/*.rb")
+  rdoc.options << "--markup=tomdoc"
 end

data/lib/quiz_master.rb

@@ -1,17 +1,44 @@
-require 'quiz_master/version'
-require 'quiz_master/text_question_formatter'
-require 'quiz_master/text_answer_sheet_formatter'
-require 'quiz_master/text_question_sheet_formatter'
-require 'quiz_master/question'
-require 'quiz_master/rendered_question'
-require 'quiz_master/answer'
-require 'quiz_master/quiz'
-require 'quiz_master/answers_renderer'
-require 'quiz_master/text_assembler'
+require "quiz_master/version"
+require "quiz_master/text_question_formatter"
+require "quiz_master/text_answer_sheet_formatter"
+require "quiz_master/text_question_sheet_formatter"
+require "quiz_master/question"
+require "quiz_master/rendered_question"
+require "quiz_master/answer"
+require "quiz_master/quiz"
+require "quiz_master/quiz_variant"
+require "quiz_master/answers_renderer"
+require "quiz_master/text_assembler"
+require "quiz_master/reorderer"
+require "quiz_master/reordering_vector"
 
 # This provides a namespace for all of the components.
 module QuizMaster
   # This error is raised when something discovers that there are the wrong
   # number of correct answers in a set of answers.
   NumberOfCorrectAnswersError = Class.new(StandardError)
+  # This error is raised when we try and move an anchored answer in a question.
+  MovingAnchoredAnswerError = Class.new(StandardError)
+  # This error is raised when we create a ReorderingVector and it doesn't
+  # contain the indices for an array of the right size.
+  BadReorderingVectorIndicesError = Class.new(StandardError)
+
+  # rubocop:disable Style/MethodName
+
+  # Public: This is a convenience method to let us construct a ReorderingVector
+  # from an Array of indices.
+  #
+  # array - An Array of values to put in the ReorderingVector
+  #
+  # Returns a ReorderingVector whose indices are copied from the Array.
+  # Raises BadReorderingVectorIndicesError if the supplied Array isn't a set
+  #   of indices.
+  def ReorderingVector(array)
+    array.sort == (0 ... array.size).to_a ||
+      fail(BadReorderingVectorIndicesError,
+           "#{array.inspect} must contain (0 ... #{array.size})")
+
+    ReorderingVector.new([false] * array.size) { array }
+  end
+  # rubocop:enable Style/MethodName
 end

data/lib/quiz_master/answer.rb

@@ -15,18 +15,21 @@ module QuizMaster
     #
     # text    - a String of text for the answer.
     # correct - whether this answer is true or false.
-    # tag     - an optional String which can be used to reference this Answer
-    #           from other Answers.
+    # tag:    - A String which can be used to reference this Answer
+    #           from other Answers. Optional.
+    # anchored: - A value to be used in boolean context to determine if this
+    #             Answer is anchored. Optional.
     #
     # Examples
     #
     #     a1 = Answer.new('Correct!', true)
     #     a1.text                           # => 'Correct!'
     #     a1.correct?                       # => true
-    def initialize(text, correct, tag = nil)
+    def initialize(text, correct, tag: nil, anchored: false)
       @text = text.to_s
       @correct = correct
       @tag = tag
+      @anchored = anchored
     end
 
     # Public: Tell whether this Answer is correct
@@ -35,5 +38,12 @@ module QuizMaster
     def correct?
       @correct ? true : false
     end
+
+    # Public: Tell whether this Answer is anchored
+    #
+    # Returns +true+ or +false+
+    def anchored?
+      @anchored ? true : false
+    end
   end
 end

data/lib/quiz_master/answers_renderer.rb

@@ -1,13 +1,13 @@
 module QuizMaster
-  # Public: This renders a list of answers into a new list of answers updating
-  # tag references enclosed in {{...}} so that the new answers have tags
+  # This renders a list of answers into a new list of Answers updating
+  # tag references enclosed in {{...}} so that the new Answers have tags
   # starting at +first_tag+
   class AnswersRenderer
     include Enumerable
 
     # Public: Initialize an AnswersRenderer object.
     #
-    # answers - An Array of Answer objects.
+    # answers   - An Array of Answer objects.
     # first_tag - Something that responds to #succ which is used as the initial
     #             tag in the stream of yielded Answers.
     def initialize(answers:, first_tag:)
@@ -21,13 +21,16 @@ module QuizMaster
     # Yields an Answer object.
     #
     # Returns nothing.
-    def each
-      @rendered_answers.each do |a|
-        yield a
-      end
+    def each(&block)
+      @rendered_answers.each(&block)
     end
 
-    private
+    # Public: Gets the Array of all the rendered Answers.
+    #
+    # Returns an Array of rendered Answers.
+    def all_answers
+      @rendered_answers.dup
+    end
 
     # Private: Create a mapping from the tags used in the original questions
     # passed to our initialize to the tags we'll use in the rendered answer.
@@ -46,7 +49,7 @@ module QuizMaster
     #
     # Returns a Hash mapping the original_answers tags to rendered answers
     # tags.
-    def make_tag_map(original_answers)
+    private def make_tag_map(original_answers)
       tagged_list(original_answers).each_with_object({}) do |(tag, ans), map|
         map[ans.tag] = tag if ans.tag
       end
@@ -59,9 +62,10 @@ module QuizMaster
     # original_answers - and Array of Answer objects
     #
     # Returns an Array of Answer objects.
-    def render_answers(original_answers)
+    private def render_answers(original_answers)
       tagged_list(original_answers).map do |tag, answer|
-        Answer.new(replace_tags(answer.text), answer.correct?, tag)
+        Answer.new(replace_tags(answer.text), answer.correct?,
+                   tag: tag, anchored: true)
       end
     end
 
@@ -72,7 +76,7 @@ module QuizMaster
     #
     # Returns a String with the tag place holders replaced with the correct
     # tags.
-    def replace_tags(string)
+    private def replace_tags(string)
       string
         .split(/({{[^}]+}})/)
         .each_with_object(TextAssembler.new) do |fragment, assembler|
@@ -94,7 +98,7 @@ module QuizMaster
     #   # => [['a', 'foo'], ['b', 'bar'], ['c', 'baz']
     #
     # Returns an Array whose elements are Arrays containing [tag, list_element]
-    def tagged_list(list)
+    private def tagged_list(list)
       list.zip(tag_sequence).map do |element, tag|
         [tag, element]
       end
@@ -104,7 +108,7 @@ module QuizMaster
     # starting with @first_tag.
     #
     # Returns an Enumerator which generates tags.
-    def tag_sequence
+    private def tag_sequence
       Enumerator.new do |yielder|
         tag = @first_tag
         loop do

data/lib/quiz_master/question.rb

@@ -1,3 +1,5 @@
+require_relative "answers_renderer"
+
 module QuizMaster
   # A simple class to link a prompt to a list of Answers.
   class Question
@@ -27,5 +29,72 @@ module QuizMaster
     def correct_answer
       answers.find(&:correct?).clone
     end
+
+    # Public: Return a new Question with the Answers reordered by the
+    # given specification.
+    #
+    # spec - A Reorderer, initialized to specify the reordering to perform.
+    #
+    # Returns a new Question with the Answers reordered.
+    # Raises MovingAnchoredAnswerError if we attempt to move an anchored answer.
+    def reorder_answers(spec)
+      fail(MovingAnchoredAnswerError) if moving_anchored_answer?(spec)
+      self.class.new(prompt: prompt, answers: spec.reorder(answers))
+    end
+
+    # Public: Return a reordering vector for this question, with un-anchored
+    # answers shuffled according to the shuffle_block.
+    #
+    # klass         - The class for the returned reordering vector.  Optional.
+    # shuffle_block - A block which specifies how the un-anchored answer indices
+    #                 should be shuffled.  It is passed an array of indices and
+    #                 is expected to return an array containing the same indices
+    #                 possibly in a different order.  Optional.
+    #
+    # Examples
+    #
+    #     # If this question has 4 answers with the last one anchored
+    #     q.reordering_vector
+    #     # => #<QuizMaster::ReorderingVector:0x???? @indices=[1, 2, 0, 3]>
+    #     #
+    #     # Where the first three indices can be shuffled in to any order.
+    #
+    # Returns an object of class klass.
+    def reordering_vector(klass = ReorderingVector, &shuffle_block)
+      shuffle_block ||= ->(a) { a.shuffle }
+      klass.new(answers.map(&:anchored?), &shuffle_block)
+    end
+
+    # Public: This generates a new object whose answers have been rendered.
+    #
+    # first_tag      - The tag to be used for the first question, it must
+    #                  respond to succ.  (Optional).
+    # result_class   - The class of the object to return.  I assume it is some
+    #                  sort of class which is compatible with Question.
+    #                  (Optional).
+    # renderer_class - The class to use for rendering the list of answers.
+    #                  (Optional).
+    #
+    # Returns result_class object which is the Question with the answers
+    # rendered.
+    def render_answers(first_tag: "a",
+                       result_class: self.class,
+                       renderer_class: AnswersRenderer)
+      result_class.new(prompt: prompt,
+                       answers: renderer_class.new(answers: answers,
+                                                   first_tag: first_tag
+                                                  ).all_answers
+                      )
+    end
+
+    # Private: A predicate to tell us if the given spec will move any Answer
+    # which is anchored.
+    #
+    # spec - A Reorderer
+    #
+    # Returns true or false.
+    private def moving_anchored_answer?(spec)
+      answers.values_at(*spec.moving_indices).any? { |a| a.anchored? }
+    end
   end
 end

data/lib/quiz_master/quiz.rb

@@ -1,3 +1,6 @@
+require_relative "reordering_vector"
+require_relative "reorderer"
+
 module QuizMaster
   # A quiz is a set of questions and their answers.
   #
@@ -17,10 +20,86 @@ module QuizMaster
     # questions - An Array of Questions.
     # header    - A String containg header text (optional).
     # footer    - A String containg footer text (optional).
-    def initialize(questions, header: '', footer: '')
+    def initialize(questions, header: "", footer: "")
       @questions = questions
       @header = header
       @footer = footer
     end
+
+    # Public: Return a ReorderingVector for the Answers for each of the
+    # Questions in the Quiz.
+    #
+    # The arguments are used for testing only and should not be supplied in
+    # "normal" code.
+    #
+    # klass         - The class of the Array elements to return. (optional).
+    # shuffle_block - A block to shuffle un-anchored Answers in a question.
+    #                 (optional).
+    #
+    # Returns an Array of ReorderingVectors.
+    def answer_reordering_vectors(klass = ReorderingVector, &shuffle_block)
+      questions.map do |q|
+        q.reordering_vector(klass, &shuffle_block)
+      end
+    end
+
+    # Public: Return a ReorderingVector for the Questions in the Quiz.
+    #
+    # The arguments are used for testing only and should not be supplied in
+    # "normal" code.
+    #
+    # klass         - The class of the object to return. (optional).
+    # shuffle_block - A block to shuffle Questions in the Quiz. (optional).
+    #
+    # Returns a ReorderingVector.
+    def question_reordering_vector(klass = ReorderingVector, &shuffle_block)
+      shuffle_block ||= ->(a) { a.shuffle }
+      # We assume that none of the Questions in a Quiz is anchored, hence the
+      # [false] * questions.count.
+      klass.new([false] * questions.count, &shuffle_block)
+    end
+
+    # Public: This generates a new object with the same Questions as this
+    # Quiz but in a different order.
+    #
+    # vector          - A vector specifying how the Questions are to be
+    #                   reordered.
+    # reorderer_class - The class of the Reorderer to use. (Optional).
+    #
+    # Returns a new Quiz with the questions reordered.
+    def reorder_questions(vector, reorderer_class = Reorderer)
+      reorderer = reorderer_class.new(*vector)
+      self.class.new(reorderer.reorder(questions),
+                     header: header,
+                     footer: footer)
+    end
+
+    # Public: This generates a new object where the Answers to each question
+    # have been reordered.
+    #
+    # array_of_vectors - An array of vectors specifiying how the Questions'
+    #                    Answers are to be re-ordered.
+    #
+    # Returns a new Quiz with the Questions' Answers reordered.
+    def reorder_answers(array_of_vectors)
+      new_questions = questions.zip(array_of_vectors).map do |q, vector|
+        question_with_reordered_answers(q, vector)
+      end
+
+      self.class.new(new_questions, header: header, footer: footer)
+    end
+
+    # Private: Create a new version of a question with its answers re-ordered.
+    #
+    # q      - The "source" question.
+    # vector - The ReorderingVector which specifies how the answers are to be
+    #          reordered.
+    #
+    # Returns a new Question which contains the answers from the source question
+    # reordered.
+    private def question_with_reordered_answers(q, vector)
+      r = Reorderer.new(*vector)
+      Question.new(prompt: q.prompt, answers: r.reorder(q.answers))
+    end
   end
 end