haml 2.0.10 → 2.2.0

data/lib/haml/error.rb

@@ -1,22 +1,22 @@
 module Haml
   # An exception raised by Haml code.
   class Error < StandardError
-    # :stopdoc:
-
-    # By default, an error is taken to refer to the line of the template
-    # that was being processed when the exception was raised.
-    # However, if line is non-nil, it + 1 is used instead.
+    # The line of the template on which the error occurred.
+    #
+    # @return [Fixnum]
     attr_reader :line
 
+    # @param message [String] The error message
+    # @param line [Fixnum] See \{#line}
     def initialize(message = nil, line = nil)
       super(message)
       @line = line
     end
-    # :startdoc:
   end
 
   # SyntaxError is the type of exception raised when Haml encounters an
   # ill-formatted document.
-  # It's not particularly interesting, except in that it includes Haml::Error.
+  # It's not particularly interesting,
+  # except in that it's a subclass of {Haml::Error}.
   class SyntaxError < Haml::Error; end
 end

data/lib/haml/exec.rb

@@ -2,19 +2,18 @@ require 'optparse'
 require 'fileutils'
 
 module Haml
-  # This module contains code for working with the
-  # haml, sass, and haml2html executables,
-  # such as command-line parsing stuff.
-  # It shouldn't need to be invoked by client code.
-  module Exec # :nodoc:
-    # A class that encapsulates the executable code
-    # for all three executables.
-    class Generic # :nodoc:
+  # This module handles the various Haml executables (`haml`, `sass`, `css2sass`, etc).
+  module Exec
+    # An abstract class that encapsulates the executable code for all three executables.
+    class Generic
+      # @param args [Array<String>] The command-line arguments
       def initialize(args)
         @args = args
         @options = {}
       end
 
+      # Parses the command-line arguments and runs the executable.
+      # Calls `Kernel#exit` at the end, so it never returns.
       def parse!
         begin
           @opts = OptionParser.new(&method(:set_opts))
@@ -32,12 +31,18 @@ module Haml
         exit 0
       end
 
+      # @return [String] A description of the executable
       def to_s
         @opts.to_s
       end
 
       protected
 
+      # Finds the line of the source template
+      # on which an exception was raised.
+      #
+      # @param exception [Exception] The exception
+      # @return [String] The line number
       def get_line(exception)
         # SyntaxErrors have weird line reporting
         # when there's trailing whitespace,
@@ -46,8 +51,13 @@ module Haml
         exception.backtrace[0].scan(/:(\d+)/).first.first
       end
 
-      private
-
+      # Tells optparse how to parse the arguments
+      # available for all executables.
+      #
+      # This is meant to be overridden by subclasses
+      # so they can add their own options.
+      #
+      # @param opts [OptionParser]
       def set_opts(opts)
         opts.on('-s', '--stdin', :NONE, 'Read input from standard input instead of an input file') do
           @options[:input] = $stdin
@@ -68,12 +78,19 @@ module Haml
         end
       end
 
+      # Processes the options set by the command-line arguments.
+      # In particular, sets `@options[:input]` and `@options[:output]`
+      # to appropriate IO streams.
+      #
+      # This is meant to be overridden by subclasses
+      # so they can run their respective programs.
       def process_result
         input, output = @options[:input], @options[:output]
         input_file, output_file = if input
-                                    [nil, open_file(ARGV[0], 'w')]
+                                    [nil, open_file(@args[0], 'w')]
                                   else
-                                    [open_file(ARGV[0]), open_file(ARGV[1], 'w')]
+                                    @options[:filename] = @args[0]
+                                    [open_file(@args[0]), open_file(@args[1], 'w')]
                                   end
 
         input  ||= input_file
@@ -84,22 +101,32 @@ module Haml
         @options[:input], @options[:output] = input, output
       end
 
+      private
+
       def open_file(filename, flag = 'r')
         return if filename.nil?
         File.open(filename, flag)
       end
     end
 
-    # A class encapsulating the executable functionality
-    # specific to Haml and Sass.
-    class HamlSass < Generic # :nodoc:
+    # An abstrac class that encapsulates the code
+    # specific to the `haml` and `sass` executables.
+    class HamlSass < Generic
+      # @param args [Array<String>] The command-line arguments
       def initialize(args)
         super
         @options[:for_engine] = {}
       end
 
-      private
+      protected
 
