ruql 0.1.3 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 8a6637987324f5db32e7387b7183ea4591957817
-  data.tar.gz: 05dc9bbffafb43de71688bbbd1a0b70302d51665
+SHA256:
+  metadata.gz: 9fccf871f5ff726c5efff5cbc3871792bcdc6b9610296285a962018e906e9cc7
+  data.tar.gz: e8f08ac21c0e465767decc50022c69c7e4d770e631ba9a0df01b8fb058bfcb3e
 SHA512:
-  metadata.gz: bd17352a49b61a9b0844cb0d043093c3ba8fe33ba302ac83aac60cb602a4f534074f7c02c4dd0f0772d301232dd360c57d997ddd6fd67ac171172983b0e8c93b
-  data.tar.gz: 2f34ee1cd6b63f9f81ccd6bafecc7864143d4512d127d1a5740e035f73d9cf5c83abd68bd0eda6b232837bb1a68e60223977ca38920c9a8926b1d167779fd25d
+  metadata.gz: 14f33e1817d330f2fee438529a1a4ef86cf7f90a68156381c73f9a99db6b1b48da7706cad0847919102c648b1d1b4371ac6a88e869eaf8efacccc9c227ee54ec
+  data.tar.gz: 611b7d96d5597b9bd14f995c9aece5b8c46695b472470a9b7edf8a3322a8067e8bfa36ba470c032314c7c4cdb6c85f001e4ac16733fee73df85b79d37ab56106

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,308 @@
+[![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.
+
+
+Installation
+============
+
+`gem install ruql` to install this from RubyGems.  It works with Ruby
+>=1.9.2
+
+You'll also need to install one or more formatters to produce quiz output.
+
+Installation: Current Formatters
+================================
+
+* [ruql-html](https://github.com/saasbook/ruql-html): produces HTML 5 output using a default or user-supplied HTML
+template
+* [ruql-canvas](https://github.com/saasbook/ruql-canvas): creates a quiz in Canvas LMS using its REST API
+
+
+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.
+
+
+Adding your own renderer
+========================
+
+**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
+  module 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,105 +1,95 @@
 #!/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
+      if renderer == 'stats'
+        @renderer = Ruql::Stats
+        @help = ''
+        @additional_options = []
+      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:
-  -l <loglevel>, --log=<loglevel>
-     In increasing verbosity, they are 'error' (nonfatal), 'warn', 'info',
-     'debug'; default is 'warn'
-  -p <penalty>, --penalty <penalty>
-     The penalty for WRONG answers, as a fraction of the penalty for
-     RIGHT answers.  For a 2-point question, penalty=0.25 means 1/2 point
-     (0.25 * 2) deducted for WRONG answer.  Default is 0.  Not all
-     output formats are able to do something useful with this.
-
-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>
-  -a <first>, --list-start=<first>
-      Sets the values of the 'start' and 'type' attributes for the HTML <ol>
-      element.  Type should be one of 1,a,A,i,I.  Start should always be
-      a number indicating the ordinal value (starting from 1) of first item.
-  -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(
-    ['-o', '--list-type', Getopt::REQUIRED],
-    ['-a', '--list-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],
-    ['-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
+
+