spirit 0.1.0.pre

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012-2013 Jiunn Haur Lim, Carnegie Mellon University
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,29 @@
+# Spirit
+
+Genie's parser, which parses the Genie Markup Language and produces HTML
+partials. Both Aladdin and Lamp should depend on this gem for all their parsing
+needs.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'spirit'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install spirit
+
+## Usage
+
+### Parsing a document
+
+  Spirit::Document.new(data, opts).render //=> rendered html
+
+### Parsing a manifest
+
+  Spirit::Manifest.new(data, opts) //=> configuration object

data/lib/spirit.rb

@@ -0,0 +1,22 @@
+# ~*~ encoding: utf-8 ~*~
+require 'spirit/logger'
+require 'spirit/constants'
+require 'spirit/errors'
+require 'spirit/document'
+require 'spirit/manifest'
+
+module Spirit
+  extend self
+
+  attr_reader :logger
+
+  # Initializes the logger. It takes the same arguments as +Logger::new+.
+  # Invoke this at the beginning if you wish {Spirit} to log to another
+  # location than +STDOUT+.
+  def initialize_logger(output=STDOUT, *args)
+    @logger = Logger.new output, *args
+  end
+
+  initialize_logger
+
+end

data/lib/spirit/constants.rb

@@ -0,0 +1,27 @@
+# ~*~ encoding: utf-8 ~*~
+require 'tmpdir'
+
+module Spirit
+
+  # Path to templates
+  VIEWS = File.join File.dirname(__FILE__), *%w(.. .. views)
+
+  # Markdown extensions for Redcarpet
+  MARKDOWN_EXTENSIONS = {
+    no_intra_emphasis:  true,
+    tables:             true,
+    fenced_code_blocks: true,
+    autolink:           true,
+    strikethrough:      true,
+  }
+
+  SOLUTION_DIR = Dir.tmpdir
+  SOLUTION_EXT = '.sol'
+
+  # Name of index page.
+  INDEX     = 'index.md'
+
+  # Name of manifest file.
+  MANIFEST  = 'manifest.yml'
+
+end

data/lib/spirit/document.rb

@@ -0,0 +1,51 @@
+# ~*~ encoding: utf-8 ~*~
+require 'spirit/constants'
+require 'spirit/errors'
+require 'spirit/render'
+
+module Spirit
+
+  # Document written in Genie Markup Language.
+  # @todo TODO clean?
+  class Document
+
+    attr_accessor :data, :engine
+
+    # Creates a new document from the given source. It should contain valid
+    # markdown + embedded YAML.
+    # @param [#read, #to_str] source
+    # @param [Hash] opts         options for {::Redcarpet}
+    def initialize(source, opts={})
+      opts = MARKDOWN_EXTENSIONS.merge opts
+      rndr = Render::HTML.new
+      @engine = ::Redcarpet::Markdown.new(rndr, opts)
+      @data   = case
+                when source.respond_to?(:to_str) then source.to_str
+                when source.respond_to?(:read) then source.read
+                else nil end
+    end
+
+    # @return [Boolean] true iff if was a clean parse with no errors.
+    def clean?
+      # TODO
+    end
+
+    # Rendered output is returned as a string if +anIO+ is not provided. The
+    # output is sanitized with {Spirit::Render::Sanitize}, and should be
+    # considered safe for embedding into a HTML page without further escaping or
+    # sanitization.
+    #
+    # @param [IO] anIO  if given, the HTML partial will be written to it.
+    # @return [String]  if +anIO+ was not provided, returns the HTML string.
+    # @return [Fixnum]  if +anIO+ was provided, returns the number of bytes
+    #                   written.
+    # @raise [Spirit::Error] if a fatal error is encountered.
+    def render(anIO=nil)
+      output = engine.render(data)
+      return anIO.write(output) unless anIO.nil?
+      output
+    end
+
+  end
+
+end

data/lib/spirit/errors.rb

@@ -0,0 +1,12 @@
+# ~*~ encoding: utf-8 ~*~
+module Spirit
+
+  # The base exception for all {Spirit} errors. Raised if the parser is unable
+  # to continue.
+  class Error < StandardError; end
+
+  class DocumentError < Error; end
+
+  class ManifestError < Error; end
+
+end

data/lib/spirit/logger.rb

