haml-edge 2.1.21 → 2.1.22

data/lib/sass/plugin.rb

@@ -1,9 +1,13 @@
 require 'sass/engine'
 
 module Sass
-  # This module contains methods to aid in using Sass
-  # as a stylesheet-rendering plugin for various systems.
-  # Currently Rails/ActionController and Merb are supported out of the box.
+  # This module handles the compilation of Sass files.
+  # It provides global options and checks whether CSS files
+  # need to be updated.
+  #
+  # This module is used as the primary interface with Sass
+  # when it's used as a plugin for various frameworks.
+  # Currently Rails and Merb are supported out of the box.
   module Plugin
     extend self
 
@@ -15,37 +19,42 @@ module Sass
     }
     @checked_for_updates = false
 
-    # Whether or not Sass has *ever* checked if the stylesheets need updates
+    # Whether or not Sass has **ever** checked if the stylesheets need to be updated
     # (in this Ruby instance).
-    def checked_for_updates
-      @checked_for_updates
-    end
-
-    # Gets various options for Sass. See README.rdoc for details.
-    #--
-    # TODO: *DOCUMENT OPTIONS*
-    #++
-    def options
-      @options
-    end
-
-    # Sets various options for Sass.
+    #
+    # @return [Boolean]
+    attr_reader :checked_for_updates
+
+    # An options hash.
+    # See [the Sass options documentation](../Sass.html#sass_options).
+    #
+    # @return [Hash<Symbol, Object>]
+    attr_reader :options
+
+    # Sets the options hash.
+    # See [the Sass options documentation](../Sass.html#sass_options).
+    #
+    # @param value [Hash<Symbol, Object>] The options hash
     def options=(value)
       @options.merge!(value)
     end
 
-    # Get the options ready to be passed to the Sass::Engine
+    # Non-destructively modifies \{#options} so that default values are properly set.
+    #
+    # @param additional_options [Hash<Symbol, Object>] An options hash with which to merge \{#options}
+    # @return [Hash<Symbol, Object>] The modified options hash
     def engine_options(additional_options = {})
       opts = options.dup.merge(additional_options)
       opts[:load_paths] = load_paths(opts)
       opts
     end
 
-    # Checks each stylesheet in <tt>options[:css_location]</tt>
-    # to see if it needs updating,
-    # and updates it using the corresponding template
-    # from <tt>options[:templates]</tt>
-    # if it does.
+    # Updates out-of-date stylesheets.
+    #
+    # Checks each Sass file in [`:template_location`](../Sass.html#template_location-option)
+    # to see if it's been modified more recently than the corresponding CSS file
+    # in [`:css_location`](../Sass.html#css_location-option).
+    # If it has, it updates the CSS file.
     def update_stylesheets
       return if options[:never_update]
 

data/lib/sass/repl.rb

@@ -1,11 +1,18 @@
 require 'readline'
 
 module Sass
+  # Runs a SassScript read-eval-print loop.
+  # It presents a prompt on the terminal,
+  # reads in SassScript expressions,
+  # evaluates them,
+  # and prints the result.
   class Repl
+    # @param options [Hash<Symbol, Object>] An options hash.
     def initialize(options = {})
       @options = options
     end
 
+    # Starts the read-eval-print loop.
     def run
       environment = Environment.new
       environment.set_var('important', Script::String.new('!important'))

data/lib/sass/script/bool.rb

@@ -1,13 +1,17 @@
 require 'sass/script/literal'
 
 module Sass::Script
-  class Bool < Literal # :nodoc:
+  # A SassScript object representing a boolean (true or false) value.
+  class Bool < Literal
+    # The Ruby value of the boolean.
+    #
+    # @return [Boolean]
+    attr_reader :value
+    alias_method :to_bool, :value
+
+    # @return [String] "true" or "false"
     def to_s
       @value.to_s
     end
-
-    def to_bool
-      @value
-    end
   end
 end

data/lib/sass/script/color.rb

@@ -1,9 +1,11 @@
 require 'sass/script/literal'
 
 module Sass::Script
-  class Color < Literal # :nodoc:
+  # A SassScript object representing a CSS color.
+  class Color < Literal
     class << self; include Haml::Util; end
 
