spirit 0.1.0.pre

data/lib/spirit/render/sanitize.rb

@@ -0,0 +1,90 @@
+# ~*~ encoding: utf-8 ~*~
+require 'sanitize'
+
+module Spirit
+
+  module Render
+
+    # Encapsulate sanitization options.
+    # @see https://github.com/github/gollum/blob/master/lib/gollum/sanitization.rb
+    class Sanitize < ::Sanitize
+
+      # white-listed elements
+      ELEMENTS = [
+        'a', 'abbr', 'acronym', 'address', 'area', 'b', 'big',
+        'blockquote', 'br', 'button', 'caption', 'center', 'cite',
+        'code', 'col', 'colgroup', 'dd', 'del', 'dfn', 'dir',
+        'div', 'dl', 'dt', 'em', 'fieldset', 'font', 'form', 'h1',
+        'h2', 'h3', 'h4', 'h5', 'h6', 'hr', 'i', 'img', 'input',
+        'ins', 'kbd', 'label', 'legend', 'li', 'map', 'menu',
+        'ol', 'optgroup', 'option', 'p', 'pre', 'q', 's', 'samp',
+        'select', 'small', 'span', 'strike', 'strong', 'sub',
+        'sup', 'table', 'tbody', 'td', 'textarea', 'tfoot', 'th',
+        'thead', 'tr', 'tt', 'u', 'ul', 'var'
+      ].freeze
+
+      # white-listed attributes
+      ATTRIBUTES = {
+        'a'   => ['href', 'name', 'data-magellan-destination'],
+        'dd'  => ['data-magellan-arrival'],
+        'dl'  => ['data-magellan-expedition'],
+        'img' => ['src'],
+        :all  => ['abbr', 'accept', 'accept-charset',
+                  'accesskey', 'action', 'align', 'alt', 'axis',
+                  'border', 'cellpadding', 'cellspacing', 'char',
+                  'charoff', 'class', 'charset', 'checked', 'cite',
+                  'clear', 'cols', 'colspan', 'color',
+                  'compact', 'coords', 'datetime', 'dir',
+                  'disabled', 'enctype', 'for', 'frame',
+                  'headers', 'height', 'hreflang',
+                  'hspace', 'id', 'ismap', 'label', 'lang',
+                  'longdesc', 'maxlength', 'media', 'method',
+                  'multiple', 'name', 'nohref', 'noshade',
+                  'nowrap', 'prompt', 'readonly', 'rel', 'rev',
+                  'rows', 'rowspan', 'rules', 'scope',
+                  'selected', 'shape', 'size', 'span',
+                  'start', 'summary', 'tabindex', 'target',
+                  'title', 'type', 'usemap', 'valign', 'value',
+                  'vspace', 'width']
+      }.freeze
+
+      # white-listed protocols
+      PROTOCOLS = {
+        'a'   => {'href' => ['http', 'https', 'mailto', 'ftp', 'irc', 'apt', :relative]},
+        'img' => {'src'  => ['http', 'https', :relative]}
+      }.freeze
+
+      # elements to remove (incl. contents)
+      REMOVE_CONTENTS = [
+        'script',
+        'style'
+      ].freeze
+
+      # attributes to add to elements
+      ADD_ATTRIBUTES = {
+        'a' => {'rel' => 'nofollow'}
+      }
+
+      # Creates a new sanitizer with {Spirit}'s configuration.
+      def initialize
+        super config
+      end
+
+      private
+
+      # @return [Hash] configuration hash.
+      def config
+        { elements:         ELEMENTS.dup,
+          attributes:       ATTRIBUTES.dup,
+          protocols:        PROTOCOLS.dup,
+          add_attributes:   ADD_ATTRIBUTES.dup,
+          remove_contents:  REMOVE_CONTENTS.dup,
+          allow_comments:   false
+        }
+      end
+
+    end
+
+  end
+
+end

data/lib/spirit/render/templates.rb

@@ -0,0 +1,6 @@
+# ~*~ encoding: utf-8 ~*~
+
+# require all template types
+%w(template header image problem multi short table navigation).each do |type|
+  require File.join 'spirit', 'render', 'templates', type
+end

data/lib/spirit/render/templates/header.rb

