ruql 0.1.5 → 1.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 1a384710404460b95c945d6a1fb850c88531db8a
-  data.tar.gz: 5c6af8b878133a20c3f7b0e4e38a184b4b0b7400
+SHA256:
+  metadata.gz: ff79fa8465db54b4e2ce0e9ee62c891649b2066a5093c76747f7a3693cc8321e
+  data.tar.gz: 43f22ab810aebe22665a985d25db33a8a8d46cba38ff1f0d4cd6145de4bf0fce
 SHA512:
-  metadata.gz: feb04ca43e5e83c6e6a97f042ab03b3692663a23f835783121edd68bc3ebba1b3ffe728ab682edf053055ef64222625cf8f056a93112ebc287314f475edb0f4a
-  data.tar.gz: 0414a7abbd51a50703b290c2a912575b6fbaead7330cfbcede247950dd67e0e4d84a6f6e6d35120d26e8fdbcb37a6b103c75d512211e16b9db8eb2fcdc2b5736
+  metadata.gz: 7f2ec53ca0098f8c7fe2bf43557935351b73313469ce3610517eb51122bdecb5353509dedd84a05119b7f422c85510b47cc2fb062b17a34a51bd15e077deb4a3
+  data.tar.gz: 78913cb4c7913a01748cd9f6966bf0fbfed7886bc5c94e81a95bac7ec893f0e5469c2621a7f00124f18f57fd45e64fe8541f6e8d76a16316a75e7ff52fe88411

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+.byebug_history
+Gemfile.lock
+TAGS

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.6.3
+before_install: gem install bundler -v 1.17.3

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in ruql.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) 2012 Strawberry Canyon LLC.
+
+Contents of this repository are governed by the Creative Commons
+Attribution - Noncommercial - ShareAlike 3.0 Unported license:
+
+http://creativecommons.org/licenses/by-nc-sa/3.0/

data/README.md