+      # Tells optparse how to parse the arguments
+      # available for the `haml` and `sass` executables.
+      #
+      # This is meant to be overridden by subclasses
+      # so they can add their own options.
+      #
+      # @param opts [OptionParser]
       def set_opts(opts)
         opts.banner = <<END
 Usage: #{@name.downcase} [options] [INPUT] [OUTPUT]
@@ -154,20 +181,33 @@ END
         super
       end
 
+      # Processes the options set by the command-line arguments.
+      # In particular, sets `@options[:for_engine][:filename]` to the input filename
+      # and requires the appropriate file.
+      #
+      # This is meant to be overridden by subclasses
+      # so they can run their respective programs.
       def process_result
         super
+        @options[:for_engine][:filename] = @options[:filename] if @options[:filename]
         require File.dirname(__FILE__) + "/../#{@name.downcase}"
       end
     end
 
-    # A class encapsulating executable functionality
-    # specific to Sass.
-    class Sass < HamlSass # :nodoc:
+    # The `sass` executable.
+    class Sass < HamlSass
+      # @param args [Array<String>] The command-line arguments
       def initialize(args)
         super
         @name = "Sass"
+        @options[:for_engine][:load_paths] = ['.'] + (ENV['SASSPATH'] || '').split(File::PATH_SEPARATOR)
       end
 
+      protected
+
+      # Tells optparse how to parse the arguments.
+      #
+      # @param opts [OptionParser]
       def set_opts(opts)
         super
 
@@ -175,34 +215,62 @@ END
                 'Output style. Can be nested (default), compact, compressed, or expanded.') do |name|
           @options[:for_engine][:style] = name.to_sym
         end
+        opts.on('-l', '--line-comments',
+                'Line Comments. Emit comments in the generated CSS indicating the corresponding sass line.') do
+          @options[:for_engine][:line_comments] = true
+        end
+        opts.on('-i', '--interactive',
+                'Run an interactive SassScript shell.') do
+          @options[:interactive] = true
+        end
+        opts.on('-I', '--load-path PATH', 'Add a sass import path.') do |path|
+          @options[:for_engine][:load_paths] << path
+        end
+        opts.on('--cache-location', 'The path to put cached Sass files. Defaults to .sass-cache.') do |loc|
+          @options[:for_engine][:cache_location] = path
+        end
+        opts.on('-C', '--no-cache', "Don't cache to sassc files.") do
+          @options[:for_engine][:cache] = false
+        end
       end
 
+      # Processes the options set by the command-line arguments,
+      # and runs the Sass compiler appropriately.
       def process_result
+        if @options[:interactive]
+          require 'sass'
+          require 'sass/repl'
+          ::Sass::Repl.new(@options).run
+          return
+        end
+
         super
         input = @options[:input]
         output = @options[:output]
 
-        template = input.read()
-        input.close() if input.is_a? File
+        tree =
+          if input.is_a?(File) && !@options[:check_syntax]
+            ::Sass::Files.tree_for(input.path, @options[:for_engine])
+          else
+            # We don't need to do any special handling of @options[:check_syntax] here,
+            # because the Sass syntax checking happens alongside evaluation
+            # and evaluation doesn't actually evaluate any code anyway.
+            ::Sass::Engine.new(input.read(), @options[:for_engine]).to_tree
+          end
 
-        begin
-          # We don't need to do any special handling of @options[:check_syntax] here,
-          # because the Sass syntax checking happens alongside evaluation
-          # and evaluation doesn't actually evaluate any code anyway.
-          result = ::Sass::Engine.new(template, @options[:for_engine]).render
-        rescue ::Sass::SyntaxError => e
-          raise e if @options[:trace]
-          raise "Syntax error on line #{get_line e}: #{e.message}"
-        end
+        input.close() if input.is_a?(File)
 
-        output.write(result)
+        output.write(tree.render)
         output.close() if output.is_a? File
+      rescue ::Sass::SyntaxError => e
+        raise e if @options[:trace]
+        raise "Syntax error on line #{get_line e}: #{e.message}"
       end
     end
 
-    # A class encapsulating executable functionality
-    # specific to Haml.
-    class Haml < HamlSass # :nodoc:
+    # The `haml` executable.
+    class Haml < HamlSass
+      # @param args [Array<String>] The command-line arguments
       def initialize(args)
         super
         @name = "Haml"
@@ -210,6 +278,9 @@ END
         @options[:load_paths] = []
       end
 
+      # Tells optparse how to parse the arguments.
+      #
+      # @param opts [OptionParser]
       def set_opts(opts)
         super
 
@@ -241,6 +312,8 @@ END
         end
       end
 