+    # A hash from color names to [red, green, blue] value arrays.
     HTML4_COLORS = map_vals({
         'black'   => 0x000000,
         'silver'  => 0xc0c0c0,
@@ -22,14 +24,33 @@ module Sass::Script
         'teal'    => 0x008080,
         'aqua'    => 0x00ffff
       }) {|color| (0..2).map {|n| color >> (n << 3) & 0xff}.reverse}
+    # A hash from [red, green, blue] value arrays to color names.
     HTML4_COLORS_REVERSE = map_hash(HTML4_COLORS) {|k, v| [v, k]}
 
+    # @param rgb [Array<Fixnum>] A three-element array of the red, green, and blue values (respectively)
+    #   of the color
+    # @raise [Sass::SyntaxError] if any color value isn't between 0 and 255
     def initialize(rgb)
       rgb = rgb.map {|c| c.to_i}
       raise Sass::SyntaxError.new("Color values must be between 0 and 255") if rgb.any? {|c| c < 0 || c > 255}
       super(rgb)
     end
 
+    # The SassScript `+` operation.
+    # Its functionality depends on the type of its argument:
+    #
+    # {Number}
+    # : Adds the number to each of the RGB color channels.
+    #
+    # {Color}
+    # : Adds each of the RGB color channels together.
+    #
+    # {Literal}
+    # : See {Literal#plus}.
+    #
+    # @param other [Literal] The right-hand side of the operator
+    # @return [Color] The resulting color
+    # @raise [Sass::SyntaxError] if `other` is a number with units
     def plus(other)
       if other.is_a?(Sass::Script::Number) || other.is_a?(Sass::Script::Color)
         piecewise(other, :+)
@@ -38,6 +59,21 @@ module Sass::Script
       end
     end
 
+    # The SassScript `-` operation.
+    # Its functionality depends on the type of its argument:
+    #
+    # {Number}
+    # : Subtracts the number from each of the RGB color channels.
+    #
+    # {Color}
+    # : Subtracts each of the other color's RGB color channels from this color's.
+    #
+    # {Literal}
+    # : See {Literal#minus}.
+    #
+    # @param other [Literal] The right-hand side of the operator
+    # @return [Color] The resulting color
+    # @raise [Sass::SyntaxError] if `other` is a number with units
     def minus(other)
       if other.is_a?(Sass::Script::Number) || other.is_a?(Sass::Script::Color)
         piecewise(other, :-)
@@ -46,6 +82,21 @@ module Sass::Script
       end
     end
 
+    # The SassScript `*` operation.
+    # Its functionality depends on the type of its argument:
+    #
+    # {Number}
+    # : Multiplies the number by each of the RGB color channels.
+    #
+    # {Color}
+    # : Multiplies each of the RGB color channels together.
+    #
+    # {Literal}
+    # : See {Literal#times}.
+    #
+    # @param other [Literal] The right-hand side of the operator
+    # @return [Color] The resulting color
+    # @raise [Sass::SyntaxError] if `other` is a number with units
     def times(other)
       if other.is_a?(Sass::Script::Number) || other.is_a?(Sass::Script::Color)
         piecewise(other, :*)
@@ -54,6 +105,21 @@ module Sass::Script
       end
     end
 
+    # The SassScript `/` operation.
+    # Its functionality depends on the type of its argument:
+    #
+    # {Number}
+    # : Divides each of the RGB color channels by the number.
+    #
+    # {Color}
+    # : Divides each of this color's RGB color channels by the other color's.
+    #
+    # {Literal}
+    # : See {Literal#div}.
+    #
+    # @param other [Literal] The right-hand side of the operator
+    # @return [Color] The resulting color
+    # @raise [Sass::SyntaxError] if `other` is a number with units
     def div(other)
       if other.is_a?(Sass::Script::Number) || other.is_a?(Sass::Script::Color)
         piecewise(other, :/)
@@ -62,6 +128,21 @@ module Sass::Script
       end
     end
 
+    # The SassScript `%` operation.
+    # Its functionality depends on the type of its argument:
+    #
+    # {Number}
+    # : Takes each of the RGB color channels module the number.
+    #
+    # {Color}
+    # : Takes each of this color's RGB color channels modulo the other color's.
+    #
+    # {Literal}
+    # : See {Literal#mod}.
+    #
+    # @param other [Literal] The right-hand side of the operator
+    # @return [Color] The resulting color
+    # @raise [Sass::SyntaxError] if `other` is a number with units
     def mod(other)
       if other.is_a?(Sass::Script::Number) || other.is_a?(Sass::Script::Color)
         piecewise(other, :%)
@@ -70,6 +151,11 @@ module Sass::Script
       end
     end
 
+    # Returns a string representation of the color.
+    # This is usually the color's hex value,
+    # but if the color has a name that's used instead.
+    #
+    # @return [String] The string representation
     def to_s
       return HTML4_COLORS_REVERSE[@value] if HTML4_COLORS_REVERSE[@value]
       red, green, blue = @value.map { |num| num.to_s(16).rjust(2, '0') }

data/lib/sass/script/funcall.rb

@@ -1,18 +1,39 @@
 require File.join(File.dirname(__FILE__), 'functions')
 module Sass
   module Script
-    class Funcall # :nodoc:
-      attr_reader :name, :args
+    # A SassScript parse node representing a function call.
+    #
+    # A function call either calls one of the functions in {Script::Functions},
+    # or if no function with the given name exists
+    # it returns a string representation of the function call.
+    class Funcall < Node
+      # The name of the function.
+      #
+      # @return [String]
+      attr_reader :name
 
+      # The arguments to the function.
+      #
+      # @return [Array<Script::Node>]
+      attr_reader :args
+
+      # @param name [String] See \{#name}
+      # @param name [Array<Script::Node>] See \{#args}
       def initialize(name, args)
         @name = name
         @args = args
       end
 
+      # @return [String] A string representation of the function call
       def inspect
         "#{name}(#{args.map {|a| a.inspect}.join(', ')})"
       end
 
+      # Evaluates the function call.
+      #
+      # @param environment [Sass::Environment] The environment in which to evaluate the SassScript
+      # @return [Literal] The SassScript object that is the value of the function call
+      # @raise [Sass::SyntaxError] if the function call raises an ArgumentError
       def perform(environment)
         args = self.args.map {|a| a.perform(environment)}
         unless Haml::Util.has?(:public_instance_method, Functions, name) && name !~ /^__/

data/lib/sass/script/functions.rb

@@ -1,15 +1,35 @@
 module Sass::Script
-  # Methods in this module are accessible from the Sass script context.
+  # Methods in this module are accessible from the SassScript context.
   # For example, you can write
   #
-  #   color = hsl(120, 100%, 50%)
+  #     !color = hsl(120, 100%, 50%)
   #
-  # and it will call Sass::Script::Functions#hsl.
+  # and it will call {Sass::Script::Functions#hsl}.
+  #
+  # The following functions are provided:
+  #
+  # \{#hsl}
+  # : Converts an `hsl(hue, saturation, lightness)` triplet into a color.
+  #
+  # \{#percentage}
+  # : Converts a unitless number to a percentage.
+  #
+  # \{#round}
+  # : Rounds a number to the nearest whole number.
+  #
+  # \{#ceil}
+  # : Rounds a number up to the nearest whole number.
+  #
+  # \{#floor}
+  # : Rounds a number down to the nearest whole number.
+  #
+  # \{#abs}
+  # : Returns the absolute value of a number.
   #
   # You can add your own functions to this module,
   # but there are a few things to keep in mind.
-  # First of all, the arguments passed are (currently undocumented) Sass::Script::Literal objects,
-  # Literal objects are also the expected return values.
+  # First of all, the arguments passed are {Sass::Script::Literal} objects.
+  # Literal objects are also expected to be returned.
   #
   # Second, making Ruby functions accessible from Sass introduces the temptation
   # to do things like database access within stylesheets.
@@ -17,38 +37,23 @@ module Sass::Script
   # Keep in mind that Sass stylesheets are only compiled once
   # at a somewhat indeterminate time
   # and then left as static CSS files.
