aladdin 0.0.1 → 0.0.3

data/lib/aladdin/render/error.rb

@@ -0,0 +1,20 @@
+# ~*~ encoding: utf-8 ~*~
+module Aladdin
+
+  module Render
+
+    # The base exception for {Aladdin::Render} Errors
+    class Error < StandardError
+    end
+
+    # This exception is raised if a parse error occurs.
+    class ParseError < Error
+    end
+
+    # This exception is raised if a render error occurs.
+    class RenderError < Error
+    end
+
+  end
+
+end

data/lib/aladdin/render/image.rb

@@ -0,0 +1,54 @@
+# ~*~ encoding: utf-8 ~*~
+require 'nokogiri'
+
+module Aladdin
+
+  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 {ParseError} 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 ParseError.new 'Not really a block image.'
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/aladdin/render/markdown.rb

@@ -1,37 +1,140 @@
+require 'aladdin/render/sanitize'
+require 'aladdin/render/error'
+require 'aladdin/render/template'
+require 'aladdin/render/image'
+require 'aladdin/render/problem'
+require 'aladdin/render/multi'
+require 'aladdin/render/short'
+require 'aladdin/render/table'
+require 'aladdin/render/navigation'
+
 # ~*~ encoding: utf-8 ~*~
 module Aladdin
 
-  # laddin-render module for all of Laddin's rendering needs.
+  # aladdin-render module for all of Laddin's rendering needs.
   module Render
 
     # HTML Renderer for Markdown.
+    #
     # It creates pygmentized code blocks, supports hard-wraps, and only
-    # generates links for protocols which are considered safe.
+    # generates links for protocols which are considered safe. Adds support for
+    # embedded JSON, which are used to markup quizzes and tables. Refer to
+    # {CONFIGURATION} for more details.
+    #
     # @see http://github.github.com/github-flavored-markdown/
     class HTML < ::Redcarpet::Render::HTML
+      include Aladdin::Mixin::Logger
 
       @sanitize = Aladdin::Sanitize.new
