haml-edge 2.1.21 → 2.1.22

data/lib/sass/script/literal.rb

@@ -1,80 +1,172 @@
 module Sass::Script
-  class Literal # :nodoc:
+  # The abstract superclass for SassScript objects.
+  #
+  # Many of these methods, especially the ones that correspond to SassScript operations,
+  # are designed to be overridden by subclasses which may change the semantics somewhat.
+  # The operations listed here are just the defaults.
+  class Literal < Node
     require 'sass/script/string'
     require 'sass/script/number'
     require 'sass/script/color'
     require 'sass/script/bool'
 
+    # Returns the Ruby value of the literal.
+    # The type of this value varies based on the subclass.
+    #
+    # @return [Object]
     attr_reader :value
 
+    # Creates a new literal.
+    #
+    # @param value [Object] The object for \{#value}
     def initialize(value = nil)
       @value = value
     end
 
+    # Evaluates the literal.
+    #
+    # @param environment [Sass::Environment] The environment in which to evaluate the SassScript
+    # @return [Literal] This literal
     def perform(environment)
       self
     end
 
+    # The SassScript `and` operation.
+    #
+    # @param other [Literal] The right-hand side of the operator
+    # @return [Literal] The result of a logical and:
+    #   `other` if this literal isn't a false {Bool},
+    #   and this literal otherwise
     def and(other)
       to_bool ? other : self
     end
 
+    # The SassScript `or` operation.
+    #
+    # @param other [Literal] The right-hand side of the operator
+    # @return [Literal] The result of the logical or:
+    #   this literal if it isn't a false {Bool},
+    #   and `other` otherwise
     def or(other)
       to_bool ? self : other
     end
 
+    # The SassScript `==` operation.
+    # **Note that this returns a {Sass::Script::Bool} object,
+    # not a Ruby boolean**.
+    #
+    # @param other [Literal] The right-hand side of the operator
+    # @return [Bool] True if this literal is the same as the other,
+    #   false otherwise
     def eq(other)
       Sass::Script::Bool.new(self.class == other.class && self.value == other.value)
     end
 
+    # The SassScript `!=` operation.
+    # **Note that this returns a {Sass::Script::Bool} object,
+    # not a Ruby boolean**.
+    #
+    # @param other [Literal] The right-hand side of the operator
+    # @return [Bool] False if this literal is the same as the other,
+    #   true otherwise
     def neq(other)
       Sass::Script::Bool.new(!eq(other).to_bool)
     end
 
+    # The SassScript `==` operation.
+    # **Note that this returns a {Sass::Script::Bool} object,
+    # not a Ruby boolean**.
+    #
+    # @param other [Literal] The right-hand side of the operator
+    # @return [Bool] True if this literal is the same as the other,
+    #   false otherwise
     def unary_not
       Sass::Script::Bool.new(!to_bool)
     end
 
+    # The SassScript default operation (e.g. `!a !b`, `"foo" "bar"`).
+    #
+    # @param other [Literal] The right-hand side of the operator
+    # @return [Script::String] A string containing both literals
+    #   separated by a space
     def concat(other)
       Sass::Script::String.new("#{self.to_s} #{other.to_s}")
     end
 
+    # The SassScript `,` operation (e.g. `!a, !b`, `"foo", "bar"`).
+    #
+    # @param other [Literal] The right-hand side of the operator
+    # @return [Script::String] A string containing both literals
+    #   separated by `", "`
     def comma(other)
       Sass::Script::String.new("#{self.to_s}, #{other.to_s}")
     end
 
+    # The SassScript `+` operation.
+    #
+    # @param other [Literal] The right-hand side of the operator
+    # @return [Script::String] A string containing both literals
+    #   without any separation
     def plus(other)
       Sass::Script::String.new(self.to_s + other.to_s)
     end
 
+    # The SassScript `-` operation.
+    #
+    # @param other [Literal] The right-hand side of the operator
+    # @return [Script::String] A string containing both literals
+    #   separated by `"-"`
     def minus(other)
       Sass::Script::String.new("#{self.to_s}-#{other.to_s}")
     end
 
+    # The SassScript `/` operation.
+    #
+    # @param other [Literal] The right-hand side of the operator
+    # @return [Script::String] A string containing both literals
+    #   separated by `"/"`
     def div(other)
       Sass::Script::String.new("#{self.to_s}/#{other.to_s}")
     end
 