@@ -0,0 +1,52 @@
+# ~*~ encoding: utf-8 ~*~
+require 'active_support/core_ext/string/inflections'
+
+module Spirit
+
+  module Render
+
+    # Keeps track of headers within the same document. It's responsible for
+    # assigning unique names that can be used in the anchors.
+    class Headers
+
+      def initialize
+        @headers = {}
+      end
+
+      # Adds a new header to the set.
+      # @return [Header] header
+      def add(text, level=1)
+        name = text.parameterize
+        if @headers.include? name
+          name += '-%d' % (@headers[name] += 1)
+        else @headers[name] = 0 end
+        Header.new(text, level, name)
+      end
+
+    end
+
+    # Renders a header (e.g. +h1+, +h2+, ...) with anchors.
+    class Header < Template
+
+      # Name of template file for rendering headers.
+      TEMPLATE = 'header.haml'
+
+      attr_reader :name
+
+      # Creates a new header.
+      # @param [String] text          header text
+      # @param [Fixnum] level         1 to 6
+      # @param [String] name          anchor name
+      def initialize(text, level, name)
+        @text, @level, @name = text, level, name
+      end
+
+      def render(locals={})
+        super locals.merge(text: @text, level: @level, name: @name)
+      end
+
+    end
+
+  end
+
+end

data/lib/spirit/render/templates/image.rb

@@ -0,0 +1,54 @@
+# ~*~ encoding: utf-8 ~*~
+require 'nokogiri'
+
+module Spirit
+
+  module Render
+
+    # Renders a block image with a figure number.
+    class Image < Template
+
+      # <img ...>
+      IMAGE_TAG = 'img'
+
+      # Name of template file for rendering block images
+      TEMPLATE = 'img.haml'
+
+      class << self
+
+        # Parses the given text for a block image.
+        def parse(text)
+          Image.new text
+        end
+
+      end
+
+      # Creates a new image.
+      def initialize(html)
+        @html = html
+        parse_or_raise
+      end
+
+      def render(locals={})
+        super locals.merge(img: @html, caption: @node['alt'])
+      end
+
+      private
+
+      # Parses the given HTML, or raise {RenderError} if it is invalid.
+      def parse_or_raise
+        frag = Nokogiri::HTML::DocumentFragment.parse(@html)
+        if 1 == frag.children.count and
+          node = frag.children.first and
+          node.is_a? Nokogiri::XML::Element and
+          node.name == IMAGE_TAG
+          @node = node
+        else raise RenderError, 'Not really a block image.'
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/spirit/render/templates/multi.rb

@@ -0,0 +1,40 @@
+# ~*~ encoding: utf-8 ~*~
+module Spirit
+
+  module Render
+
+    # Renders multiple choice questions marked up in YAML as HTML.
+    # @example
+    #
+    #     {
+    #       "format": "multi",
+    #       "question": "How tall is Mount Everest?",
+    #       "answer": "A",
+    #       "options": {
+    #         "A": "452 inches",
+    #         "B": "8.85 kilometers"
+    #       }
+    #     }
+    class Multi < Problem
+
+      # Required key in YAML markup. Associated value should be a dictionary of
+      # label -> choices.
+      OPTIONS = 'options'
+
+      # Name of template file for rendering multiple choice questions.
+      TEMPLATE = 'multi.haml'
+
+      # Checks if the given yaml contains a valid MCQ.
+      # @return [Boolean] true iff the yaml contains a valid MCQ.
+      def valid?
+        super and
+          @yaml[ANSWER].is_a? String and
+          @yaml.has_key?(OPTIONS) and
+          @yaml[OPTIONS].is_a? Hash
+      end
+
+    end
+
+  end
+
+end

data/lib/spirit/render/templates/navigation.rb

@@ -0,0 +1,34 @@
+# ~*~ encoding: utf-8 ~*~
+module Spirit
+
+  module Render
+
+    # Keeps track of document sections and renders a navigation bar.
+    class Navigation < Template
+
+      # HAML template for navigation bar
+      TEMPLATE = 'nav.haml'
+
+      # Creates a new navigation bar.
+      def initialize
+        @sections = {}
+      end
+
+      # Adds a new section.
+      # @param [String] heading      section heading
+      # @param [String] name         anchor name
+      # @return [void]
+      def append(heading, name)
+        @sections[name] = heading
+      end
+
+      # Renders the navigation bar in HTML.
+      def render(locals={})
+        super locals.merge(sections: @sections)
+      end
+
+    end
+
+  end
+
+end