-      class << self; attr_reader :sanitize; end
+      @entities = HTMLEntities.new
+
+      class << self; attr_reader :sanitize, :entities; end
+
+      # Paragraphs that start and end with braces are treated as JSON blocks
+      # and are parsed for questions/answers.
+      PROBLEM_REGEX = %r<^\s*{.+$>
+
+      # Paragraphs that only contain images are rendered differently.
+      IMAGE_REGEX = %r{^\s*<img[^<>]+>\s*$}
+
+      # Renderer configuration options.
+      CONFIGURATION = {
+        hard_wrap:          true,
+        safe_links_only:    true,
+      }
 
       # Creates a new HTML renderer.
       # @param [Hash] options        described in the RedCarpet documentation.
       def initialize(options = {})
-        super options.merge(hard_wrap: true, safe_links_only: true)
+        super options.merge(CONFIGURATION)
+        exe_template = File.join(Aladdin::VIEWS[:haml], 'exe.haml')
+        @exe, @nav = Haml::Engine.new(File.read exe_template), Navigation.new
+        @prob, @img = 0, 0 # indices for Problem # and Figure #
       end
 
       # Pygmentizes code blocks.
       # @param [String] code        code block contents
-      # @param [String] language    name of language, for syntax highlighting
+      # @param [String] marker      name of language, for syntax highlighting
       # @return [String] highlighted code
-      def block_code(code, language)
-        Albino.colorize code, language
+      def block_code(code, marker)
+        language, type, id = (marker || 'text').split ':'
+        highlighted = Albino.colorize code, language
+        case type
+        when 'demo', 'test'
+          executable id: id, raw: code, colored: highlighted
+        else highlighted end
+      end
+
+      # Detects problem blocks and image blocks.
+      # @param [String] text      paragraph text
+      def paragraph(text)
+        case text
+        when PROBLEM_REGEX then problem(text)
+        when IMAGE_REGEX then block_image(text)
+        else p(text) end
+      rescue Error => e # fall back to paragraph
+        logger.warn e.message
+        p(text)
+      end
+
+      # Increases all header levels by one and keeps track of document
+      # sections.
+      def header(text, level)
+        level += 1
+        html = h(text, level)
+        if level == 2
+          index = @nav << text
+          html += "<a name='section_#{index}' data-magellan-destination='section_#{index}'/>"
+        end
+        html
       end
 
       # Sanitizes the final document.
       # @param [String] document    html document
       # @return [String] sanitized document
       def postprocess(document)
-        HTML.sanitize.clean document
+        HTML.sanitize.clean(@nav.render + document.force_encoding('utf-8'))
+      end
+
+      private
+
+      # Prepares an executable code block.
+      # @option opts [String] id        author-supplied ID
+      # @option opts [String] raw       code to execute
+      # @option opts [String] colored   syntax highlighted code
+      # @return [String]
+      def executable(opts)
+        opts[:colored] + @exe.render(Object.new, id: opts[:id], raw: opts[:raw])
+      end
+
+      # Prepares a problem form. Raises {RenderError} or {ParseError} if the
+      # given text does not contain valid json markup for a problem.
+      # @param [String] json            JSON markup
+      # @return [String] rendered HTML
+      def problem(json)
+        b = '\\' # unescape backslashes
+        problem = Problem.parse(HTML.entities.decode(json).gsub(b, b * 4))
+        problem.save! and problem.render(index: @prob += 1)
+      end
+
+      # Prepares a block image. Raises {RenderError} or {ParseError} if the
+      # given text does not contain a valid image block.
+      def block_image(text)
+        image = Image.parse(text)
+        image.render(index: @img += 1)
+      end
+
+      # Wraps the given text with header tags.
+      # @return [String] wrapped text
+      def h(text, level)
+        "<h#{level}>#{text}</h#{level}>"
+      end
+
+      # Wraps the given text with paragraph tags.
+      # @param [String] text            paragraph text
+      # @return [String] wrapped text
+      def p(text)
+        '<p>' + text + '</p>'
       end
 
     end

data/lib/aladdin/render/multi.rb

@@ -0,0 +1,40 @@
+# ~*~ encoding: utf-8 ~*~
+module Aladdin
+
+  module Render
+
+    # Renders multiple choice questions marked up in JSON 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 JSON 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 json contains a valid MCQ.
+      # @return [Boolean] true iff the json contains a valid MCQ.
+      def valid?
+        super and
+          @json[ANSWER].is_a? String and
+          @json.has_key?(OPTIONS) and
+          @json[OPTIONS].is_a? Hash
+      end
+
+    end
+
+  end
+
+end

data/lib/aladdin/render/navigation.rb

@@ -0,0 +1,34 @@
+# ~*~ encoding: utf-8 ~*~
+module Aladdin
+
+  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
+      # @return [Fixnum] section index
+      def <<(heading)
+        @sections << heading
+        @sections.size - 1
+      end
+
+      # Renders the navigation bar in HTML.
+      def render(locals={})
+        super locals.merge(sections: @sections)
+      end
+
+    end
+
+  end
+
+end

data/lib/aladdin/render/problem.rb

@@ -0,0 +1,114 @@
+# ~*~ encoding: utf-8 ~*~
+module Aladdin
+
+  module Render
+
+    # Renders a single problem. This class doesn't do anything useful; use the
+    # child classes (e.g. {Aladdin::Render::Multi}) instead. Child classes should
+    # override {#valid?}.
+    class Problem < Template
+
+      # Required key in JSON markup. Value indicates type of problem.
+      FORMAT = 'format'
+
+      # Required key in JSON markup. Value contains question body.
+      QUESTION = 'question'
+
+      # Required key in JSON markup. Value contains answers.
+      ANSWER = 'answer'
+
+      # Optional key in JSON markup. Value contains problem ID.
+      ID = 'id'
+
+      # Required keys.
+      KEYS = [FORMAT, QUESTION, ANSWER]
+
+      class << self
+
+        # Parses the given text for questions and answers. If the given text
+        # does not contain valid JSON or does not contain the format key, raises
+        # an {Aladdin::Render::ParseError}.
+        # @param [String] text          markdown text
+        def parse(text)
+          json = JSON.parse text
+          if json.is_a?(Hash) and json.has_key?(FORMAT)
+            get_instance(json)
+          else raise ParseError.new("Expected a JSON object containing the #{FORMAT} key.")
+          end
+        rescue JSON::JSONError => e
+          raise ParseError.new(e.message)
+        end
+
+        # Dynamically creates accessor methods for JSON values.
+        # @example
+        #   accessor :id
+        def accessor(*args)
+          args.each { |arg| define_method(arg) { @json[arg] } }
+        end
+
+        # @return [Problem] problem
+        def get_instance(json)
+          klass = Aladdin::Render.const_get(json[FORMAT].capitalize)
+          raise NameError.new unless klass < Problem
+          klass.new(json)
+        rescue NameError
+          raise ParseError.new('Unrecognized format: %p' % json[FORMAT])
+        end
+
+      end
+
+      accessor ID, *KEYS
+
+      # Creates a new problem from the given JSON.
+      # @param [Hash] json          parsed JSON object
+      def initialize(json)
+        @json = json
+        @json[ID] ||= SecureRandom.uuid
+      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?
+        super @json.merge(locals)
+      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(Aladdin::DATA_DIR, id + Aladdin::DATA_EXT)
+        File.open(solution, 'wb+') { |file| Marshal.dump answer, file }
+      end
+
+      # Retrieves the answer from the given JSON object in a serializable form.
+      # @see #serializable
+      # @return [String, Numeric, TrueClass, FalseClass] answer
+      def answer
+        serialize @json[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 JSON, and that the
+      # question is given as a string.
+      # @return [Boolean] true iff the parsed json contains a valid problem.
+      def valid?
+        KEYS.all? { |key| @json.has_key? key } and question.is_a? String
+      end
+
+    end
+
+  end
+
+end

data/lib/aladdin/render/sanitize.rb

@@ -23,7 +23,9 @@ module Aladdin
 
     # white-listed attributes
     ATTRIBUTES = {
-      'a'   => ['href'],
+      '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',

data/lib/aladdin/render/short.rb

@@ -0,0 +1,30 @@
+# ~*~ encoding: utf-8 ~*~
+module Aladdin
+
+  module Render
+
+    # Renders short questions marked up in JSON 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 json contains a valid MCQ.
+      # @return [Boolean] true iff the json contains a valid MCQ.
+      def valid?
+        super and
+          not @json[ANSWER].nil?
+      end
+
+    end
+
+  end
+
+end
+