+    # The SassScript unary `-` operation (e.g. `-!a`).
+    #
+    # @param other [Literal] The right-hand side of the operator
+    # @return [Script::String] A string containing the literal
+    #   preceded by `"-"`
     def unary_minus
       Sass::Script::String.new("-#{self.to_s}")
     end
 
+    # The SassScript unary `/` operation (e.g. `/!a`).
+    #
+    # @param other [Literal] The right-hand side of the operator
+    # @return [Script::String] A string containing the literal
+    #   preceded by `"/"`
     def unary_div
       Sass::Script::String.new("/#{self.to_s}")
     end
 
+    # @return [String] A readable representation of the literal
     def inspect
       value.inspect
     end
 
+    # @return [Boolean] `true` (the Ruby boolean value)
     def to_bool
       true
     end
 
+    # Compares this object with another.
+    #
+    # @param other [Object] The object to compare with
+    # @return [Boolean] Whether or not this literal is equivalent to `other`
     def ==(other)
       eq(other).to_bool
     end
 
+    # @return [Fixnum] The integer value of this literal
+    # @raise [Sass::SyntaxError] if this literal isn't an integer
     def to_i
       raise Sass::SyntaxError.new("#{self.inspect} is not an integer.")
     end

data/lib/sass/script/node.rb

@@ -0,0 +1,14 @@
+module Sass::Script
+  # The abstract superclass for SassScript parse tree nodes.
+  #
+  # Use \{#perform} to evaluate a parse tree.
+  class Node
+    # Evaluates the node.
+    #
+    # @param environment [Sass::Environment] The environment in which to evaluate the SassScript
+    # @return [Literal] The SassScript object that is the value of the SassScript
+    def perform(environment)
+      raise NotImplementedError.new("All subclasses of Sass::Script::Node must override #perform.")
+    end
+  end
+end

data/lib/sass/script/number.rb

@@ -1,12 +1,38 @@
 require 'sass/script/literal'
 
 module Sass::Script
-  class Number < Literal # :nodoc:
-
-    attr_reader :numerator_units, :denominator_units
-
+  # A SassScript object representing a number.
+  # SassScript numbers can have decimal values,
+  # and can also have units.
+  # For example, `12`, `1px`, and `10.45em`
+  # are all valid values.
+  #
+  # Numbers can also have more complex units, such as `1px*em/in`.
+  # These cannot be inputted directly in Sass code at the moment.
+  class Number < Literal
+    # The Ruby value of the number.
+    #
+    # @return [Numeric]
+    attr_reader :value
+
+    # A list of units in the numerator of the number.
+    # For example, `1px*em/in*cm` would return `["px", "em"]`
+    # @return [Array<String>] 
+    attr_reader :numerator_units
+
+    # A list of units in the denominator of the number.
+    # For example, `1px*em/in*cm` would return `["in", "cm"]`
+    # @return [Array<String>]
+    attr_reader :denominator_units
+
+    # The precision with which numbers will be printed to CSS files.
+    # For example, if this is `1000.0`,
+    # `3.1415926` will be printed as `3.142`.
     PRECISION = 1000.0
 
+    # @param value [Numeric] The value of the number
+    # @param numerator_units [Array<String>] See \{#numerator\_units}
+    # @param denominator_units [Array<String>] See \{#denominator\_units}
     def initialize(value, numerator_units = [], denominator_units = [])
       super(value)
       @numerator_units = numerator_units
@@ -14,6 +40,21 @@ module Sass::Script
       normalize!
     end
 
+    # The SassScript `+` operation.
+    # Its functionality depends on the type of its argument:
+    #
+    # {Number}
+    # : Adds the two numbers together, converting units if possible.
+    #
+    # {Color}
+    # : Adds this number to each of the RGB color channels.
+    #
+    # {Literal}
+    # : See {Literal#plus}.
+    #
+    # @param other [Literal] The right-hand side of the operator
+    # @return [Literal] The result of the operation
+    # @raise [Sass::SyntaxError] if `other` is a number with incompatible units
     def plus(other)
       if other.is_a? Number
         operate(other, :+)
@@ -24,6 +65,18 @@ module Sass::Script
       end
     end
 