@@ -0,0 +1,318 @@
+[![CodeClimate](https://codeclimate.com/github/saasbook/ruql/badges/gpa.svg)](https://codeclimate.com/github/saasbook/ruql)
+[![Coverage](https://codeclimate.com/github/saasbook/ruql/badges/coverage.svg)](https://codeclimate.com/github/saasbook/ruql/coverage)
+[![Gem Version](https://badge.fury.io/rb/ruql.svg)](https://badge.fury.io/rb/ruql)
+
+Ruby-based DSL for Authoring Quiz Questions
+===========================================
+
+This is a simple gem that takes a set of questions (a "quiz") written in
+RuQL ("Ruby quiz language" or "Ruby question language" - a DSL embedded
+in Ruby), and produces one of several possible output formats.
+
+Some types of questions or question elements that can be expressed in
+RuQL cannot be expressed by some LMSs, and some LMS-specific question
+features cannot be expressed in RuQL.
+
+[Registered ESaaS instructors](http://www.saasbook.info/instructors) can access
+[this repo](/saasbook/csw169a-quizzes) of questions, grouped by
+chapter of the [ESaaS textbook](http://www.saasbook.info).
+
+
+Installation
+============
+
+`gem install ruql` to install this from RubyGems.  It works with Ruby 1.9 or later.
+
+You'll also need to install one or more formatters to produce quiz output.
+
+Installation: Current Formatters
+================================
+
+* [ruql-html](/saasbook/ruql-html): produces HTML 5 output using a default or user-supplied HTML
+template
+* [ruql-canvas](/saasbook/ruql-canvas): creates a quiz in Canvas LMS using its REST API
+* [ruql-olx](/saasbook/ruql-olx): creates a quiz in edX's Open Learning XML
+
+
+Running RuQL
+============
+
+Create your `quiz.rb` file as described below, then run:
+
+`ruql formatter-name quiz.rb`
+
+Where `formatter-name` is from the list above, eg `html` for the
+`ruql-html` formatter.
+
+`ruql formatter-name -h` lists the options supported by that
+formatter, and `ruql -h` shows RuQL's global options.
+
+
+Creating Quiz Questions in RuQL
+===============================
+
+RuQL supports a few different types of short-answer questions and can
+output them in a variety of formats compatible with different Learning
+Management Systems or in printable form.
+
+RuQL is a DSL embedded in Ruby, so you can include expressions in
+questions, for example, to generate simple variants of a question along
+with its solution.
+
+In addition to the basic parts of a question (prompt text, answers,
+etc.), each question can also have an optional list of one or more
+_tags_, and an optional _comment_.  These attributes
+are available to formatters, but most formatters ignore them.
+They can be used to provide information about the
+question's topic(s) or other info useful to a question-management app
+such as [Course Question Bank](https://github.com/saasbook/coursequestionbank).
+
+A question can also optionally have a _group_.  Questions with the
+same group name (within the scope of a single quiz) are grouped in
+a "pool" from which a single question is selected at quiz generation time.
+For "static" formatters such as HTML, RuQL will pick a random
+question.  For some LMSs, like Canvas, the questions are put into a
+"quiz group" and any given student gets a randomly chosen one at runtime.
+
+Preparing a quiz
+----------------
+
+A quiz is an `.rb` file with a collection of questions:
+
+    quiz 'Example quiz name here' do
+      # (questions here)
+    end
+
+You create a quiz by putting the quiz in its own file and
+copying-and-pasting the questions you want into it.  (Yes, that's ugly.
+Soon, questions will have unique IDs and you'll be able to create a quiz
+by reference.)
+
+Multiple-choice questions with a single correct answer
+------------------------------------------------------
+
+You can provide a generic `explanation` clause, and/or override it with
+specific explanations to accompany right or wrong answers.
+Choices are rendered in the order in which
+they appear in the RuQL markup, but capable LMSs or formatters can be
+told to randomize them.  This example also shows the use of tags to
+include metadata about a question's topic, and the use of groups to
+place two questions into a group from which one will be chosen at
+random for the quiz.
+
+```ruby
+choice_answer  do
+  tags 'US states', 'geography'
+  group 'states-1'
+  text  "What is the largest US state?"
+  explanation "Not big enough." # for distractors without their own explanation
+  answer 'Alaska'
+  distractor 'Hawaii'
+  distractor 'Texas', :explanation => "That's pretty big, but think colder."
+end
+choice_answer  do
+  tags 'US cities', 'geography'
+  group 'states-1'
+  text  "What is the largest US city?"
+  answer 'New York'
+  distractor 'Los Angeles'
+  distractor 'Chicago'
+end
+```
+
+Specifying `:raw => true` allows HTML markup in the question to be
+passed through unescaped, such as for `<pre>` or `<code>` blocks.
+
+
+```ruby
+  choice_answer :raw => true do
+    text %Q{What does the following code do:
+<pre>
+  puts "Hello world!"
+</pre>
+}
+    distractor 'Throws an exception', :explanation => "Don't be an idiot."
+    answer 'Prints a friendly message'
+  end
+```
+
+Multiple-choice "select all that apply" questions
+-------------------------------------------------
+
+These use the same syntax as single-choice questions, but multiple
+`answer` clauses are allowed:
+
+```ruby
+select_multiple do
+  text "Which are American political parties?"
+  answer "Democrats"
+  answer "Republicans"
+  answer "Greens", :explanation => "Yes, they're a party!"
+  distractor "Tories", :explanation => "They're British"
+  distractor "Social Democrats"
+end
+```
+
+True or false questions
+-----------------------
+
+Internally, true/false questions are treated as a special case of
+multiple-choice questions with a single correct answer, but there's a
+shortcut syntax for them.
+
+```ruby
+truefalse 'The week has 7 days.', true
+truefalse 'The earth is flat.', false, :explanation => 'No, just looks that way'
+```
+
+Short-answer fill-in-the-blanks questions
+-----------------------------------------
+
+Put three or more hyphens in a row where you want the "blanks" to be,
+and provide a string or regexp to check the answer; all regexps are 
+case-INSENSITIVE unless :case_sensitive => true is passed.  
+
+```ruby
+fill_in :points => 2 do
+  text 'The capital of California is ---.'
+  answer 'sacramento'
+end
+```
+
+Optional distractors can capture common incorrect answers.  As with all
+question types, an optional `:explanation` can accompany a correct
+answer or a distractor; its usage varies with the LMS, but a typical use
+is to display a hint if the wrong answer is given, or to display
+explanatory text accompanying the correct answer.
+
+```ruby
+fill_in do
+  text 'The visionary founder of Apple is ---'
+  answer /^ste(ve|phen)\s+jobs$/
+  distractor /^steve\s+wozniak/, :explanation => 'Almost, but not quite.'
+end
+```
+
+You can have multiple blanks per question and pass an array of regexps
+or strings to check them.  Passing `:order => false` means that the
+order in which blanks are filled doesn't matter.  The number of elements
+in the array must exactly match the number of blanks.
+
+```ruby
+fill_in do
+  text 'The --- brown fox jumped over the lazy ---'
+  answer [/fox/, /dog/], :explanation => 'This sentence contains all of the letters of the English Alphabet'
+end
+
+fill_in do
+  text 'The three stooges are ---, ---, and ---.'
+  answer %w(larry moe curly), :order => false
+end
+```
+
+
+
+Questions with one or more dropdown-menu choices
+------------------------------------------------
+
+A question can consist of one or more dropdown menus and interstitial text (which is rendered verbatim without newlines,
+so use `:raw => true` to embed `<br>` tags if you want breaks).  A choice selector needs
+two arguments: the 0-based index of the correct choice, and an array of strings of all the choices.
+The `label` method provides interstitial text that separates the dropdowns.
+
+```ruby
+dropdown do
+  text "Arguably the world's first theme park was"
+  choice 0, ['Disneyland', 'Mickey World', 'Teenage Mutant Ninja Turtles Park']
+  label "located in"
+  choice 2, ['Beijing, China', 'Paris, France', 'California, USA']
+end
+```
+
+
+Additional arguments and options
+--------------------------------
+
+The following arguments and options have different behavior (or no
+effect on behavior) depending on what format questions are emitted in:
+
+1. All question types accept a `:name => 'something'` argument, which some
+output generators use to create a displayable name for the question or
+to identify it within a group of questions.
+
+2. The optional `tag` clause is followed by a string or array of strings,
+and associates the given tag(s) with the question, in anticipation of
+future tools that can use this information.
+
+3. The optional `comment` clause is followed by a string and allows a
+free-text comment to be added to a question.
+
+4. The optional `group` clause, which takes a single string, names
+a "pool" of questions of which this question is a part.  Some formatters
+such as the Canvas importer will turn this into a "quiz question group"
+so that one question from the pool will be randomly chosen to show the
+student.  See each formatter's documentation for how/whether it uses this property.
+
+
+Adding your own formatter
+========================
+
+**This documentation is incomplete**
+
+If you're creating the `foobar` formatter, the gem should
+be named `ruql-foobar` and have the following directory
+structure (heavily recommend using Bundler):
+
+```
+ruql-foobar:
+.
+├── CODE_OF_CONDUCT.md
+├── Gemfile
+├── README.md
+├── Rakefile
+├── bin
+│   ├── console
+│   └── setup
+├── lib
+│   └── ruql
+│       ├── foobar
+│       │   ├── foobar.rb
+│       │   └── version.rb
+│       └── foobar.rb
+├── result.json
+├── ruql-foobar.gemspec
+├── spec
+│   ├── ruql
+│   │   └── foobar_spec.rb
+│   └── spec_helper.rb
+└── templates
+    └── quiz.json
+
+
+```
+
+The main entry point should be in
+`ruql-foobar/lib/ruql/foobar/foobar.rb` and include the following at a
+minimum:
+
+```ruby
+module Ruql
+  class Foobar
+    def initialize(quiz, options={})
+      # initialize yourself, given a Quiz object and command-line
+      # options in Getoptlong format
+    end
+    def self.allowed_options
+      opts = [['--foobar-option1', Getoptlong::REQUIRED_ARGUMENT],
+              ['--foobar-option2', Getoptlong::BOOLEAN_ARGUMENT]]
+      help_text = "Some text describing what the options do"
+      return [help_text, opts]
+    end
+    def render_quiz
+      # render your quiz however you like. See the descriptions of 
+      # the Quiz class and various subclasses of Question and Answer.
+    end
+  end
+end
+```
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "ruql"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/ruql

@@ -1,121 +1,97 @@
 #!/usr/bin/env ruby
 
-# require 'ruql'
+require 'rubygems'
 require_relative '../lib/ruql'
-require 'getopt/long'
-
-def usage
-  name = File.basename $0
-  STDERR.puts <<eos
-Usage: #{name} filename.rb renderer [options]
-filename.rb contains questions expressed in RuQL
-
-renderer choices are:
-  Html5    - HTML 5 suitable for Web display/printing
-  HtmlForm - HTML forms
-  EdXml    - XML for OpenEdX platform in-course questions
-  AutoQCM  - LaTeX for use with AutoQCM (http://home.gna.org/auto-qcm)
-  JSON     - [partially implemented] JSON format
-  Qualtrics -[partially implemented] Qualtrics survey (txt) format
+require 'getoptlong'
 
+module Ruql
+  class Runner
+
+    def initialize
+      @renderer = nil
+      @options = {}
+      @filename = nil
+      @template = nil
+      @solutions = nil
+      @help = ''
+      @additional_options = [[]]
+    end
+
+    def version
+      puts Ruql::VERSION
+      exit true
+    end
+
+    def load_renderer
+      renderer = ARGV.shift
+      @help = ''
+      @additional_options = []
+      if renderer == 'stats'
+        @renderer = Ruql::Stats
+      elsif renderer == 'json'
+        @renderer = Ruql::Json
+      else
+        begin
+          require "ruql/#{renderer}"
+          @renderer = Object.const_get("Ruql::" + renderer.gsub(/(?:_|^)(\w)/){$1.upcase})
+          @help,@additional_options = @renderer.allowed_options
+        rescue LoadError => e
+          raise Ruql::OptionsError.new("Formatter '#{renderer}' requires the gem ruql-#{renderer} to be installed")
+        end
+      end
+    end
+
+    def run
+      usage if ARGV.length < 1 || ARGV[0] =~ /^--?[Hh]/
+      version if ARGV[0] =~ /^-v/
+      load_renderer
+
+      options = [
+        ['-h', '--help', GetoptLong::NO_ARGUMENT],
+        ['-S', '--solutions', GetoptLong::NO_ARGUMENT],
+        ['-V', '--verbose', GetoptLong::NO_ARGUMENT]
+      ]
+      opts = GetoptLong.new(*(options + @additional_options))
+      
+      opts.each do |opt,arg|
+        usage if (opt == '--help' || opt == '-H')
+        # anything else gets passed to renderer
+        @options[opt] = arg
+      end
+
+      @filename = ARGV.pop || usage
+      raise "Cannot read #{@filename}" unless File.readable? @filename
+
+      ## Quiz.set_yaml_file opts.delete("y") || opts.delete("yaml")
+      Quiz.set_options(@options)
+      Quiz.instance_eval "#{IO.read(@filename)}"
+      Quiz.quizzes.each { |quiz| puts quiz.render_with(@renderer, @options)  }
+    end
+    
+    def usage
+      name = File.basename $0
+      STDERR.puts <<eos
+Usage: #{name} <formatter> [options] filename.rb
+
+ filename.rb contains questions expressed in RuQL.  Formatters are packaged as separate gems
+ named ruql-*, for example, formatter 'html' is provided by the gem ruql-html, which must
+ be installed. See #{Gem.loaded_specs['ruql'].homepage} for available formatters or to add your own.
+
+The special formatter 'stats' will just show stats for the input file without generating output.
 Global options:
-  -r <file>, --report=<file>
-     Write to <file> a 4-line report of #points, #questions, and first and last
-     question#. Especially useful in conjunction with the -a/--start option.
-  -a <first>, --start=<first>
-      Sets the starting ordinal value (1=first) for question numbering. Default 1.
-      If a filename is given, looks for a line of the form "last NN" and
-      starts at the number following NN.
-  -l <loglevel>, --log=<loglevel>
-     In increasing verbosity, they are 'error' (nonfatal), 'warn', 'info',
-     'debug'; default is 'warn'
-  -p <points>, --points-threshold <points>
-     If a question's point value is more than <points> (default: 0), include
-     the string "[N points]" at the beginning of the question text.  Make this a
-     large number to avoid any points info being printed.
-  -P <points-string>, --points-string <points-string>  
-     String for formatting the points description prepended to the question text,
-     with %d as a placeholder for the point value and %s as a placeholder for
-     pluralizing the word 'points' or whatever.  Default is "[%d point%s]".
-  -R, --no-randomize
-     Present the answer choices in the order they appear in the RuQL file(s),
-     even for questions that have :randomize => true.
-
-The EdXML renderer supports these options:
-  -n <name>, --name=<name>
-      Only render the question(s) that have :name => 'name'.
-  NOTE: Some markup that is legal in RuQL questions will break the EdX parser.
-     Manually check your questions as you enter them into EdX.  Code seems to
-     be particularly troublesome.
-  NOTE: The 'points' and 'randomize' attributes of questions are not honored by
-     some systems.
-
-  -y <file.yml>, --yaml=<file.yml>
-      Render open-assessment questions using info in given Yaml file.
-
-The HTML5 and HTML Forms renderers supports these options:
-  -o <type>, --list-type=<type>
-      Sets the type of HTML list to use for answer choices: 'u' for unordered
-      (<ul>) or 'o' for ordered (<ol>).  Default is 'o'.
-  -j <src>, --js=<src>
-      embed <src> for JavaScript
-  -t <file.html.erb>, --template=<file.html.erb>
-      Use file.html.erb as HTML template rather than generating our own file.
-      file.html.erb should have <%= yield %> where questions should go.
-      The default template in the templates/ directory of RuQL will be used
-      if this option is not given.
-      The following local variables will be replaced with their values in
-      the template:
-        <%= quiz.title %> - the quiz title
-        <%= quiz.num_questions %> - total number of questions
-        <%= quiz.points %> - total number of points for whole quiz
-  -s, --solutions
-      generate solutions (showing correct answers and explanations)
-  NOTE: If there is more than one quiz (collection of questions) in the file,
-      a complete <html>...</html> block is produced in the output for EACH quiz.
-
-The AutoQCM renderer supports these options:
-  -t <file.tex.erb>, --template=<file.tex.erb>
-      MANDATORY: Use file.tex.erb as LaTeX/AutoQCM template.
-      The file should have <%= yield %> where questions should go.
-      See the description of template under HTML5 renderer for variable
-      substitutions that can occur in the quiz body.
-
-The JSON renderer currently supports no options
-
-The Qualtrics renderer supports these options:
-  -t <file.txt.erb>, --template=<file.txt.erb>
-  The file should have <%= yield %> where questions should go. Since this just creates survey questions, grading information is ignored. Currently supports the same type of questions as the AutoQCM renderer.
+  -S, --solutions
+     Generate a version of the output with solutions included (not supported by all formatters)
+  -V, --verbose
+     Show verbose output for debugging
+
+#{@help}
 
 eos
-  exit
-end
-
-def main
-  filename = ARGV.shift
-  raise "Cannot read #{filename}" unless File.readable? filename
-  renderer = ARGV.shift
-  raise "Unknown renderer '#{renderer}'" unless Quiz.get_renderer(renderer)
-
-  opts = Getopt::Long.getopts(
-    ['-v', '--version', Getopt::BOOLEAN],
-    ['-o', '--list-type', Getopt::REQUIRED],
-    ['-r', '--report', Getopt::REQUIRED],
-    ['-a', '--start', Getopt::REQUIRED],
-    ['-c', '--css', Getopt::REQUIRED],
-    ['-j', '--js', Getopt::REQUIRED],
-    ['-t', '--template', Getopt::REQUIRED],
-    ['-s', '--solutions', Getopt::BOOLEAN],
-    ['-n', '--name', Getopt::REQUIRED],
-    ['-l', '--log', Getopt::REQUIRED],
-    ['-P', '--points-string', Getopt::REQUIRED],
-    ['-p', '--points-threshold', Getopt::REQUIRED],
-    ['-R', '--no-randomize', Getopt::BOOLEAN],
-    ['-y', '--yaml', Getopt::REQUIRED]
-  )
-  Quiz.instance_eval "#{IO.read(filename)}"
-  Quiz.quizzes.each { |quiz| puts quiz.render_with(renderer, opts)  }
-end
-
-usage if ARGV.length < 2
-main
+      exit false
+    end
+  end
+end  
+
+Ruql::Runner.new.run
+
+