haml-edge 2.1.21 → 2.1.22

data/lib/sass/css.rb

@@ -3,14 +3,18 @@ require 'sass/tree/node'
 require 'strscan'
 
 module Sass
-  # :stopdoc:
   module Tree
     class Node
-      def to_sass(opts = {})
+      # Converts a node to Sass code that will generate it.
+      #
+      # @param tabs [Fixnum] The amount of tabulation to use for the Sass code
+      # @param opts [Hash<Symbol, Object>] An options hash (see {Sass::CSS#initialize})
+      # @return [String] The Sass code corresponding to the node
+      def to_sass(tabs = 0, opts = {})
         result = ''
 
         children.each do |child|
-          result << "#{child.to_sass(0, opts)}\n"
+          result << "#{'  ' * tabs}#{child.to_sass(0, opts)}\n"
         end
 
         result
@@ -18,6 +22,7 @@ module Sass
     end
 
     class RuleNode
+      # @see Node#to_sass
       def to_sass(tabs, opts = {})
         str = "\n#{'  ' * tabs}#{rules.first}#{children.any? { |c| c.is_a? AttrNode } ? "\n" : ''}"
 
@@ -30,26 +35,33 @@ module Sass
     end
 
     class AttrNode
+      # @see Node#to_sass
       def to_sass(tabs, opts = {})
         "#{'  ' * tabs}#{opts[:alternate] ? '' : ':'}#{name}#{opts[:alternate] ? ':' : ''} #{value}\n"
       end
     end
 
     class DirectiveNode
+      # @see Node#to_sass
       def to_sass(tabs, opts = {})
         "#{'  ' * tabs}#{value}#{children.map {|c| c.to_sass(tabs + 1, opts)}}\n"
       end
     end
   end
 
-  # :startdoc:
-
-  # This class contains the functionality used in the +css2sass+ utility,
-  # namely converting CSS documents to Sass templates.
+  # This class converts CSS documents into Sass templates.
+  # It works by parsing the CSS document into a {Sass::Tree} structure,
+  # and then applying various transformations to the structure
+  # to produce more concise and idiomatic Sass.
+  #
+  # Example usage:
+  #
+  #     Sass::CSS.new("p { color: blue }").render #=> "p\n  :color blue"
   class CSS
-
-    # Creates a new instance of Sass::CSS that will compile the given document
-    # to a Sass string when +render+ is called.
+    # @param template [String] The CSS code
+    # @option options :alternate [Boolean] (false)
+    #     Whether or not to output alternate attribute syntax
+    #     (`color: blue` as opposed to `:color blue`).
     def initialize(template, options = {})
       if template.is_a? IO
         template = template.read
@@ -59,11 +71,12 @@ module Sass
       @template = StringScanner.new(template)
     end
 
-    # Processes the document and returns the result as a string
-    # containing the CSS template.
+    # Converts the CSS template into Sass code.
+    #
+    # @return [String] The resulting Sass code
     def render
       begin
-        build_tree.to_sass(@options).strip + "\n"
+        build_tree.to_sass(0, @options).strip + "\n"
       rescue Exception => err
         line = @template.string[0...@template.pos].split("\n").size
 
@@ -74,6 +87,9 @@ module Sass
 
     private
 
+    # Parses the CSS template and applies various transformations
+    #
+    # @return [Tree::Node] The root node of the parsed tree
     def build_tree
       root = Tree::Node.new
       whitespace
@@ -86,6 +102,9 @@ module Sass
       root
     end
 
+    # Parses a set of CSS rules.
+    #
+    # @param root [Tree::Node] The parent node of the rules
     def rules(root)
       while r = rule
         root << r
@@ -93,6 +112,9 @@ module Sass
       end
     end
 
+    # Parses a single CSS rule.
+    #
+    # @return [Tree::Node] The parsed rule
     def rule
       return unless rule = @template.scan(/[^\{\};]+/)
       rule.strip!
@@ -115,6 +137,9 @@ module Sass
       return node
     end
 
+    # Parses a set of CSS attributes within a rule.
+    #
+    # @param rule [Tree::RuleNode] The parent node of the attributes
     def attributes(rule)
       while @template.scan(/[^:\}\s]+/)
         name = @template[0]
@@ -134,6 +159,9 @@ module Sass
       assert_match /\}/
     end
 
+    # Moves the scanner over a section of whitespace or comments.
+    #
+    # @return [String] The ignored whitespace
     def whitespace
       space = @template.scan(/\s*/) || ''
 
@@ -146,6 +174,10 @@ module Sass
       return space
     end
 
+    # Moves the scanner over a regular expression,
+    # raising an exception if it doesn't match.
+    #
+    # @param re [Regexp] The regular expression to assert
     def assert_match(re)
       if !@template.scan(re)
         line = @template.string[0..@template.pos].count "\n"
@@ -158,20 +190,19 @@ module Sass
 
     # Transform
     #
-    #   foo, bar, baz
-    #     color: blue
+    #     foo, bar, baz
+    #       color: blue
     #
     # into
     #
-    #   foo
-    #     color: blue
-    #   bar
-    #     color: blue
-    #   baz
-    #     color: blue
+    #     foo
+    #       color: blue
+    #     bar
+    #       color: blue
+    #     baz
+    #       color: blue
     #
-    # Yes, this expands the amount of code,
-    # but it's necessary to get nesting to work properly.
+    # @param root [Tree::Node] The parent node
     def expand_commas(root)
       root.children.map! do |child|
         next child unless Tree::RuleNode === child && child.rules.first.include?(',')
@@ -186,37 +217,38 @@ module Sass
 
     # Make rules use parent refs so that
     #
-    #   foo
-    #     color: green
-    #   foo.bar
-    #     color: blue
+    #     foo
+    #       color: green
+    #     foo.bar
+    #       color: blue
     #
     # becomes
     #
-    #   foo
-    #     color: green
-    #     &.bar
-    #       color: blue
+    #     foo
+    #       color: green
+    #       &.bar
+    #         color: blue
     #
     # This has the side effect of nesting rules,
     # so that
     #
-    #   foo
-    #     color: green
-    #   foo bar
-    #     color: red
-    #   foo baz
-    #     color: blue
+    #     foo
+    #       color: green
+    #     foo bar
+    #       color: red
+    #     foo baz
+    #       color: blue
     #
     # becomes
     #
-    #   foo
-    #     color: green
-    #     & bar
-    #       color: red
-    #     & baz
-    #       color: blue
+    #     foo
+    #       color: green
+    #       & bar
+    #         color: red
+    #       & baz
+    #         color: blue
     #
+    # @param root [Tree::Node] The parent node
     def parent_ref_rules(root)
       current_rule = nil
       root.children.select { |c| Tree::RuleNode === c }.each do |child|
@@ -241,16 +273,17 @@ module Sass
 
     # Remove useless parent refs so that
     #
-    #   foo
-    #     & bar
-    #       color: blue
+    #     foo
+    #       & bar
+    #         color: blue
     #
     # becomes
     #
-    #   foo
-    #     bar
-    #       color: blue
+    #     foo
+    #       bar
+    #         color: blue
     #
+    # @param root [Tree::Node] The parent node
     def remove_parent_refs(root)
       root.children.each do |child|
         if child.is_a?(Tree::RuleNode)
@@ -262,31 +295,35 @@ module Sass
 
     # Flatten rules so that
     #
-    #   foo
-    #     bar
-    #       baz
-    #         color: red
+    #     foo
+    #       bar
+    #         :color red
     #
     # becomes
     #
-    #   foo bar baz
-    #     color: red
+    #     foo bar
+    #       :color red
     #
     # and
     #
-    #   foo
-    #     &.bar
-    #       color: blue
+    #     foo
+    #       &.bar
+    #         color: blue
     #
     # becomes
     #
-    #   foo.bar
-    #     color: blue
+    #     foo.bar
+    #       color: blue
     #
+    # @param root [Tree::Node] The parent node
     def flatten_rules(root)
       root.children.each { |child| flatten_rule(child) if child.is_a?(Tree::RuleNode) }
     end
 
+    # Flattens a single rule
+    #
+    # @param rule [Tree::RuleNode] The candidate for flattening
+    # @see #flatten_rules
     def flatten_rule(rule)
       while rule.children.size == 1 && rule.children.first.is_a?(Tree::RuleNode)
         child = rule.children.first
@@ -305,18 +342,19 @@ module Sass
 
     # Transform
     #
-    #   foo
-    #     bar
-    #       color: blue
-    #     baz
-    #       color: blue
+    #     foo
+    #       bar
+    #         color: blue
+    #       baz
+    #         color: blue
     #
     # into
     #
-    #   foo
-    #     bar, baz
-    #       color: blue
+    #     foo
+    #       bar, baz
+    #         color: blue
     #
+    # @param rule [Tree::RuleNode] The candidate for flattening
     def fold_commas(root)
       prev_rule = nil
       root.children.map! do |child|

data/lib/sass/engine.rb

@@ -20,20 +20,55 @@ require 'sass/files'
 require 'haml/shared'
 
 module Sass
-  # :stopdoc:
+  # A Sass mixin.
+  #
+  # `name`: [{String}]
+  # : The name of the mixin.
+  #
+  # `args`: [{Array}<({String}, {Script::Node})>]
+  # : The arguments for the mixin.
+  #   Each element is a tuple containing the name of the argument
+  #   and the parse tree for the default value of the argument.
+  #
+  # `environment`: [{Sass::Environment}]
+  # : The environment in which the mixin was defined.
+  #   This is captured so that the mixin can have access
+  #   to local variables defined in its scope.
+  #
+  # `tree`: [{Sass::Tree::Node}]
+  # : The parse tree for the mixin.
   Mixin = Struct.new(:name, :args, :environment, :tree)
-  # :startdoc:
 
-  # This is the class where all the parsing and processing of the Sass
-  # template is done. It can be directly used by the user by creating a
-  # new instance and calling <tt>render</tt> to render the template. For example:
+  # This class handles the parsing and compilation of the Sass template.
+  # Example usage:
   #
-  #   template = File.load('stylesheets/sassy.sass')
-  #   sass_engine = Sass::Engine.new(template)
-  #   output = sass_engine.render
-  #   puts output
+  #     template = File.load('stylesheets/sassy.sass')
+  #     sass_engine = Sass::Engine.new(template)
+  #     output = sass_engine.render
+  #     puts output
   class Engine
     include Haml::Util
+
+    # A line of Sass code.
+    #
+    # `text`: [{String}]
+    # : The text in the line, without any whitespace at the beginning or end.
+    #
+    # `tabs`: [{Fixnum}]
+    # : The level of indentation of the line.
+    #
+    # `index`: [{Fixnum}]
+    # : The line number in the original document.
+    #
+    # `offset`: [{Fixnum}]
+    # : The number of bytes in on the line that the text begins.
+    #   This ends up being the number of bytes of leading whitespace.
+    #
+    # `filename`: [{String}]
+    # : The name of the file in which this line appeared.
+    #
+    # `children`: [{Array}<{Line}>]
+    # : The lines nested below this one.
     Line = Struct.new(:text, :tabs, :index, :offset, :filename, :children)
 
     # The character that begins a CSS attribute.
@@ -86,30 +121,28 @@ module Sass
       :cache_location => './.sass-cache',
     }.freeze
 
-    # Creates a new instace of Sass::Engine that will compile the given
-    # template string when <tt>render</tt> is called.
-    # See README.rdoc for available options.
-    #
-    #--
-    #
-    # TODO: Add current options to REFRENCE. Remember :filename!
-    #
-    # When adding options, remember to add information about them
-    # to README.rdoc!
-    #++
-    #
+    # @param template [String] The Sass template.
+    # @param options [Hash<Symbol, Object>] An options hash;
+    #   see [the Sass options documentation](../Sass.html#sass_options)
     def initialize(template, options={})
       @options = DEFAULT_OPTIONS.merge(options)
       @template = template
     end
 
-    # Processes the template and returns the result as a string.
+    # Render the template to CSS.
+    #
+    # @return [String] The CSS
+    # @raise [Sass::SyntaxError] if there's an error in the document
     def render
       to_tree.render
     end
 
     alias_method :to_css, :render
 
+    # Parses the document into its parse tree.
+    #
+    # @return [Sass::Tree::Node] The root of the parse tree.
+    # @raise [Sass::SyntaxError] if there's an error in the document
     def to_tree
       root = Tree::Node.new
       append_children(root, tree(tabulate(@template)).first, true)

