mint 0.2.9 → 0.5.0

data/features/publish.feature

@@ -0,0 +1,73 @@
+Feature: Publish document with varying options at the command line
+  As a writer
+  I want to create a document at the command line from plain text
+  So that I can view a typeset version in a web browser
+
+  Background:
+    Given a file named "content.md" with:
+      """
+      Header
+      ======
+
+      This is a test. It is theoretically formatted in
+      the Markdown templating language.
+      """
+
+    And a file named "style.sass" with:
+      """
+      p
+        margin: 0
+      """
+
+    And a file named "layout.haml" with:
+      """
+      %html
+        %head
+          %link(rel='stylesheet' href=stylesheet)
+
+        %body
+          #container= content
+      """
+
+  Scenario: Publish document with defaults
+    When I run `mint publish content.md`
+    Then a file named "content.md" should exist
+    And a file named "content.html" should exist
+
+  Scenario Outline: Publish document with named template, layout & style
+    When I run `mint publish <template> <layout> <style> content.md`
+    Then a file named "content.html" should exist
+    And the file "content.html" should contain "This is a test"
+    And a file named "<style file>" should exist
+    And the file "content.html" should match /templates.*style.css/
+    And the file "content.html" should contain "<style file>"
+
+    Examples:
+      | template | layout | style  | style file                            |
+      |          |        |        | ../../templates/default/css/style.css |
+      | -t pro   |        |        | ../../templates/pro/css/style.css     |
+      |          | -l pro | -s pro | ../../templates/pro/css/style.css     |
+
+  Scenario: Publish document with non-existent template
+    When I run `mint publish -t nonexistent content.md`
+    Then the stderr should contain "Template 'nonexistent' does not exist."
+
+  Scenario: Publish document in directory
+    When I run `mint publish content.md -d compiled`
+    Then a file named "compiled/content.html" should exist
+
+  Scenario: Publish document in subdirectory
+    When I run `mint publish content.md -d compiled/chapter-1`
+    Then a file named "compiled/chapter-1/content.html" should exist
+
+  Scenario: Publish document with default style and explicit style destination
+    When I run `mint publish content.md -n styles`
+    Then a file named "styles/style.css" should exist
+
+  Scenario: Publish document with hand-crafted style and explicit style destination
+    When I run `mint publish content.md -n styles -s style.sass`
+    Then a file named "styles/style.css" should exist
+
+  Scenario: Publish document with hand-crafted layout
+    When I run `mint publish content.md -l layout.haml`
+    Then the file "content.html" should match /id=['"]container['"]/

data/features/support/env.rb

@@ -4,7 +4,7 @@ $LOAD_PATH.unshift File.expand_path('../../../lib', __FILE__)
 
 module ArubaOverrides
   def detect_ruby(cmd)
-    if cmd =~ /^mint /
+    if cmd =~ /^mint/
       "ruby -I ../../lib -S ../../bin/#{cmd}"
     else
       super(cmd)

data/lib/mint.rb

@@ -8,3 +8,4 @@ require 'mint/version'
 require 'mint/css'
 require 'mint/commandline'
 require 'mint/exceptions'
+require 'mint/plugin'

data/lib/mint/commandline.rb

@@ -144,7 +144,7 @@ module Mint
       config_directory = Mint.path_for_scope(scope, true)
       config_file = config_directory + Mint.files[:config]
       Helpers.ensure_directory config_directory
-      Helpers.update_yaml opts, config_file
+      Helpers.update_yaml! opts, config_file
     end
 
     # Tries to set a config option (at the specified scope) per 
@@ -184,7 +184,7 @@ module Mint
     # @param [Hash, #[]] commandline_options a structured set of configuration options
     #   that will guide Mint.publish!
     # @return [void]
-    def self.mint(files, commandline_options)
+    def self.publish!(files, commandline_options)
       documents = []
       options = configuration_with commandline_options
       
@@ -194,7 +194,7 @@ module Mint
       # change detection
       render_style = true
       files.each do |file|
-        Document.new(file, options).publish!(render_style)
+        Document.new(file, options).publish! :render_style => render_style
         render_style = false
       end
     end

data/lib/mint/document.rb

@@ -4,9 +4,12 @@ require 'mint/style'
 
 module Mint
   class Document < Resource
+    METADATA_DELIM = "\n\n"
+
     # Implicit readers are paired with explicit accessors. This
     # allows for processing variables before storing them.
     attr_reader :content, :layout, :style
+    attr_accessor :metadata
 
     # Passes content through a renderer before assigning it to be
     # the Document's content
@@ -15,7 +18,16 @@ module Mint
     #   from a templating language into HTML
     # @return [void]
     def content=(content)
-      @renderer = Mint.renderer content
+      tempfile = Helpers.generate_temp_file! content
+      original_content = File.read content
+
+      metadata, text = Document.parse_metadata_from original_content
+      self.metadata = metadata
+      intermediate_content = Mint.before_render text
+
+      File.open(tempfile, 'w') {|file| file << intermediate_content }
+
+      @renderer = Mint.renderer tempfile
       @content = @renderer.render
     end
 
@@ -71,7 +83,7 @@ module Mint
     # The style_destination attribute is lazy. It's exposed via
     # virtual attributes like #style_destination_file.
     attr_reader :style_destination
-    #
+    
     # @param [String] style_destination the subdirectory into
     #   which styles will be rendered or copied
     # @return [void]
@@ -153,12 +165,14 @@ module Mint
 
     # Renders content in the context of layout and returns as a String.
     def render(args={})
-      layout.render self, args
+      intermediate_content = layout.render self, args
+      Mint.after_render(intermediate_content)
     end
 
     # Writes all rendered content where a) possible, b) required,
     # and c) specified. Outputs to specified file.
-    def publish!(render_style=true)      
+    def publish!(opts={})      
+      options = { :render_style => true }.merge(opts)
       FileUtils.mkdir_p self.destination_directory
       File.open(self.destination_file, 'w+') do |f|
         f << self.render
@@ -168,12 +182,14 @@ module Mint
       # b) it actually needs rendering (i.e., it's in template form and
       # not raw, browser-parseable CSS) or it if it doesn't need
       # rendering but there is an explicit style_destination.
-      if render_style
+      if options[:render_style]
         FileUtils.mkdir_p style_destination_directory
         File.open(self.style_destination_file, 'w+') do |f|
           f << self.style.render
         end
       end
+
+      Mint.after_publish(self, opts)
     end
 
     # Convenience methods for views
@@ -184,5 +200,30 @@ module Mint
       Helpers.normalize_path(self.style_destination_file,
                              self.destination_directory).to_s
     end
+
+    protected
+
+    def self.metadata_chunk(text)
+      text.split(METADATA_DELIM).first
+    end
+
+    def self.metadata_from(text)
+      raw_metadata = YAML.load metadata_chunk(text)
+      raw_metadata.is_a?(String) ? {} : raw_metadata
+    rescue
+      {}
+    end
+
+    def self.parse_metadata_from(text)
+      metadata = metadata_from text
+      new_text =
+        if !metadata.empty?
+          text.sub metadata_chunk(text) + METADATA_DELIM, ''
+        else
+          text
+        end
+
+      [metadata, new_text]
+    end
   end
 end

data/lib/mint/helpers.rb

@@ -1,8 +1,23 @@
 require 'pathname'
+require 'tempfile'
 require 'yaml'
+require 'active_support/core_ext/string/inflections'
 
 module Mint
   module Helpers    
+    def self.underscore(obj, opts={})
+      namespaces = obj.to_s.split('::').map do |namespace|
+        if opts[:ignore_prefix]
+          namespace[0..1].downcase + namespace[2..-1]
+        else
+          namespace
+        end
+      end
+
+      string = opts[:namespaces] ? namespaces.join('::') : namespaces.last
+      string.underscore
+    end
+
     # Transforms a String into a URL-ready slug. Properly handles
     # ampersands, non-alphanumeric characters, extra hyphens and spaces.
     #
@@ -41,12 +56,14 @@ module Mint
     #
     # @param [Hash, #[]] map a potentially nested Hash containing symbolizable keys
     # @return [Hash] a version of map where all keys are symbols
-    def self.symbolize_keys(map)
+    def self.symbolize_keys(map, opts={})
+      transform = lambda {|x| opts[:downcase] ? x.downcase : x }
+
       map.reduce(Hash.new) do |syms,(k,v)| 
-        syms[k.to_sym] = 
+        syms[transform[k].to_sym] = 
           case v
           when Hash
-            self.symbolize_keys(v)
+            self.symbolize_keys(v, opts)
           else
             v
           end
@@ -54,6 +71,38 @@ module Mint
       end
     end
 
+    def self.listify(list)
+      if list.length > 2
+        list[0..-2].join(', ') + ' & ' + list.last
+      else
+        list.join(' & ')
+      end
+    end
+
+    def self.standardize(metadata, opts={})
+      table = opts[:table] || {}
+      metadata.reduce({}) do |hash, (key,value)|
+        if table[key] && table[key].length == 2
+          standard_key, standard_type = table[key]
+          standard_value =
+            case standard_type
+            when :array
+              [*value]
+            when :string
+              value
+            else
+              # If key/type were not in table
+              value
+            end
+
+          hash[standard_key] = standard_value
+        else
+          hash[key] = value
+        end
+        hash
+      end
+    end
+
     # Returns the relative path to to_directory from from_directory. 
     # If to_directory and from_directory have no parents in common besides 
     # /, returns the absolute directory of to_directory. Assumes no symlinks.
@@ -77,12 +126,24 @@ module Mint
     # @param [Hash, #[]] new_opts a set of options to add to the Yaml file
     # @param [Pathname, #exist] file a file to read from and write to
     # @return [void] 
-    def self.update_yaml(new_opts, file)
+    def self.update_yaml!(new_opts, file)
       curr_opts = file.exist? ? YAML.load_file(file) : {}
 
       File.open file, 'w' do |f|
         YAML.dump(curr_opts.merge(new_opts), f)
       end
     end
+
+    def self.generate_temp_file!(file)
+      basename  = File.basename file
+      extension = File.extname file
+      content   = File.read file
+
+      tempfile = Tempfile.new([basename, extension])
+      tempfile << content
+      tempfile.flush
+      tempfile.close
+      tempfile.path
+    end
   end
 end

data/lib/mint/mint.rb

@@ -141,11 +141,10 @@ module Mint
     find_files = lambda {|x| Pathname.glob "#{x.to_s}.*" }
     acceptable = lambda {|x| x.to_s =~ /#{Mint.formats.join '|'}/ }
 
-    template = Mint.path(true).map(&file_name).map(&find_files).flatten.
-      select(&acceptable).select(&:exist?).first.to_s
-    raise TemplateNotFoundException unless template
-
-    template
+    Mint.path(true).map(&file_name).map(&find_files).flatten.
+      select(&acceptable).select(&:exist?).first.tap do |template|
+      raise TemplateNotFoundException unless template
+    end.to_s
   end
 
   # Checks (non-rigorously) to see if the file is somewhere on the
@@ -185,7 +184,7 @@ module Mint
   #
   # @param [Document] document a Mint document
   # @return [void]
-  def self.publish!(document)
-    document.publish!
+  def self.publish!(document, opts={})
+    document.publish! opts
   end
 end

data/lib/mint/plugin.rb

@@ -0,0 +1,136 @@
+require 'mint/document'
+require 'set'
+
+module Mint
+  def self.plugins
+    @@plugins ||= Set.new
+    @@plugins.to_a
+  end
+
+  def self.activated_plugins
+    @@activated_plugins ||= Set.new
+    @@activated_plugins.to_a
+  end
+
+  def self.register_plugin!(plugin)
+    @@plugins ||= Set.new
+    @@plugins << plugin
+  end
+
+  def self.activate_plugin!(plugin)
+    @@activated_plugins ||= Set.new
+    @@activated_plugins << plugin
+  end
+
+  def self.clear_plugins!
+    defined?(@@plugins) && @@plugins.clear
+    defined?(@@activated_plugins) && @@activated_plugins.clear
+  end
+
+  def self.template_directory(plugin)
+    Mint.root + '/plugins/templates/' + plugin.underscore
+  end
+
+  def self.config_directory(plugin)
+    Mint.root + '/plugins/config/' + plugin.underscore
+  end
+
+  def self.commandline_options_file(plugin)
+    plugin.config_directory + '/syntax.yml'
+  end
+
+  def self.commandline_name(plugin)
+    plugin.underscore
+  end
+
+  def self.before_render(plain_text, opts={})
+    active_plugins = opts[:plugins] || Mint.activated_plugins
+    active_plugins.reduce(plain_text) do |intermediate, plugin|
+      plugin.before_render(intermediate)
+    end
+  end
+
+  def self.after_render(html_text, opts={})
+    active_plugins = opts[:plugins] || Mint.activated_plugins
+    active_plugins.reduce(html_text) do |intermediate, plugin|
+      plugin.after_render(intermediate)
+    end
+  end
+
+  def self.after_publish(document, opts={})
+    active_plugins = opts[:plugins] || Mint.activated_plugins
+    active_plugins.each do |plugin|
+      plugin.after_publish(document)
+    end
+  end
+
+  class Plugin
+    def self.inherited(plugin)
+      Mint.register_plugin! plugin
+    end
+
+    def self.underscore(opts={})
+      opts[:ignore_prefix] ||= true
+      Helpers.underscore self.name, :ignore_prefix => opts[:ignore_prefix]
+    end
+
+    def self.template_directory
+      Mint.template_directory(self)
+    end
+
+    def self.config_directory
+      Mint.config_directory(self)
+    end
+
+    def self.commandline_options_file
+      Mint.commandline_options_file(self)
+    end
+
+    def self.commandline_name
+      Mint.commandline_name(self)
+    end
+
+    # Supports:
+    # - Change raw text
+    #
+    # Use cases:
+    # - Add footnote syntax on top of Markdown
+    # - Perform text analysis for use in later callbacks (?)
+    def self.before_render(text_document)
+      text_document
+    end
+
+    # Supports:
+    # - Change preview HTML
+    #
+    # Use cases:
+    # - Transform elements based on position or other HTML attributes
+    #   For example: Add a class to the first paragraph of a document if it is
+    #   italicized
+    #
+    # Questions:
+    # - Could I allow jQuery use here?
+    def self.after_render(html_document)
+      html_document
+    end
+
+    # Supports:
+    # - Change file, filesystem once written
+    # - Automatic cleanup of intermediate files, including all edge cases
+    #   currently covered by transformation library. (For example, if I generated
+    #   a CSS file but am ultimately generating a PDF, I would want to have 
+    #   an automatic way to delete that CSS file.)
+    #
+    # Use cases:
+    # - Zip set of documents into ePub and create manifest 
+    # - Change file extension
+    # - Generate PDF from emitted HTML and get rid of intermediate files
+    # - Generate .doc (or any other OO UNO format) and get rid of intermediate files
+    #
+    # NOTE: Unlike the other two callbacks, this doesn't use the result of 
+    #   the callback expression for anything. This callback is purely for 
+    #   side effects like rearranging the file system.
+    def self.after_publish(document)
+    end
+  end
+end