+    # The SassScript binary `-` operation (e.g. `!a - !b`).
+    # Its functionality depends on the type of its argument:
+    #
+    # {Number}
+    # : Subtracts this number from the other, converting units if possible.
+    #
+    # {Literal}
+    # : See {Literal#minus}.
+    #
+    # @param other [Literal] The right-hand side of the operator
+    # @return [Literal] The result of the operation
+    # @raise [Sass::SyntaxError] if `other` is a number with incompatible units
     def minus(other)
       if other.is_a? Number
         operate(other, :-)
@@ -32,10 +85,25 @@ module Sass::Script
       end
     end
 
+    # The SassScript unary `-` operation (e.g. `-!a`).
+    #
+    # @return [Number] The negative value of this number
     def unary_minus
       Number.new(-value, numerator_units, denominator_units)
     end
 
+    # The SassScript `*` operation.
+    # Its functionality depends on the type of its argument:
+    #
+    # {Number}
+    # : Multiplies the two numbers together, converting units appropriately.
+    #
+    # {Color}
+    # : Multiplies each of the RGB color channels by this number.
+    #
+    # @param other [Number, Color] The right-hand side of the operator
+    # @return [Number, Color] The result of the operation
+    # @raise [NoMethodError] if `other` is an invalid type
     def times(other)
       if other.is_a? Number
         self.operate(other, :*)
@@ -46,6 +114,17 @@ module Sass::Script
       end
     end
 
+    # The SassScript `/` operation.
+    # Its functionality depends on the type of its argument:
+    #
+    # {Number}
+    # : Divides this number by the other, converting units appropriately.
+    #
+    # {Literal}
+    # : See {Literal#div}.
+    #
+    # @param other [Literal] The right-hand side of the operator
+    # @return [Literal] The result of the operation
     def div(other)
       if other.is_a? Number
         operate(other, :/)
@@ -54,6 +133,12 @@ module Sass::Script
       end
     end
 
+    # The SassScript `%` operation.
+    #
+    # @param other [Number] The right-hand side of the operator
+    # @return [Number] This number modulo the other
+    # @raise [NoMethodError] if `other` is an invalid type
+    # @raise [Sass::SyntaxError] if `other` has any units
     def mod(other)
       if other.is_a?(Number)
         unless other.unitless?
@@ -65,37 +150,70 @@ module Sass::Script
       end
     end
 
+    # The SassScript `==` operation.
+    #
+    # @param other [Literal] The right-hand side of the operator
+    # @return [Boolean] Whether this number is equal to the other object
     def eq(other)
       Sass::Script::Bool.new(super.to_bool &&
         self.numerator_units.sort == other.numerator_units.sort &&
         self.denominator_units.sort == other.denominator_units.sort)
     end
 
+    # The SassScript `>` operation.
+    #
+    # @param other [Number] The right-hand side of the operator
+    # @return [Boolean] Whether this number is greater than the other
+    # @raise [NoMethodError] if `other` is an invalid type
     def gt(other)
       raise NoMethodError.new(nil, :gt) unless other.is_a?(Number)
       operate(other, :>)
     end
 
+    # The SassScript `>=` operation.
+    #
+    # @param other [Number] The right-hand side of the operator
+    # @return [Boolean] Whether this number is greater than or equal to the other
+    # @raise [NoMethodError] if `other` is an invalid type
     def gte(other)
       raise NoMethodError.new(nil, :gte) unless other.is_a?(Number)
       operate(other, :>=)
     end
 
+    # The SassScript `<` operation.
+    #
+    # @param other [Number] The right-hand side of the operator
+    # @return [Boolean] Whether this number is less than the other
+    # @raise [NoMethodError] if `other` is an invalid type
     def lt(other)
       raise NoMethodError.new(nil, :lt) unless other.is_a?(Number)
       operate(other, :<)
     end
 
+    # The SassScript `<=` operation.
+    #
+    # @param other [Number] The right-hand side of the operator
+    # @return [Boolean] Whether this number is less than or equal to the other
+    # @raise [NoMethodError] if `other` is an invalid type
     def lte(other)
       raise NoMethodError.new(nil, :lte) unless other.is_a?(Number)
       operate(other, :<=)
     end
 