data/lib/spirit/render/templates/problem.rb

@@ -0,0 +1,126 @@
+# ~*~ encoding: utf-8 ~*~
+require 'spirit/constants'
+module Spirit
+
+  module Render
+
+    # Renders a single problem. This class doesn't do anything useful; use the
+    # child classes (e.g. {Spirit::Render::Multi}) instead. Child classes should
+    # override {#valid?}.
+    class Problem < Template
+
+      # Required key in YAML markup. Value indicates type of problem.
+      FORMAT = 'format'
+
+      # Required key in YAML markup. Value contains question body.
+      QUESTION = 'question'
+
+      # Required key in YAML markup. Value contains answers.
+      ANSWER = 'answer'
+
+      # Optional key in YAML markup. Value contains problem ID.
+      ID = 'id'
+
+      # Required keys.
+      KEYS = [FORMAT, QUESTION, ANSWER]
+
+      # Stateless markdown renderer.
+      MARKDOWN = ::Redcarpet::Markdown.new(::Redcarpet::Render::HTML, MARKDOWN_EXTENSIONS)
+
+      class << self
+
+        # Parses the given text for questions and answers. If the given text
+        # does not contain valid YAML or does not contain the format key, raises
+        # an {Spirit::Render::RenderError}.
+        # @param  [String]  text          embedded yaml
+        # @return [Problem] problem
+        def parse(text)
+          yaml = YAML.load text
+          get_instance(yaml)
+        rescue ::Psych::SyntaxError => e
+          raise RenderError, e.message
+        end
+
+        # Dynamically creates accessor methods for YAML values.
+        # @example
+        #   accessor :id
+        def accessor(*args)
+          args.each { |arg| define_method(arg) { @yaml[arg] } }
+        end
+
+        # @return [Problem] problem
+        def get_instance(yaml)
+          raise RenderError, "Missing 'format' key in given YAML" unless instantiable? yaml
+          klass = Spirit::Render.const_get(yaml[FORMAT].capitalize)
+          raise NameError unless klass < Problem
+          klass.new(yaml)
+        rescue NameError
+          raise RenderError, 'Unrecognized format: %p' % yaml[FORMAT]
+        end
+
+        private
+
+        def instantiable?(yaml)
+          yaml.is_a?(Hash) and yaml.has_key?(FORMAT)
+        end
+
+      end
+
+      accessor ID, *KEYS
+
+      # Creates a new problem from the given YAML.
+      # @param [Hash] yaml          parsed yaml object
+      def initialize(yaml)
+        @yaml = yaml
+        @yaml[ID] ||= SecureRandom.uuid
+        raise RenderError.new('Invalid problem.') unless @yaml[QUESTION].is_a? String
+        @yaml[QUESTION] = MARKDOWN.render @yaml[QUESTION]
+      end
+
+      # @todo TODO should probably show some error message in the preview,
+      #   so that the author doesn't have to read the logs.
+      def render(locals={})
+        raise RenderError.new('Invalid problem.') unless valid?
+        yaml = @yaml.merge(locals)
+        super yaml
+      end
+
+      # Saves the answer to a file on disk.
+      # @todo TODO should probably show some error message in the preview,
+      #   so that the author doesn't have to read the logs.
+      def save!
+        raise RenderError.new('Invalid problem.') unless valid?
+        solution = File.join(Spirit::SOLUTION_DIR, id + Spirit::SOLUTION_EXT)
+        File.open(solution, 'wb+') { |file| Marshal.dump answer, file }
+      end
+
+      # Retrieves the answer from the given YAML object in a serializable form.
+      # @see #serializable
+      # @return [String, Numeric, TrueClass, FalseClass] answer
+      def answer
+        serialize @yaml[ANSWER]
+      end
+
+      private
+
+      # If +obj+ is one of String, Numeric, +true+, or +false+, the it's
+      # returned. Otherwise, +to_s+ is invoked on the object and returned.
+      # @return [String, Numeric, TrueClass, FalseClass] answer
+      def serialize(obj)
+        case obj
+        when String, Numeric, TrueClass, FalseClass then obj
+        else obj.to_s end
+      end
+
+      # Checks that all required {KEYS} exist in the YAML, and that the
+      # question is given as a string.
+      # @return [Boolean] true iff the parsed yaml contains a valid problem.
+      def valid?
+        KEYS.all? { |key| @yaml.has_key? key } and question.is_a? String
+      end
+
+    end
+
+  end
+
+end