-  # Any dynamic CSS should be left in <style> tags in the HTML.
-  #
-  # Within a sass function you can call the options method to gain access to the
-  # options hash that was used to create the Sass::Engine that is processing the function call.
-  #
-  # The following functions are provided:
-  # * +hsl+ - converts an <tt>hsl(hue, saturation, lightness)</tt> triplet into a color.
-  #
-  #   The +hue+ value should be between 0 and 360 inclusive,
-  #   saturation and lightness must be between <tt>0%</tt> to <tt>100%</tt> inclusive.
-  #   The percent sign is optional.
-  # * +percentage+ - converts a unitless number to a css percentage.
-  #
-  #   Example: <tt>percentage(14px / 7px) => 200%</tt>
-  # * +round+ - Rounds a number to the nearest whole number.
-  #
-  #   Example: <tt>round(10.4px) => 10px</tt>
-  # * +ceil+ - Rounds a number up to the nearest whole number.
-  #
-  #   Example: <tt>ceil(10.4px) => 11px</tt>
-  # * +floor+ - Rounds a number down to the nearest whole number.
-  #
-  #   Example: <tt>floor(10.6px) => 10px</tt>
-  # * +abs+ - Returns the absolute value of a number.
+  # Any dynamic CSS should be left in `<style>` tags in the HTML.
   #
-  #   Example: <tt>abs(-10px) => 10px</tt>
+  # Within one of the functions in this module,
+  # methods of {EvaluationContext} can be used.
   module Functions
-    class EvaluationContext # :nodoc:
+    # The context in which methods in {Script::Functions} are evaluated.
+    # That means that all instance methods of {EvaluationContext}
+    # are available to use in functions.
+    class EvaluationContext
       include Sass::Script::Functions
 
+      # The options hash for the {Sass::Engine} that is processing the function call
+      #
+      # @return [Hash<Symbol, Object>]
       attr_reader :options
 
+      # @param options [Hash<Symbol, Object>] See \{#options}
       def initialize(options)
         @options = options
       end
@@ -56,15 +61,22 @@ module Sass::Script
 
     instance_methods.each { |m| undef_method m unless m.to_s =~ /^__/ }
 
-    # Creates a Sass::Script::Color object from hue, saturation, and lightness.
-    # As per the CSS3 spec (http://www.w3.org/TR/css3-color/#hsl-color),
-    # hue is in degrees,
-    # and saturation and lightness are percentages.
-    def hsl(h, s, l)
-      original_s = s
-      original_l = l
+    # Creates a {Color} object from hue, saturation, and lightness
+    # as per the CSS3 spec (http://www.w3.org/TR/css3-color/#hsl-color).
+    #
+    # @param hue [Number] The hue of the color.
+    #   Should be between 0 and 360 degrees, inclusive
+    # @param saturation [Number] The saturation of the color.
+    #   Must be between `0%` and `100%`, inclusive
+    # @param lightness [Number] The lightness of the color.
+    #   Must be between `0%` and `100%`, inclusive
+    # @return [Color] The resulting color
+    # @raise [ArgumentError] if `saturation` or `lightness` are out of bounds
+    def hsl(hue, saturation, lightness)
+      original_s = saturation
+      original_l = lightness
       # This algorithm is from http://www.w3.org/TR/css3-color#hsl-color
-      h, s, l = [h, s, l].map { |a| a.value }
+      h, s, l = [hue, saturation, lightness].map { |a| a.value }
       raise ArgumentError.new("Saturation #{s} must be between 0% and 100%") if s < 0 || s > 100
       raise ArgumentError.new("Lightness #{l} must be between 0% and 100%") if l < 0 || l > 100
 
@@ -79,9 +91,14 @@ module Sass::Script
                  hue_to_rgb(m1, m2, h - 1.0/3)].map { |c| (c * 0xff).round })
     end
 
-    # Converts a unitless number into a percent and multiplies the number by 100.
-    # E.g. percentage(100px / 50px) => 200%
-    # Some may find this more natural than: 100% * 100px / 50px
+    # Converts a decimal number to a percentage.
+    # For example:
+    #
+    #     percentage(100px / 50px) => 200%
+    #
+    # @param value [Number] The decimal number to convert to a percentage
+    # @return [Number] The percentage
+    # @raise [ArgumentError] If `value` isn't a unitless number
     def percentage(value)
       unless value.is_a?(Sass::Script::Number) && value.unitless?
         raise ArgumentError.new("#{value} is not a unitless number")
@@ -90,21 +107,53 @@ module Sass::Script
     end
 
     # Rounds a number to the nearest whole number.