+      # Processes the options set by the command-line arguments,
+      # and runs the Haml compiler appropriately.
       def process_result
         super
         input = @options[:input]
@@ -280,9 +353,9 @@ END
       end
     end
 
-    # A class encapsulating executable functionality
-    # specific to the html2haml executable.
-    class HTML2Haml < Generic # :nodoc:
+    # The `html2haml` executable.
+    class HTML2Haml < Generic
+      # @param args [Array<String>] The command-line arguments
       def initialize(args)
         super
 
@@ -297,6 +370,9 @@ END
         end
       end
 
+      # Tells optparse how to parse the arguments.
+      #
+      # @param opts [OptionParser]
       def set_opts(opts)
         opts.banner = <<END
 Usage: html2haml [options] [INPUT] [OUTPUT]
@@ -321,6 +397,8 @@ END
         super
       end
 
+      # Processes the options set by the command-line arguments,
+      # and runs the HTML compiler appropriately.
       def process_result
         super
 
@@ -334,9 +412,9 @@ END
       end
     end
 
-    # A class encapsulating executable functionality
-    # specific to the css2sass executable.
-    class CSS2Sass < Generic # :nodoc:
+    # The `css2sass` executable.
+    class CSS2Sass < Generic
+      # @param args [Array<String>] The command-line arguments
       def initialize(args)
         super
 
@@ -345,6 +423,9 @@ END
         require 'sass/css'
       end
 
+      # Tells optparse how to parse the arguments.
+      #
+      # @param opts [OptionParser]
       def set_opts(opts)
         opts.banner = <<END
 Usage: css2sass [options] [INPUT] [OUTPUT]
@@ -354,13 +435,17 @@ Description: Transforms a CSS file into corresponding Sass code.
 Options:
 END
 
-        opts.on('-a', '--alternate', 'Output using alternative Sass syntax (margin: 1px)') do
-          @module_opts[:alternate] = true
+        opts.on('--old', 'Output the old-style ":prop val" property syntax') do
+          @module_opts[:old] = true
         end
 
+        opts.on_tail('-a', '--alternate', 'Ignored') {}
+
         super
       end
 
+      # Processes the options set by the command-line arguments,
+      # and runs the CSS compiler appropriately.
       def process_result
         super
 

data/lib/haml/filters.rb

@@ -1,72 +1,98 @@
 module Haml
-  # The module containing the default filters,
-  # as well as the base module,
-  # Haml::Filters::Base.
+  # The module containing the default Haml filters,
+  # as well as the base module, {Haml::Filters::Base}.
+  #
+  # @see Haml::Filters::Base
   module Filters
-    # Returns a hash of defined filters.
+    # @return [Hash<String, Haml::Filters::Base>] a hash of filter names to classes
     def self.defined
       @defined ||= {}
     end
 
     # The base module for Haml filters.
     # User-defined filters should be modules including this module.
+    # The name of the filter is taken by downcasing the module name.
+    # For instance, if the module is named `FooBar`, the filter will be `:foobar`.
     #
-    # A user-defined filter should override either Base#render or Base #compile.
-    # Base#render is the most common.
+    # A user-defined filter should override either \{#render} or {\#compile}.
+    # \{#render} is the most common.
     # It takes a string, the filter source,
-    # and returns another string,
-    # the result of the filter.
-    # For example:
+    # and returns another string, the result of the filter.
+    # For example, the following will define a filter named `:sass`:
     #
-    #   module Haml::Filters::Sass
-    #     include Haml::Filters::Base
+    #     module Haml::Filters::Sass
+    #       include Haml::Filters::Base
     #
-    #     def render(text)
-    #       ::Sass::Engine.new(text).render
+    #       def render(text)
+    #         ::Sass::Engine.new(text).render
+    #       end
     #     end
-    #   end
     #
-    # For details on overriding #compile, see its documentation.
+    # For details on overriding \{#compile}, see its documentation.
     #
+    # Note that filters overriding \{#render} automatically support `#{}`
+    # for interpolating Ruby code.
+    # Those overriding \{#compile} will need to add such support manually
+    # if it's desired.
     module Base
-      def self.included(base) # :nodoc:
+      # This method is automatically called when {Base} is included in a module.
+      # It automatically defines a filter
+      # with the downcased name of that module.
+      # For example, if the module is named `FooBar`, the filter will be `:foobar`.
+      #
+      # @param base [Module, Class] The module that this is included in
+      def self.included(base)
         Filters.defined[base.name.split("::").last.downcase] = base
         base.extend(base)