@@ -0,0 +1,49 @@
+# ~*~ encoding: utf-8 ~*~
+require 'active_support/core_ext/logger'
+
+module Spirit
+
+  # @see https://github.com/chriseppstein/compass/blob/stable/lib/compass/logger.rb
+  class Logger < ::Logger
+
+    COLORS = { clear: 0, red: 31, green: 32, blue: 35, yellow: 33, grey: 37 }
+
+    ACTION_COLORS = {
+      :error     => :red,
+      :warning   => :yellow,
+      :problem   => :blue,
+    }
+
+    # Record that an action has occurred.
+    def record(action, *args)
+      msg = ''
+      msg << color(ACTION_COLORS[action])
+      msg << action_padding(action) + action.to_s
+      msg << color(:clear)
+      msg << ' ' + args.join(' ')
+      info msg
+    end
+
+    private
+
+    def color(c)
+      (c and code = COLORS[c.to_sym]) ? "\e[#{code}m" : ''
+    end
+
+    # Adds padding to the left of an action that was performed.
+    def action_padding(action)
+      ' ' * [(max_action_length - action.to_s.length), 0].max
+    end
+
+    # the maximum length of all the actions known to the logger.
+    def max_action_length
+      @max_action_length ||= actions.reduce(0) { |m, a| [m, a.to_s.length].max }
+    end
+
+    def actions
+      @actions ||= ACTION_COLORS.keys
+    end
+
+  end
+
+end

data/lib/spirit/manifest.rb

@@ -0,0 +1,79 @@
+# ~*~ encoding: utf-8 ~*~
+require 'active_support/core_ext/hash'
+require 'active_support/core_ext/string'
+
+module Spirit
+
+  # Manifest described in YAML. Values in this hash should not be trusted,
+  # since they are provided by the user.
+  class Manifest < Hash
+
+    # Expected types.
+    TYPES = {
+      verify: { 'bin' => 'string', 'arg_prefix' => 'string' },
+      title: 'string',
+      description: 'string',
+      categories: %w(string),
+      static_paths: %w(string)
+    }
+
+    # Creates a new configuration hash from the given source.
+    def initialize(hash)
+      super nil
+      hash ||= {}
+      bad_file(hash.class) unless hash.is_a? Hash
+      merge! hash.symbolize_keys
+      check_types
+    end
+
+    # Load configuration from given string.
+    # @param [String] source
+    # @return [Manifest] manifest
+    def self.load(source)
+      new YAML.load source
+    rescue ::Psych::SyntaxError => e
+      raise ManifestError, e.message
+    end
+
+    # Load configuration from given yaml file.
+    # @param [String] path
+    # @return [Manifest] manifest
+    def self.load_file(path)
+      File.open(path, 'r:utf-8') { |f| new YAML.load f.read }
+    rescue ::Psych::SyntaxError => e
+      raise ManifestError, e.message
+    end
+
+    private_class_method :new
+
+    private
+
+    # Checks that the given hash has the valid types for each value, if they
+    # exist.
+    # @raise [ManifestError] if a bad type is encountered.
+    def check_types(key='root', expected=TYPES, actual=self, opts={})
+      bad_type(key, expected, actual, opts) unless actual.is_a? expected.class
+      case actual
+      when Hash then actual.each { |k, v| check_types(k, expected[k], v) }
+      when Enumerable then actual.each { |v| check_types(key, expected.first, v, enum: true) }
+      end
+    end
+
+    def bad_file(type)
+      raise ManifestError, <<-eos.squish
+        The manifest file should contain a dictionary, but a #{type.name} was
+        found.
+      eos
+    end
+
+    def bad_type(key, expected, actual, opts={})
+      verb = opts[:enum] ? 'contain' : 'be'
+      raise ManifestError, <<-eos.squish
+        The #{key} option in the manifest file should #{verb} a #{expected.class.name}
+        instead of a #{actual.class.name}.
+      eos
+    end
+
+  end
+
+end

data/lib/spirit/render.rb

@@ -0,0 +1,6 @@
+# ~*~ encoding: utf-8 ~*~
+require 'albino'
+require 'haml'
+require 'redcarpet'
+
+require 'spirit/render/html'

data/lib/spirit/render/errors.rb