data/lib/sass/environment.rb

@@ -1,8 +1,24 @@
 module Sass
+  # The lexical environment for SassScript.
+  # This keeps track of variable and mixin definitions.
+  #
+  # A new environment is created for each level of Sass nesting.
+  # This allows variables to be lexically scoped.
+  # The new environment refers to the environment in the upper scope,
+  # so it has access to variables defined in enclosing scopes,
+  # but new variables are defined locally.
+  #
+  # Environment also keeps track of the {Engine} options
+  # so that they can be made available to {Sass::Script::Functions}.
   class Environment
+    # The enclosing environment,
+    # or nil if this is the global environment.
+    #
+    # @return [Environment]
     attr_reader :parent
     attr_writer :options
 
+    # @param parent [Environment] See \{#parent}
     def initialize(parent = nil)
       @vars = {}
       @mixins = {}
@@ -11,38 +27,53 @@ module Sass
       set_var("important", Script::String.new("!important")) unless @parent
     end
 
+    # The options hash.
+    # See [the Sass options documentation](../Sass.html#sass_options).
+    #
+    # @return [Hash<Symbol, Object>]
     def options
       @options || (parent && parent.options) || {}
     end
 
-    def self.inherited_hash(name)
-      class_eval <<RUBY, __FILE__, __LINE__ + 1
-        def #{name}(name)
-          @#{name}s[name] || @parent && @parent.#{name}(name)
-        end
+    class << self
+      private
 
-        def set_#{name}(name, value)
-          @#{name}s[name] = value unless try_set_#{name}(name, value)
-        end
+      # Note: when updating this,
+      # update haml/yard/inherited_hash.rb as well.
+      def inherited_hash(name)
+        class_eval <<RUBY, __FILE__, __LINE__ + 1
+          def #{name}(name)
+            @#{name}s[name] || @parent && @parent.#{name}(name)
+          end
 
-        def try_set_#{name}(name, value)
-          if @#{name}s.include?(name)
-            @#{name}s[name] = value
-            true
-          elsif @parent
-            @parent.try_set_#{name}(name, value)
-          else
-            false
+          def set_#{name}(name, value)
+            @#{name}s[name] = value unless try_set_#{name}(name, value)
+          end
+
+          def try_set_#{name}(name, value)
+            if @#{name}s.include?(name)
+              @#{name}s[name] = value
+              true
+            elsif @parent
+              @parent.try_set_#{name}(name, value)
+            else
+              false
+            end
           end
-        end
-        protected :try_set_#{name}
+          protected :try_set_#{name}
 
-        def set_local_#{name}(name, value)
-          @#{name}s[name] = value
-        end
+          def set_local_#{name}(name, value)
+            @#{name}s[name] = value
+          end
 RUBY
+      end
     end
+
+    # variable
+    # Script::Literal
     inherited_hash :var
+    # mixin
+    # Engine::Mixin
     inherited_hash :mixin
   end
 end

data/lib/sass/error.rb

@@ -1,25 +1,34 @@
 module Sass
-  # Sass::SyntaxError encapsulates information about the exception,
-  # such as the line of the Sass template it was raised on
+  # An exception class that keeps track of
+  # the line of the Sass template it was raised on
   # and the Sass file that was being parsed (if applicable).
-  # It also provides a handy way to rescue only exceptions raised
-  # because of a faulty template.
+  #
+  # All Sass errors are raised as {Sass::SyntaxError}s.
   class SyntaxError < StandardError
-    # The line of the Sass template on which the exception was thrown.
+    # The line of the Sass template on which the error occurred.
+    #
+    # @return [Fixnum]
     attr_accessor :sass_line
 
     # The name of the file that was being parsed when the exception was raised.
-    # This will be nil unless Sass is being used as an ActionView plugin.
+    # This could be `nil` if no filename is available.
+    #
+    # @return [String]
     attr_reader :sass_filename
 
-    # Creates a new SyntaxError.
-    # +lineno+ should be the line of the Sass template on which the error occurred.
+    # @param msg [String] The error message
+    # @param lineno [Fixnum] See \{#sass\_line}
     def initialize(msg, lineno = nil)
       @message = msg
       @sass_line = lineno
     end
 