-        base.instance_variable_set "@lazy_requires", nil
       end
 
-      # Takes a string, the source text that should be passed to the filter,
-      # and returns the string resulting from running the filter on <tt>text</tt>.
+      # Takes the source text that should be passed to the filter
+      # and returns the result of running the filter on that string.
       #
       # This should be overridden in most individual filter modules
       # to render text with the given filter.
-      # If compile is overridden, however, render doesn't need to be.
+      # If \{#compile} is overridden, however, \{#render} doesn't need to be.
+      #
+      # @param text [String] The source text for the filter to process
+      # @return [String] The filtered result
+      # @raise [Haml::Error] if it's not overridden
       def render(text)
         raise Error.new("#{self.inspect}#render not defined!")
       end
 
-      # Same as render, but takes the Haml options hash as well.
-      # It's only safe to rely on options made available in Haml::Engine#options_for_buffer.
+      # Same as \{#render}, but takes a {Haml::Engine} options hash as well.
+      # It's only safe to rely on options made available in {Haml::Engine#options\_for\_buffer}.
+      #
+      # @see #render
+      # @param text [String] The source text for the filter to process
+      # @return [String] The filtered result
+      # @raise [Haml::Error] if it or \{#render} isn't overridden
       def render_with_options(text, options)
         render(text)
       end
 
-      def internal_compile(*args) # :nodoc:
+      # Same as \{#compile}, but requires the necessary files first.
+      # *This is used by {Haml::Engine} and is not intended to be overridden or used elsewhere.*
+      #
+      # @see #compile
+      def internal_compile(*args)
         resolve_lazy_requires
         compile(*args)
       end
 
-      # compile should be overridden when a filter needs to have access
-      # to the Haml evaluation context.
+      # This should be overridden when a filter needs to have access to the Haml evaluation context.
       # Rather than applying a filter to a string at compile-time,
-      # compile uses the Haml::Precompiler instance to compile the string to Ruby code
+      # \{#compile} uses the {Haml::Precompiler} instance to compile the string to Ruby code
       # that will be executed in the context of the active Haml template.
       #
-      # Warning: the Haml::Precompiler interface is neither well-documented
+      # Warning: the {Haml::Precompiler} interface is neither well-documented
       # nor guaranteed to be stable.
-      # If you want to make use of it,
-      # you'll probably need to look at the source code
+      # If you want to make use of it, you'll probably need to look at the source code
       # and should test your filter when upgrading to new Haml versions.
+      #
+      # @param precompiler [Haml::Precompiler] The precompiler instance
+      # @param text [String] The text of the filter
+      # @raise [Haml::Error] if none of \{#compile}, \{#render}, and \{#render_with_options} are overridden
       def compile(precompiler, text)
         resolve_lazy_requires
         filter = self
@@ -74,7 +100,7 @@ module Haml
           if contains_interpolation?(text)
             return if options[:suppress_eval]
 
