kramdown 0.4.0 → 0.5.0

data/lib/kramdown/document.rb

@@ -26,10 +26,22 @@ require 'kramdown/version'
 require 'kramdown/error'
 require 'kramdown/parser'
 require 'kramdown/converter'
-require 'kramdown/extension'
+require 'kramdown/options'
 
 module Kramdown
 
+  # Return the data directory for kramdown.
+  def self.data_dir
+    unless defined?(@@data_dir)
+      require 'rbconfig'
+      @@data_dir = File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'data', 'kramdown'))
+      @@data_dir = File.expand_path(File.join(Config::CONFIG["datadir"], "kramdown")) if !File.exists?(@@data_dir)
+      raise "kramdown data directory not found! This is a bug, please report it!" unless File.directory?(@@data_dir)
+    end
+    @@data_dir
+  end
+
+
   # The main interface to kramdown.
   #
   # This class provides a one-stop-shop for using kramdown to convert text into various output
@@ -39,59 +51,12 @@ module Kramdown
   #   doc = Kramdown::Document.new('This *is* some kramdown text')
   #   puts doc.to_html
   #
-  # The #to_html method is a shortcut for using the Converter::ToHtml class. If other converters are
-  # added later, there may be additional shortcut methods.
+  # The #to_html method is a shortcut for using the Converter::Html class.
   #
-  # The second argument to the #new method is an options hash for customizing the behaviour of
-  # kramdown.
+  # The second argument to the #new method is an options hash for customizing the behaviour of the
+  # kramdown parser and the converters.
   class Document
 
-    # Currently available options are:
-    #
-    # [:auto_ids (used by the parser)]
-    #    A boolean value deciding whether automatic header ID generation is used. Default: +false+.
-    #
-    # [:coderay (used by the HTML converter)]
-    #    A hash containing options for the CodeRay syntax highlighter. If this is set to +nil+,
-    #    syntax highlighting is disabled. When using the +options+ extension, any CodeRay option can
-    #    be set by prefixing it with +coderay_+.
-    #
-    #    Default:
-    #      {:wrap => :div, :line_numbers => :inline, :line_number_start => 1,
-    #       :tab_width => 8, :bold_every => 10, :css => :style}
-    #
-    # [:filter_html (used by the HTML converter)]
-    #    An array of HTML tag names that defines which tags should be filtered from the output. For
-    #    example, if the value contains +iframe+, then all HTML +iframe+ tags are filtered out and
-    #    only the body is displayed. Default: empty array. When using the +options+ extension, the
-    #    string value needs to hold the HTML tag names separated by one or more spaces.
-    #
-    # [:footnote_nr (used by the HTML converter)]
-    #    The initial number used for creating the link to the first footnote. Default: +1+. When
-    #    using the +options+ extension, the string value needs to be a valid number.
-    #
-    # [:parse_block_html (used by the parser)]
-    #    A boolean value deciding whether kramdown syntax is processed in block HTML tags. Default:
-    #    +false+.
-    #
-    # [:parse_span_html (used by the parser)]
-    #    A boolean value deciding whether kramdown syntax is processed in span HTML tags. Default:
-    #    +true+.
-    #
-    # When using the +options+ extension, all boolean values can be set to false by using the
-    # string 'false' or an empty string, any other non-empty string will be converted to the value
-    # +true+.
-    DEFAULT_OPTIONS={
-      :footnote_nr => 1,
-      :filter_html => [],
-      :auto_ids => true,
-      :parse_block_html => false,
-      :parse_span_html => true,
-      :coderay => {:wrap => :div, :line_numbers => :inline,
-        :line_number_start => 1, :tab_width => 8, :bold_every => 10, :css => :style}
-    }
-
-
     # The element tree of the document. It is immediately available after the #new method has been
     # called.
     attr_accessor :tree
@@ -101,33 +66,38 @@ module Kramdown
     attr_accessor :options
 
     # An array of warning messages. It is filled with warnings during the parsing phase (i.e. in
-    # #new) and the converting phase.
+    # #new) and the conversion phase.
     attr_reader :warnings
 
     # Holds needed parse information like ALDs, link definitions and so on.
     attr_reader :parse_infos
 