data/lib/spirit/render/templates/short.rb

@@ -0,0 +1,30 @@
+# ~*~ encoding: utf-8 ~*~
+module Spirit
+
+  module Render
+
+    # Renders short questions marked up in YAML as HTML.
+    # @example
+    #     {
+    #       "format": "short",
+    #       "question": "What is the most commonly used word in English?",
+    #       "answer": "the"
+    #     }
+    class Short < Problem
+
+      # Name of template file for rendering short answer questions.
+      TEMPLATE = 'short.haml'
+
+      # Checks if the given yaml contains a valid MCQ.
+      # @return [Boolean] true iff the yaml contains a valid MCQ.
+      def valid?
+        super and
+          not @yaml[ANSWER].nil?
+      end
+
+    end
+
+  end
+
+end
+

data/lib/spirit/render/templates/table.rb

@@ -0,0 +1,109 @@
+# ~*~ encoding: utf-8 ~*~
+module Spirit
+
+  module Render
+
+    # Renders table problems marked up in YAML as HTML.
+    #
+    # The grid should be given as a 2-dimensional array that represents the
+    # table to be filled in. +"?"+ is a special token used in the grid to
+    # indicate cells that require student input.
+    #
+    # The answer should also be given as a 2-dimensional array. However, a
+    # dummy token may be used in cells that do not require student input to
+    # cut redundancy. In the example below, the +"-"+ token is used.
+    #
+    # @example
+    #     {
+    #       "format": "table",
+    #       "question": "fill me in",
+    #       "grid": [[0, "?", 2], [3, "?", 5]],
+    #       "answer": [["-", 1, "-"],  ["-", 4, "-"]
+    #     }
+    class Table < Problem
+
+      # Name of template file for rendering table problems.
+      TEMPLATE = 'table.haml'
+
+      # Optional headings key.
+      HEADINGS = 'headings'
+
+      # Required grid key.
+      GRID = 'grid'
+
+      # Special token indicating that the cell should be filled in.
+      FILL_ME_IN = '?'
+
+      accessor HEADINGS, GRID
+
+      # Ensures that the +headings+ key exists.
+      def initialize(yaml)
+        yaml[HEADINGS] ||= nil
+        super
+      end
+
+      # Checks if the given yaml contains a valid table.
+      # @return [Boolean] true iff the yaml contains a valid table.
+      def valid?
+        super and
+          valid_grid? and
+          valid_answer?
+      end
+
+      # Gets the expected answer, in www-form-urlencoded format.
+      # @return [Hash] answers, as expected from student's form submission
+      def answer
+        return @answer unless @answer.nil?
+        @answer = encode_answer
+      end
+
+      # @return [Boolean] true iff the given cell is an input cell
+      def self.input?(cell)
+        cell == FILL_ME_IN
+      end
+
+      private
+
+      # Iterates through each cell in the provided grid to look for answers
+      # cells that require input and takes the answer from the answers array.
+      # For example, if the answer for a cell at [0][1] is 6, the returned
+      # hash will contain
+      #
+      #     {'0' => {'1' => 6}}
+      #
+      # @return [Hash] answers
+      def encode_answer
+        encoded, ans = {}, @yaml[ANSWER]
+        grid.each_with_index do |row, i|
+          row.each_with_index do |cell, j|
+            next unless Table.input? cell
+            encoded[i.to_s] ||= {}
+            encoded[i.to_s][j.to_s] = serialize ans[i][j]
+          end
+        end
+        encoded
+      end
+
+      # @return [Boolean] true iff the yaml contains a valid grid.
+      def valid_grid?
+        @yaml.has_key? GRID and is_2d_array? grid
+      end
+
+      # @return [Boolean] true iff +answer+ is a valid 2D array and has the
+      # same number of rows as +grid+.
+      def valid_answer?
+        ans = @yaml[ANSWER]
+        is_2d_array? ans and ans.size == grid.size
+      end
+
+      # @return [Boolean] true iff +t+ is a 2-dimensional array.
+      def is_2d_array?(t)
+        t.is_a? Array and t.all? { |row| row.is_a? Array }
+      end
+
+    end
+
+  end
+
+end
+