-    # Add information about the filename and line on which the error was raised.
+    # Add information about the filename and line on which the error was raised,
+    # and re-raises the exception.
+    #
+    # @param filename [String] See \{#sass\_filename}
+    # @param line [Fixnum] See \{#sass\_line}
+    # @raise [Sass::SyntaxError] self
     def add_metadata(filename, line)
       self.sass_line ||= line
       add_backtrace_entry(filename) unless sass_filename
@@ -27,15 +36,17 @@ module Sass
     end
 
     # Adds a properly formatted entry to the exception's backtrace.
-    # +filename+ should be the file in which the error occurred,
-    # if applicable (defaults to "(sass)").
+    #
+    # @param filename [String] The file in which the error occurred,
+    #   if applicable (defaults to "(sass)")
     def add_backtrace_entry(filename) # :nodoc:
       @sass_filename ||= filename
       self.backtrace ||= []
       self.backtrace.unshift "#{@sass_filename || '(sass)'}:#{@sass_line}"
     end
 
-    def to_s # :nodoc:
+    # @return [String] The error message
+    def to_s
       @message
     end
   end

data/lib/sass/files.rb

@@ -7,6 +7,13 @@ module Sass
   module Files
     extend self
 
+    # Returns the {Sass::Tree} for the given file,
+    # reading it from the Sass cache if possible.
+    #
+    # @param filename [String] The path to the Sass file
+    # @param options [Hash<Symbol, Object>] The options hash.
+    #   Only the [`:cache_location`](../Sass.html#cache-option) option is used
+    # @raise [Sass::SyntaxError] if there's an error in the document
     def tree_for(filename, options)
       options = Sass::Engine::DEFAULT_OPTIONS.merge(options)
       text = File.read(filename)
@@ -35,6 +42,26 @@ module Sass
       root
     end
 
+    # Find the full filename of a Sass or CSS file to import.
+    # This follows Sass's import rules:
+    # if the filename given ends in `".sass"` or `".css"`,
+    # it will try to find that type of file;
+    # otherwise, it will try to find the corresponding Sass file
+    # and fall back on CSS if it's not available.
+    #
+    # Any Sass filename returned will correspond to
+    # an actual Sass file on the filesystem.
+    # CSS filenames, however, may not;
+    # they're expected to be put through directly to the stylesheet
+    # as CSS `@import` statements.
+    #
+    # @param filename [String] The filename to search for
+    # @param load_paths [Array<String>] The set of filesystem paths
+    #   to search for Sass files.
+    # @return [String] The filename of the imported file.
+    #   This is an absolute path if the file is a `".sass"` file.
+    # @raise [Sass::SyntaxError] if `filename` ends in ``".sass"``
+    #   and no corresponding Sass file could be found.
     def find_file_to_import(filename, load_paths)
       was_sass = false
       original_filename = filename

data/lib/sass/plugin/merb.rb

@@ -25,7 +25,7 @@ unless defined?(Sass::MERB_LOADED)
 
   if version[0] > 0 || version[1] >= 9
 
-    class Merb::Rack::Application # :nodoc:
+    class Merb::Rack::Application
       def call_with_sass(env)
         if !Sass::Plugin.checked_for_updates ||
             Sass::Plugin.options[:always_update] || Sass::Plugin.options[:always_check]
@@ -40,7 +40,7 @@ unless defined?(Sass::MERB_LOADED)
 
   else
 
-    class MerbHandler # :nodoc:
+    class MerbHandler
       def process_with_sass(request, response)
         if !Sass::Plugin.checked_for_updates ||
             Sass::Plugin.options[:always_update] || Sass::Plugin.options[:always_check]

data/lib/sass/plugin/rails.rb

@@ -7,7 +7,6 @@ unless defined?(Sass::RAILS_LOADED)
                               :always_check      => RAILS_ENV != "production",
                               :full_exception    => RAILS_ENV != "production")
 
-  # :stopdoc:
   module ActionController
     class Base
       alias_method :sass_old_process, :process
@@ -21,5 +20,4 @@ unless defined?(Sass::RAILS_LOADED)
       end
     end
   end
-  # :startdoc:
 end