-            push_script(<<RUBY, false)
+            push_script <<RUBY
 find_and_preserve(#{filter.inspect}.render_with_options(#{unescape_interpolation(text)}, _hamlout.options))
 RUBY
             return
@@ -90,22 +116,22 @@ RUBY
         end
       end
 
-      # This becomes a class method of modules that include Base.
+      # This becomes a class method of modules that include {Base}.
       # It allows the module to specify one or more Ruby files
       # that Haml should try to require when compiling the filter.
       #
-      # The first file specified is tried first,
-      # then the second, etc.
+      # The first file specified is tried first, then the second, etc.
       # If none are found, the compilation throws an exception.
       #
       # For example:
       #
-      #   module Haml::Filters::Markdown
-      #     lazy_require 'rdiscount', 'peg_markdown', 'maruku', 'bluecloth'
+      #     module Haml::Filters::Markdown
+      #       lazy_require 'rdiscount', 'peg_markdown', 'maruku', 'bluecloth'
       #
-      #     ...
-      #   end
+      #       ...
+      #     end
       #
+      # @param reqs [Array<String>] The requires to run
       def lazy_require(*reqs)
         @lazy_requires = reqs
       end
@@ -140,23 +166,29 @@ RUBY
   end
 end
 
-# :stopdoc:
-
 begin
   require 'rubygems'
 rescue LoadError; end
 
 module Haml
   module Filters
+    # Does not parse the filtered text.
+    # This is useful for large blocks of text without HTML tags,
+    # when you don't want lines starting with `.` or `-`
+    # to be parsed.
     module Plain
       include Base
 
+      # @see Base#render
       def render(text); text; end
     end
 
+    # Surrounds the filtered text with `<script>` and CDATA tags.
+    # Useful for including inline Javascript.
     module Javascript
       include Base
 
+      # @see Base#render_with_options
       def render_with_options(text, options)
         <<END
 <script type=#{options[:attr_wrapper]}text/javascript#{options[:attr_wrapper]}>
@@ -168,26 +200,37 @@ END
       end
     end
 
+    # Surrounds the filtered text with CDATA tags.
     module Cdata
       include Base
 
+      # @see Base#render
       def render(text)
         "<![CDATA[#{("\n" + text).rstrip.gsub("\n", "\n    ")}\n]]>"
       end
     end
 
+    # Works the same as {Plain}, but HTML-escapes the text
+    # before placing it in the document.
     module Escaped
       include Base
 
+      # @see Base#render
       def render(text)
         Haml::Helpers.html_escape text
       end
     end
 
+    # Parses the filtered text with the normal Ruby interpreter.
+    # All output sent to `$stdout`, such as with `puts`,
+    # is output into the Haml document.
+    # Not available if the {file:HAML_REFERENCE.md#suppress_eval-option `:suppress_eval`} option is set to true.
+    # The Ruby code is evaluated in the same context as the Haml template.
     module Ruby
       include Base
       lazy_require 'stringio'
 
+      # @see Base#compile
       def compile(precompiler, text)
         return if precompiler.options[:suppress_eval]
         precompiler.instance_eval do
@@ -202,27 +245,40 @@ END
       end
     end
 
+    # Inserts the filtered text into the template with whitespace preserved.
+    # `preserve`d blocks of text aren't indented,
+    # and newlines are replaced with the HTML escape code for newlines,
+    # to preserve nice-looking output.
+    #
+    # @see Haml::Helpers#preserve
     module Preserve
       include Base
 
+      # @see Base#render
       def render(text)
         Haml::Helpers.preserve text
       end
     end
 
+    # Parses the filtered text with {Sass} to produce CSS output.
     module Sass
       include Base
       lazy_require 'sass/plugin'
 
+      # @see Base#render
       def render(text)
         ::Sass::Engine.new(text, ::Sass::Plugin.engine_options).render
       end
     end
 
+    # Parses the filtered text with ERB, like an RHTML template.
+    # Not available if the {file:HAML_REFERENCE.md#suppress_eval-option `:suppress_eval`} option is set to true.
+    # Embedded Ruby code is evaluated in the same context as the Haml template.
     module ERB
       include Base
       lazy_require 'erb'
 
+      # @see Base#compile
       def compile(precompiler, text)
         return if precompiler.options[:suppress_eval]
         src = ::ERB.new(text).src.sub(/^#coding:.*?\n/, '').
@@ -231,10 +287,13 @@ END
       end
     end
 
+    # Parses the filtered text with [Textile](http://www.textism.com/tools/textile).
+    # Only works if [RedCloth](http://redcloth.org) is installed.
     module Textile
       include Base
       lazy_require 'redcloth'
 
+      # @see Base#render
       def render(text)
         ::RedCloth.new(text).to_html(:textile)
       end
@@ -242,11 +301,16 @@ END
     RedCloth = Textile
     Filters.defined['redcloth'] = RedCloth
 
-    # Uses BlueCloth or RedCloth to provide only Markdown (not Textile) parsing
+    # Parses the filtered text with [Markdown](http://daringfireball.net/projects/markdown).
+    # Only works if [RDiscount](http://github.com/rtomayko/rdiscount),
+    # [RPeg-Markdown](http://github.com/rtomayko/rpeg-markdown),
+    # [Maruku](http://maruku.rubyforge.org),
+    # or [BlueCloth](www.deveiate.org/projects/BlueCloth) are installed.
     module Markdown
       include Base
       lazy_require 'rdiscount', 'peg_markdown', 'maruku', 'bluecloth'
 
+      # @see Base#render
       def render(text)
         engine = case @required
                  when 'rdiscount'
@@ -262,15 +326,16 @@ END
       end
     end
 
+    # Parses the filtered text with [Maruku](http://maruku.rubyforge.org),
+    # which has some non-standard extensions to Markdown.
     module Maruku
       include Base
       lazy_require 'maruku'
 
+      # @see Base#render
       def render(text)
         ::Maruku.new(text).to_html
       end
     end
   end
 end
-
-# :startdoc: