haml-edge 2.1.21 → 2.1.22

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,6 +78,12 @@ 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
@@ -85,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]
@@ -155,6 +181,12 @@ 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]
@@ -162,15 +194,20 @@ END
       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
 
@@ -197,6 +234,8 @@ END
         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'
@@ -229,9 +268,9 @@ END
       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"
@@ -239,6 +278,9 @@ END
         @options[:load_paths] = []
       end
 
+      # Tells optparse how to parse the arguments.
+      #
+      # @param opts [OptionParser]
       def set_opts(opts)
         super
 
@@ -270,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]
@@ -309,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
 
@@ -326,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]
@@ -350,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
 
@@ -363,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
 
@@ -374,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]
@@ -390,6 +442,8 @@ END
         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,71 +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)
       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
@@ -89,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
@@ -139,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]}>
@@ -167,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 [`:suppress_eval`](../Haml.html#suppress-eval-option) 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
@@ -201,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 [`:suppress_eval`](../Haml.html#suppress-eval-option) 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/, '').
@@ -230,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
@@ -241,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'
@@ -261,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:

data/lib/haml/helpers/action_view_extensions.rb

@@ -1,45 +1,40 @@
 require 'haml/helpers/action_view_mods'
 
-if defined?(ActionView)
-  module Haml
-    module Helpers
-      # This module contains various useful helper methods
-      # that either tie into ActionView or the rest of the ActionPack stack,
-      # or are only useful in that context.
-      # Thus, the methods defined here are only available
-      # if ActionView is installed.
-      module ActionViewExtensions
-        # Returns a value for the "class" attribute
-        # unique to this controller/action pair.
-        # This can be used to target styles specifically at this action or controller.
-        # For example, if the current action were EntryController#show,
-        #
-        #   %div{:class => page_class} My Div
-        #
-        # would become
-        #
-        #   <div class="entry show">My Div</div>
-        #
-        # Then, in a stylesheet
-        # (shown here as Sass),
-        # you could refer to this specific action:
-        #
-        #   .entry.show
-        #     :font-weight bold
-        #
-        # or to all actions in the entry controller:
-        #
-        #   .entry
-        #     :color #00f
-        #
-        def page_class
-          controller.controller_name + " " + controller.action_name
-        end
-
-        # :stopdoc:
-        alias_method :generate_content_class_names, :page_class
-        # :startdoc:
+module Haml
+  module Helpers
+    # This module contains various useful helper methods
+    # that either tie into ActionView or the rest of the ActionPack stack,
+    # or are only useful in that context.
+    # Thus, the methods defined here are only available
+    # if ActionView is installed.
+    module ActionViewExtensions
+      # Returns a value for the "class" attribute
+      # unique to this controller/action pair.
+      # This can be used to target styles specifically at this action or controller.
+      # For example, if the current action were `EntryController#show`,
+      #
+      #     %div{:class => page_class} My Div
+      #
+      # would become
+      #
+      #     <div class="entry show">My Div</div>
+      #
+      # Then, in a stylesheet (shown here as {Sass}),
+      # you could refer to this specific action:
+      #
+      #     .entry.show
+      #       :font-weight bold
+      #
+      # or to all actions in the entry controller:
+      #
+      #     .entry
+      #       :color #00f
+      #
+      # @return [String] The class name for the current page
+      def page_class
+        controller.controller_name + " " + controller.action_name
       end
+      alias_method :generate_content_class_names, :page_class
     end
   end
 end