+    # @return [String] The CSS representation of this number
+    # @raise [Sass::SyntaxError] if this number has units that can't be used in CSS
+    #   (e.g. `px*in`)
     def to_s
       raise Sass::SyntaxError.new("#{inspect} isn't a valid CSS value.") unless legal_units?
       inspect
     end
 
+    # Returns a readable representation of this number.
+    #
+    # This representation is valid CSS (and valid SassScript)
+    # as long as there is only one unit.
+    #
+    # @return [String] The representation
     def inspect
       value =
         if self.value.is_a?(Float) && (self.value.infinite? || self.value.nan?)
@@ -108,19 +226,25 @@ module Sass::Script
       "#{value}#{unit_str}"
     end
 
+    # @return [Fixnum] The integer value of the number
+    # @raise [Sass::SyntaxError] if the number isn't an integer
     def to_i
       super unless int?
       return value
     end
 
+    # @return [Boolean] Whether or not this number is an integer.
     def int?
       value % 1 == 0.0
     end
 
+    # @return [Boolean] Whether or not this number has no units.
     def unitless?
       numerator_units.empty? && denominator_units.empty?
     end
 
+    # @return [Boolean] Whether or not this number has units that can be represented in CSS
+    #   (that is, zero or one \{#numerator\_units}).
     def legal_units?
       (numerator_units.empty? || numerator_units.size == 1) && denominator_units.empty?
     end

data/lib/sass/script/operation.rb

@@ -1,3 +1,4 @@
+require 'set'
 require 'sass/script/string'
 require 'sass/script/number'
 require 'sass/script/color'
@@ -5,17 +6,31 @@ require 'sass/script/functions'
 require 'sass/script/unary_operation'
 
 module Sass::Script
-  class Operation # :nodoc:
+  # A SassScript parse node representing a binary operation,
+  # such as `!a + !b` or `"foo" + 1`.
+  class Operation < Node
+    # @param operand1 [Script::Node] The parse-tree node
+    #   for the right-hand side of the operator
+    # @param operand2 [Script::Node] The parse-tree node
+    #   for the left-hand side of the operator
+    # @param operator [Symbol] The operator to perform.
+    #   This should be one of the binary operator names in {Lexer::OPERATORS}
     def initialize(operand1, operand2, operator)
       @operand1 = operand1
       @operand2 = operand2
       @operator = operator
     end
 
+    # @return [String] A human-readable s-expression representation of the operation
     def inspect
       "(#{@operator.inspect} #{@operand1.inspect} #{@operand2.inspect})"
     end
 
+    # Evaluates the operation.
+    #
+    # @param environment [Sass::Environment] The environment in which to evaluate the SassScript
+    # @return [Literal] The SassScript object that is the value of the operation
+    # @raise [Sass::SyntaxError] if the operation is undefined for the operands
     def perform(environment)
       literal1 = @operand1.perform(environment)
       literal2 = @operand2.perform(environment)

data/lib/sass/script/parser.rb

@@ -2,55 +2,85 @@ require 'sass/script/lexer'
 
 module Sass
   module Script
+    # The parser for SassScript.
+    # It parses a string of code into a tree of {Script::Node}s.
     class Parser
+      # @param str [String, StringScanner] The source text to parse
+      # @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
+      # @param filename [String] The name of the file in which the SassScript appears.
+      #   Used for error reporting
       def initialize(str, line, offset, filename = nil)
         @filename = filename
         @lexer = Lexer.new(str, line, offset)
       end
 
+      # Parses a SassScript expression within an interpolated segment (`#{}`).
+      # This means that it stops when it comes across an unmatched `}`,
+      # which signals the end of an interpolated segment,
+      # it returns rather than throwing an error.
+      #
+      # @return [Script::Node] The root node of the parse tree
+      # @raise [Sass::SyntaxError] if the expression isn't valid SassScript
       def parse_interpolated
         expr = assert_expr :expr
         assert_tok :end_interpolation
         expr
       end
 
+      # Parses a SassScript expression.
+      #
+      # @return [Script::Node] The root node of the parse tree
+      # @raise [Sass::SyntaxError] if the expression isn't valid SassScript
       def parse
         expr = assert_expr :expr
         raise Sass::SyntaxError.new("Unexpected #{@lexer.peek.type} token.") unless @lexer.done?
         expr
       end
 
+      # Parses a SassScript expression.
+      #
+      # @overload parse(str, line, offset, filename = nil)
+      # @return [Script::Node] The root node of the parse tree
+      # @see Parser#initialize
+      # @see Parser#parse
       def self.parse(*args)
         new(*args).parse
       end
 
-      private
-
-      # Defines a simple left-associative production.
-      # name is the name of the production,
-      # sub is the name of the production beneath it,
-      # and ops is a list of operators for this precedence level
-      def self.production(name, sub, *ops)
-        class_eval <<RUBY
-          def #{name}
-            return unless e = #{sub}
-            while tok = try_tok(#{ops.map {|o| o.inspect}.join(', ')})
-              e = Operation.new(e, assert_expr(#{sub.inspect}), tok.type)
+      class << self
+        private
+
+        # Defines a simple left-associative production.
+        # name is the name of the production,
+        # sub is the name of the production beneath it,
+        # and ops is a list of operators for this precedence level
+        def production(name, sub, *ops)
+          class_eval <<RUBY
+            def #{name}
+              return unless e = #{sub}
+              while tok = try_tok(#{ops.map {|o| o.inspect}.join(', ')})
+                e = Operation.new(e, assert_expr(#{sub.inspect}), tok.type)
+              end
+              e
             end
-            e
-          end
 RUBY
-      end
+        end
 
-      def self.unary(op, sub)
-        class_eval <<RUBY
-          def unary_#{op}
-            return #{sub} unless try_tok(:#{op})
-            UnaryOperation.new(assert_expr(:unary_#{op}), :#{op})
-          end
+        def unary(op, sub)
+          class_eval <<RUBY
+            def unary_#{op}
+              return #{sub} unless try_tok(:#{op})
+              UnaryOperation.new(assert_expr(:unary_#{op}), :#{op})
+            end
 RUBY
+        end
       end
 
+      private
+
       production :expr, :concat, :comma
 
       def concat

data/lib/sass/script/string.rb

@@ -1,9 +1,12 @@
 require 'sass/script/literal'
 
 module Sass::Script
-  class String < Literal # :nodoc:
-    def to_s
-      @value
-    end
+  # A SassScript object representing a string of text.
+  class String < Literal
+    # The Ruby value of the string.
+    #
+    # @return [String]
+    attr_reader :value
+    alias_method :to_s, :value
   end
 end

data/lib/sass/script/unary_operation.rb

@@ -1,14 +1,27 @@
 module Sass::Script
-  class UnaryOperation # :nodoc:
+  # A SassScript parse node representing a unary operation,
+  # such as `-!b` or `not true`.
+  #
+  # Currently only `-`, `/`, and `not` are unary operators.
+  class UnaryOperation < Node
+    # @param operand [Script::Node] The parse-tree node
+    #   for the object of the operator
+    # @param operator [Symbol] The operator to perform
     def initialize(operand, operator)
       @operand = operand
       @operator = operator
     end
 
+    # @return [String] A human-readable s-expression representation of the operation
     def inspect
       "(#{@operator.inspect} #{@operand.inspect})"
     end
 
+    # Evaluates the operation.
+    #
+    # @param environment [Sass::Environment] The environment in which to evaluate the SassScript
+    # @return [Literal] The SassScript object that is the value of the operation
+    # @raise [Sass::SyntaxError] if the operation is undefined for the operand
     def perform(environment)
       operator = "unary_#{@operator}"
       literal = @operand.perform(environment)

data/lib/sass/script/variable.rb

@@ -1,16 +1,27 @@
 module Sass
   module Script
-    class Variable # :nodoc:
+    # A SassScript parse node representing a variable.
+    class Variable < Node
+      # The name of the variable.
+      #
+      # @return [String]
       attr_reader :name
 
+      # @param name [String] See \{#name}
       def initialize(name)
         @name = name
       end
 
+      # @return [String] A string representation of the variable
       def inspect
         "!#{name}"
       end
 
+      # Evaluates the variable.
+      #
+      # @param environment [Sass::Environment] The environment in which to evaluate the SassScript
+      # @return [Literal] The SassScript object that is the value of the variable
+      # @raise [Sass::SyntaxError] if the variable is undefined
       def perform(environment)
         (val = environment.var(name)) && (return val)
         raise SyntaxError.new("Undefined variable: \"!#{name}\".")