-    # Holds an instance of the extension class.
-    attr_reader :extension
+    # Holds conversion information which is dependent on the used converter. A converter clears this
+    # variable before duing the conversion.
+    attr_reader :conversion_infos
 
 
-    # Create a new Kramdown document from the string +source+ and use the provided +options+ (see
-    # DEFAULT_OPTIONS for a list of available options). The +source+ is immediately parsed by the
-    # kramdown parser sothat after this call the output can be generated.
-    #
-    # The parameter +ext+ can be used to set a custom extension class. Note that the default
-    # kramdown extensions should be available in the custom extension class.
-    def initialize(source, options = {}, ext = nil)
-      @options = DEFAULT_OPTIONS.merge(options)
+    # Create a new Kramdown document from the string +source+ and use the provided +options+. The
+    # +source+ is immediately parsed by the kramdown parser sothat after this call the output can be
+    # generated.
+    def initialize(source, options = {})
+      @options = Options.merge(options)
       @warnings = []
       @parse_infos = {}
-      @extension = extension || Kramdown::Extension.new
+      @conversion_infos = {}
       @tree = Parser::Kramdown.parse(source, self)
     end
 
-    # Convert the document to HTML. Uses the Converter::ToHtml class for doing the conversion.
-    def to_html
-      Converter::Html.convert(self)
+    # Check if a method is invoked that begins with +to_+ and if so, try to instantiate a converter
+    # class and use it for converting the document.
+    #
+    # For example, +to_html+ would instantiate the Converter::Html class.
+    def method_missing(id, *attr, &block)
+      if id.to_s =~ /^to_(\w+)$/
+        Converter.const_get($1.capitalize).convert(self)
+      else
+        super
+      end
     end
 
     def inspect #:nodoc:

data/lib/kramdown/options.rb

@@ -0,0 +1,262 @@
+# -*- coding: utf-8 -*-
+#
+#--
+# Copyright (C) 2009 Thomas Leitner <t_leitner@gmx.at>
+#
+# This file is part of kramdown.
+#
+# kramdown is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#++
+#
+
+module Kramdown
+
+  # This module defines all options that are used by parsers and/or converters.
+  module Options
+
+    # Helper class introducing a boolean type for specifying boolean values (+true+ and +false+) as
+    # option types.
+    class Boolean
+
+      # Return +true+ if +other+ is either +true+ or +false+
+      def self.===(other)
+        FalseClass === other || TrueClass === other
+      end
+
+    end
+
+    # ----------------------------
+    # :section: Option definitions
+    #
+    # This sections informs about the methods that can be used on the Options class.
+    # ----------------------------
+
+    # Contains the definition of an option.
+    Definition = Struct.new(:name, :type, :default, :desc)
+
+    # Allowed option types
+    ALLOWED_TYPES = [String, Integer, Float, Symbol, Boolean, Array, Object]
+
+    @options = {}
+
+    # Define a new option called +name+ (a Symbol) with the given +type+ (String, Integer, Float,
+    # Symbol, Boolean, Array, Object), default value +default+ and the description +desc+.
+    #
+    # The type 'Object' should only be used if none of the other types suffices because such an
+    # option will be opaque!
+    def self.define(name, type, default, desc)
+      raise ArgumentError, "Option name #{name} is already used" if @options.has_key?(name)
+      raise ArgumentError, "Invalid option type #{type} specified" if !ALLOWED_TYPES.include?(type)
+      raise ArgumentError, "Invalid type for default value" if !(type === default) && !default.nil?
+      @options[name] = Definition.new(name, type, default, desc)
+    end
+
+    # Return all option definitions.
+    def self.definitions
+      @options
+    end
+
+    # Return +true+ if an option +name+ is defined.
+    def self.defined?(name)
+      @options.has_key?(name)
+    end
+
+    # Return a Hash with the default values for all options.
+    def self.defaults
+      temp = {}
+      @options.each {|n, o| temp[o.name] = o.default}
+      temp
+    end
+
+    # Merge the #defaults Hash with the parsed options from the given Hash.
+    def self.merge(hash)
+      temp = defaults
+      hash.each do |k,v|
+        next unless @options.has_key?(k)
+        temp[k] = parse(k, v)
+      end
+      temp
+    end
+
+    # Parse the given value +data+ as if it was a value for the option +name+ and return the parsed
+    # value with the correct type.
+    #
+    # If +data+ already has the correct type, it is just returned. Otherwise it is converted to a
+    # String and then to the correct type.
+    def self.parse(name, data)
+      raise ArgumentError, "No option named #{name} defined" if !@options.has_key?(name)
+      return data if @options[name].type === data
+      data = data.to_s
+      if @options[name].type == String
+        data
+      elsif @options[name].type == Integer
+        Integer(data)
+      elsif @options[name].type == Float
+        Float(data)
+      elsif @options[name].type == Symbol
+        (data.strip.empty? ? nil : data.to_sym)
+      elsif @options[name].type == Boolean
+        data.downcase.strip != 'false' && !data.empty?
+      elsif @options[name].type == Array
+        data.split(/\s+/)
+      end
+    end
+
+    # ----------------------------
+    # :section: Option Definitions
+    #
+    # This sections contains all option definitions that are used by the included
+    # parsers/converters.
+    # ----------------------------
+
+    define(:template, String, '', <<EOF)
+The name of an ERB template file that should be used to wrap the output
+
+This is used to wrap the output in an environment so that the output can
+be used as a stand-alone document. For example, an HTML template would
+provide the needed header and body tags so that the whole output is a
+valid HTML file. If no template is specified, the output will be just
+the converted text.
+
+When resolving the template file, the given template name is used first.
+If such a file is not found, the converter extension is appended. If the
+file still cannot be found, the templates name is interpreted as a
+template name that is provided by kramdown (without the converter
+extension).
+
+kramdown provides a default template named 'default' for each converter.
+
+Default: ''
+Used by: all converters
+EOF
+
+    define(:auto_ids, Boolean, true, <<EOF)
+Use automatic header ID generation
+
+If this option is `true`, ID values for all headers are automatically
+generated if no ID is explicitly specified.
+
+Default: true
+Used by: kramdown parser
+EOF
+
+    define(:parse_block_html, Boolean, false, <<EOF)
+Process kramdown syntax in block HTML tags
+
+If this option is `true`, the kramdown parser processes the content of
+block HTML tags as text containing block level elements. Since this is
+not wanted normally, the default is `false`. It is normally better to
+selectively enable kramdown processing via the markdown attribute.
+
+Default: false
+Used by: kramdown parser
+EOF
+
+    define(:parse_span_html, Boolean, true, <<EOF)
+Process kramdown syntax in span HTML tags
+
+If this option is `true`, the kramdown parser processes the content of
+span HTML tags as text containing span level elements.
+
+Default: true
+Used by: kramdown parser
+EOF
+
+    define(:extension, Object, nil, <<EOF)
+An object for handling the extensions
+
+The value for this option needs to be an object that can handle the
+extensions found in a kramdown document. If this option is `nil`, the
+default extension object is used.
+
+Default: nil
+Used by: kramdown parser
+EOF
+
+    define(:footnote_nr, Integer, 1, <<EOF)
+The number of the first footnote
+
+This option can be used to specify the number that is used for the first
+footnote.
+
+Default: 1
+Used by: HTML converter
+EOF
+
+    define(:filter_html, Array, [], <<EOF)
+An array of HTML tags that should be filtered from the output
+
+The value can either be specified as array or as a space separated
+string (which will be converted to an array). All HTML tags that are
+listed in the array will be filtered from the output, i.e. only their
+contents is used. This applies only to HTML tags found in the initial
+document.
+
+Default: []
+Used by: HTML converter
+EOF
+
+    define(:coderay_wrap, Symbol, :div, <<EOF)
+Defines how the highlighted code should be wrapped
+
+The possible values are :span, :div or nil.
+
+Default: :div
+Used by: HTML converter
+EOF
+
+    define(:coderay_line_numbers, Symbol, :inline, <<EOF)
+Defines how and if line numbers should be shown
+
+The possible values are :table, :inline, :list or nil. If this option is
+nil, no line numbers are shown.
+
+Default: :inline
+Used by: HTML converter
+EOF
+
+    define(:coderay_line_number_start, Integer, 1, <<EOF)
+The start value for the line numbers
+
+Default: 1
+Used by: HTML converter
+EOF
+
+    define(:coderay_tab_width, Integer, 8, <<EOF)
+The tab width used in highlighted code
+
+Used by: HTML converter
+EOF
+
+    define(:coderay_bold_every, Integer, 10, <<EOF)
+Defines how often a line number should be made bold
+
+Default: 10
+Used by: HTML converter
+EOF
+
+    define(:coderay_css, Symbol, :style, <<EOF)
+Defines how the highlighted code gets styled
+
+Possible values are :class (CSS classes are applied to the code
+elements, one must supply the needed CSS file) or :style (default CSS
+styles are directly applied to the code elements).
+
+Default: style
+Used by: HTML converter
+EOF
+
+  end
+
+end

data/lib/kramdown/parser/kramdown.rb

@@ -37,10 +37,12 @@ module Kramdown
 
       attr_reader :tree
       attr_reader :doc
+      attr_reader :options
 
       # Create a new Kramdown parser object for the Kramdown::Document +doc+.
       def initialize(doc)
         @doc = doc
+        @extension = @doc.options[:extension] || Kramdown::Parser::Kramdown::Extension.new
 
         @src = nil
         @tree = nil
@@ -84,7 +86,7 @@ module Kramdown
       BLOCK_PARSERS = [:blank_line, :codeblock, :codeblock_fenced, :blockquote, :table, :atx_header,
                        :setext_header, :horizontal_rule, :list, :definition_list, :link_definition, :block_html,
                        :footnote_definition, :ald, :block_ial, :extension_block, :eob_marker, :paragraph]
-      SPAN_PARSERS =  [:emphasis, :codespan, :autolink, :span_html, :footnote_marker, :link,
+      SPAN_PARSERS =  [:emphasis, :codespan, :autolink, :span_html, :footnote_marker, :link, :smart_quotes,
                        :span_ial, :html_entity, :typographic_syms, :line_break, :escaped_chars]
 
       # Adapt the object to allow parsing like specified in the options.
@@ -97,8 +99,13 @@ module Kramdown
             raise Kramdown::Error, "Unknown parser: #{name}"
           end
         end
-        @span_start = Regexp.union(*SPAN_PARSERS.map {|name| @parsers[name].start_re})
-        @span_start_re = /(?=#{@span_start})/
+        @span_start, @span_start_re = span_parser_regexps
+      end
+
+      # Create the needed span parser regexps.
+      def span_parser_regexps(parsers = SPAN_PARSERS)
+        span_start = /#{parsers.map {|name| @parsers[name].span_start}.join('|')}/
+        [span_start, /(?=#{span_start})/]
       end
 
       # Parse all block level elements in +text+ into the element +el+.
@@ -149,10 +156,7 @@ module Kramdown
 
         span_start = @span_start
         span_start_re = @span_start_re
-        if parsers
-          span_start = Regexp.union(*parsers.map {|name| @parsers[name].start_re})
-          span_start_re = /(?=#{span_start})/
-        end
+        span_start, span_start_re = span_parser_regexps(parsers) if parsers
         parsers = parsers || SPAN_PARSERS
 
         used_re = (stop_re.nil? ? span_start_re : /(?=#{Regexp.union(stop_re, span_start)})/)
@@ -171,13 +175,7 @@ module Kramdown
                 false
               end
             end unless stop_re_found
-            if !processed && !stop_re_found
-              if stop_re_matched
-                add_text(@src.scan(/./))
-              else
-                raise Kramdown::Error, 'Bug: please report!'
-              end
-            end
+            add_text(@src.scan(/./)) if !processed && !stop_re_found
           else
             add_text(@src.scan(/.*/m)) unless stop_re
             break
@@ -213,22 +211,42 @@ module Kramdown
         ial.each {|k,v| attr[k] = v if k.kind_of?(String) && k != 'class' }
       end
 
+      # Extract the part of the StringScanner backed string specified by the +range+. This method
+      # also works correctly under Ruby 1.9.
+      def extract_string(range)
+        result = nil
+        if RUBY_VERSION >= '1.9'
+          begin
+            enc = @src.string.encoding
+            @src.string.force_encoding('ASCII-8BIT')
+            result = @src.string[range].force_encoding(enc)
+          ensure
+            @src.string.force_encoding(enc)
+          end
+        else
+          result = @src.string[range]
+        end
+        result
+      end
+
 
       @@parsers = {}
 
       # Holds all the needed data for one block/span level parser.
-      Data = Struct.new(:name, :start_re, :method)
+      Data = Struct.new(:name, :start_re, :span_start, :method)
 
       # Add a parser method
       #
       # * with the given +name+,
       # * using +start_re+ as start regexp
+      # * and, for span parsers, +span_start+ as a String that can be used in a regexp and
+      #   which identifies the starting character(s)
       #
       # to the registry. The method name is automatically derived from the +name+ or can explicitly
       # be set by using the +meth_name+ parameter.
-      def self.define_parser(name, start_re, meth_name = "parse_#{name}")
+      def self.define_parser(name, start_re, span_start = nil, meth_name = "parse_#{name}")
         raise "A parser with the name #{name} already exists!" if @@parsers.has_key?(name)
-        @@parsers[name] = Data.new(name, start_re, meth_name)
+        @@parsers[name] = Data.new(name, start_re, span_start, meth_name)
       end
 
       # Return the Data structure for the parser +name+.
@@ -265,6 +283,7 @@ module Kramdown
       require 'kramdown/parser/kramdown/autolink'
       require 'kramdown/parser/kramdown/codespan'
       require 'kramdown/parser/kramdown/emphasis'
+      require 'kramdown/parser/kramdown/smart_quotes'
 
     end