formatter.rb in slodown-0.3.0

- old
+ new

@@ -1,14 +1,18 @@
 module Slodown
   # This is the base Formatter class provided by Slodown. It works right
   # out of the box if you want to use exactly the functionality provided by
   # it, but in most projects, you'll probably want to create a new class
-  # inheriting from this one.
+  # inheriting from this one, selectively overriding methods like
+  # +kramdown_options+ or adding your own.
   #
   class Formatter
+    attr_reader :metadata
+
     def initialize(source)
       @current = @source = source.to_s
+      @metadata = {}
     end
 
     # Run the entire pipeline in a sane order.
     #
     def complete
@@ -37,10 +41,12 @@
       convert do |current|
         Sanitize.clean(current, sanitize_config)
       end
     end
 
+    # Extract metadata from the document.
+    #
     def extract_metadata
       @metadata = {}
 
       convert do |current|
         current.each_line.drop_while do |line|
@@ -50,37 +56,31 @@
           @metadata[key.to_sym] = value
         end.join('')
       end
     end
 
-    # Return a hash with the extracted metadata
-    #
-    def metadata
-      @metadata
-    end
-
     def to_s
       @current
     end
 
-  private
-
-    # Applies a conversion of the current text state.
+    # Return a hash of configuration values for kramdown. Please refer to
+    # the documentation of kramdown for details:
     #
-    def convert(&blk)
-      @current = blk.call(@current)
-      self
-    end
-
+    # http://kramdown.gettalong.org/options.html
+    #
     def kramdown_options
       {
-        syntax_highlighter: 'coderay',
-        syntax_highlighter_opts: {
-        }
+        syntax_highlighter: defined?(Rouge) ? 'rouge' : 'coderay',
+        syntax_highlighter_opts: { }
       }
     end
 
+    # Return a hash of configuration values for the sanitize gem. Please refer
+    # to the documentation for sanitize for details:
+    #
+    # https://github.com/rgrove/sanitize#custom-configuration
+    #
     def sanitize_config
       {
         elements: %w(
           p br a span sub sup strong em div hr abbr s
           ul ol li
@@ -110,20 +110,31 @@
         },
         transformers: transformers
       }
     end
 
+    # Return a regular expression that will be matched against an embedded IFRAME's
+    # source URL's host. If the expression matches, the IFRAME tag will be whitelisted
+    # in its entirety; otherwise, it will be sanitized.
+    #
+    # By default, all hosts are allowed. Override this method if this is not what
+    # you want.
+    #
     def allowed_iframe_hosts
-      # By default, allow everything. Override this to return a regular expression
-      # that will be matched against the iframe/embed's src URL's host.
       /.*/
     end
 
+    # A list of sanitize transformers to be applied to the markup that is to be
+    # sanitized. By default, we're only using +embed_transformer+.
+    #
     def transformers
       [embed_transformer]
     end
 
+    # A sanitize transformer that will check the document for IFRAME tags and
+    # validate them against +allowed_iframe_hosts+.
+    #
     def embed_transformer
       lambda do |env|
         node      = env[:node]
         node_name = env[:node_name]
 
@@ -143,8 +154,17 @@
           }
         })
 
         { node_whitelist: [node] }
       end
+    end
+
+  private
+
+    # Applies a conversion of the current text state.
+    #
+    def convert(&blk)
+      @current = blk.call(@current)
+      self
     end
   end
 end