@@ -0,0 +1,11 @@
+# ~*~ encoding: utf-8 ~*~
+module Spirit
+
+  module Render
+
+    # The base exception for {Spirit::Render} errors.
+    class RenderError < DocumentError; end
+
+  end
+
+end

data/lib/spirit/render/html.rb

@@ -0,0 +1,138 @@
+# ~*~ encoding: utf-8 ~*~
+require 'spirit/render/errors'
+require 'spirit/render/sanitize'
+require 'spirit/render/templates'
+
+module Spirit
+
+  module Render
+
+    # HTML Renderer for Genie Markup Language, which is just GitHub Flavored
+    # Markdown with Embedded YAML for describing problems. Designed for use
+    # with Redcarpet.
+    # @see Spirit::Tilt::Template
+    # @see http://github.github.com/github-flavored-markdown/
+    class HTML < ::Redcarpet::Render::HTML
+
+      @sanitize = Sanitize.new
+      class << self; attr_reader :sanitize end
+
+      # Paragraphs that start and end with '---' are treated as embedded YAML
+      # and are parsed for questions/answers.
+      PROBLEM_REGEX = /^"""$(.*?)^"""$/m
+
+      # Paragraphs that only contain images are rendered with {Spirit::Render::Image}.
+      IMAGE_REGEX = /\A\s*<img[^<>]+>\s*\z/m
+
+      # Renderer configuration options.
+      CONFIGURATION = {
+        hard_wrap:          true,
+        no_styles:          true,
+      }
+
+      # Creates a new HTML renderer.
+      # @param [Hash] options        described in the RedCarpet documentation.
+      def initialize(options={})
+        super CONFIGURATION.merge options
+        @nav, @headers = Navigation.new, Headers.new
+        @prob, @img = 0, 0 # indices for Problem #, Figure #
+      end
+
+      # Pygmentizes code blocks.
+      # @param [String] code        code block contents
+      # @param [String] marker      name of language, for syntax highlighting
+      # @return [String] highlighted code
+      def block_code(code, marker)
+        #language, type, id = (marker || 'text').split ':'
+        #highlighted = Albino.colorize code, language
+        language, _, _ = (marker || 'text').split ':'
+        Albino.colorize code, language
+        # TODO
+        #case type
+        #when 'demo', 'test'
+        #  executable id: id, raw: code, colored: highlighted
+        #else highlighted end
+      end
+
+      # Detects block images and renders them as such.
+      # @return [String] rendered html
+      def paragraph(text)
+        case text
+        when IMAGE_REGEX then block_image(text)
+        else p(text) end
+      rescue RenderError => e # fall back to paragraph
+        Spirit.logger.warn e.message
+        p(text)
+      end
+
+      # Increases all header levels by one and keeps a navigation bar.
+      # @return [String] rendered html
+      def header(text, level)
+        html, name = h(text, level += 1)
+        @nav.append(text, name) if level == 2
+        html
+      end
+
+      # Runs a first pass through the document to look for problem blocks.
+      # @param [String] document    markdown document
+      def preprocess(document)
+        document.gsub(PROBLEM_REGEX) { |yaml| problem $1 }
+      end
+
+      # Sanitizes the final document.
+      # @param [String]  document    html document
+      # @return [String] sanitized document
+      def postprocess(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. Returns +yaml+ if the given text does not
+      # contain valid yaml markup for a problem.
+      # @param [String] yaml            YAML markup
+      # @return [String] rendered HTML
+      def problem(yaml)
+        problem = Problem.parse(yaml)
+        Spirit.logger.record :problem, "ID: #{problem.id}"
+        problem.save! and problem.render(index: @prob += 1)
+      rescue RenderError
+        yaml
+      end
+
+      # Prepares a block image. Raises {RenderError} if the given text does not
+      # contain a valid image block.
+      # @param  [String] text         markdown text
+      # @return [String] rendered HTML
+      def block_image(text)
+        Image.parse(text).render(index: @img += 1)
+      end
+
+      # Wraps the given text with header tags.
+      # @return [String] rendered HTML
+      # @return [String] anchor name
+      def h(text, level)
+        header = @headers.add(text, level)
+        return header.render, header.name
+      end
+
+      # Wraps the given text with paragraph tags.
+      # @param [String] text            paragraph text
+      # @return [String] rendered html
+      def p(text)
+        '<p>' + text + '</p>'
+      end
+
+    end
+
+  end
+end