+    # For example:
+    #
+    #     round(10.4px) => 10px
+    #     round(10.6px) => 11px
+    #
+    # @param value [Number] The number
+    # @return [Number] The rounded number
+    # @raise [Sass::SyntaxError] if `value` isn't a number
     def round(value)
       numeric_transformation(value) {|n| n.round}
     end
 
-    # Rounds up to the nearest whole number.
+    # Rounds a number up to the nearest whole number.
+    # For example:
+    #
+    #     ciel(10.4px) => 11px
+    #     ciel(10.6px) => 11px
+    #
+    # @param value [Number] The number
+    # @return [Number] The rounded number
+    # @raise [Sass::SyntaxError] if `value` isn't a number
     def ceil(value)
       numeric_transformation(value) {|n| n.ceil}
     end
 
     # Rounds down to the nearest whole number.
+    # For example:
+    #
+    #     floor(10.4px) => 10px
+    #     floor(10.6px) => 10px
+    #
+    # @param value [Number] The number
+    # @return [Number] The rounded number
+    # @raise [Sass::SyntaxError] if `value` isn't a number
     def floor(value)
       numeric_transformation(value) {|n| n.floor}
     end
 
-    # Returns the absolute value of a number.
+    # Finds the absolute value of a number.
+    # For example:
+    #
+    #     abs(10px) => 10px
+    #     abs(-10px) => 10px
+    #
+    # @param value [Number] The number
+    # @return [Number] The absolute value
+    # @raise [Sass::SyntaxError] if `value` isn't a number
     def abs(value)
       numeric_transformation(value) {|n| n.abs}
     end

data/lib/sass/script/lexer.rb

@@ -2,9 +2,26 @@ require 'strscan'
 
 module Sass
   module Script
-    class Lexer # :nodoc:
+    # The lexical analyzer for SassScript.
+    # It takes a raw string and converts it to individual tokens
+    # that are easier to parse.
+    class Lexer
+      # A struct containing information about an individual token.
+      #
+      # `type`: [{Symbol}]
+      # : The type of token.
+      #
+      # `value`: [{Object}]
+      # : The Ruby object corresponding to the value of the token.
+      #
+      # `line`: [{Fixnum}]
+      # : The line of the source file on which the token appears.
+      #
+      # `offset`: [{Fixnum}]
+      # : The number of bytes into the line the SassScript token appeared.
       Token = Struct.new(:type, :value, :line, :offset)
 
+      # A hash from operator strings to the corresponding token types.
       OPERATORS = {
         '+' => :plus,
         '-' => :minus,
@@ -27,10 +44,11 @@ module Sass
         '}' => :end_interpolation,
       }
 
-      # We'll want to match longer names first
-      # so that > and < don't clobber >= and <=
+      # A list of operator strings ordered with longer names first
+      # so that `>` and `<` don't clobber `>=` and `<=`.
       OP_NAMES = OPERATORS.keys.sort_by {|o| -o.size}
 
+      # A hash of regular expressions that are used for tokenizing.
       REGULAR_EXPRESSIONS = {
         :whitespace => /\s*/,
         :variable => /!(\w+)/,
@@ -42,6 +60,11 @@ module Sass
         :op => %r{(#{Regexp.union(*OP_NAMES.map{|s| Regexp.new(Regexp.escape(s) + (s =~ /\w$/ ? '(?:\b|$)' : ''))})})}
       }
 
+      # @param str [String, StringScanner] The source text to lex
+      # @param line [Fixnum] The line on which the SassScript appears.
+      #   Used for error reporting
+      # @param offset [Fixnum] The number of characters in on which the SassScript appears.
+      #   Used for error reporting
       def initialize(str, line, offset)
         @scanner = str.is_a?(StringScanner) ? str : StringScanner.new(str)
         @line = line
@@ -49,6 +72,9 @@ module Sass
         @prev = nil
       end
 
+      # Moves the lexer forward one token.
+      #
+      # @return [Token] The token that was moved past
       def next
         @tok ||= read_token
         @tok, tok = nil, @tok
@@ -56,10 +82,14 @@ module Sass
         return tok
       end
 
+      # Returns the next token without moving the lexer forward.
+      #
+      # @return [Token] The next token
       def peek
         @tok ||= read_token
       end
 
+      # @return [Boolean] Whether or not there's more source text to lex.
       def done?
         whitespace unless after_interpolation?
         @scanner.eos? && @tok.nil?