Class: Sass::Script::Color

### Home Classes Methods

### In Files

- lib/sass/script/color.rb

### Parent

Literal

### Methods

- ::new
- #alpha
- #alpha?
- #blue
- #div
- #eq
- #green
- #hsl
- #hue
- #inspect
- #lightness
- #minus
- #mod
- #plus
- #red
- #rgb
- #saturation
- #times
- #to_s
- #to_sass
- #with

### Included Modules

- Sass::Util

### Class/Module Index

Quicksearch

- Sass
- Sass::CSS
- Sass::CacheStores
- Sass::CacheStores::Base
- Sass::CacheStores::Chain
- Sass::CacheStores::Filesystem
- Sass::CacheStores::Memory
- Sass::CacheStores::Null
- Sass::Callbacks
- Sass::Callbacks::InstanceMethods
- Sass::Engine
- Sass::Engine::Line
- Sass::Environment
- Sass::Exec
- Sass::Exec::Generic
- Sass::Exec::Sass
- Sass::Exec::SassConvert
- Sass::Exec::Scss
- Sass::Importers
- Sass::Importers::Base
- Sass::Importers::Filesystem
- Sass::Logger
- Sass::Logger::Base
- Sass::Logger::LogLevel
- Sass::Logger::LogLevel::ClassMethods
- Sass::Media
- Sass::Media::Query
- Sass::Media::QueryList
- Sass::Plugin
- Sass::Plugin::Compiler
- Sass::Plugin::Configuration
- Sass::Plugin::MerbBootLoader
- Sass::Plugin::Rack
- Sass::Plugin::StalenessChecker
- Sass::Repl
- Sass::SCSS
- Sass::SCSS::CssParser
- Sass::SCSS::Parser
- Sass::SCSS::RX
- Sass::SCSS::ScriptLexer
- Sass::SCSS::ScriptParser
- Sass::SCSS::StaticParser
- Sass::Script
- Sass::Script::ArgList
- Sass::Script::Bool
- Sass::Script::Color
- Sass::Script::CssLexer
- Sass::Script::CssParser
- Sass::Script::Funcall
- Sass::Script::Functions
- Sass::Script::Functions::EvaluationContext
- Sass::Script::Interpolation
- Sass::Script::Lexer
- Sass::Script::List
- Sass::Script::Literal
- Sass::Script::Node
- Sass::Script::Null
- Sass::Script::Number
- Sass::Script::Operation
- Sass::Script::Parser
- Sass::Script::String
- Sass::Script::StringInterpolation
- Sass::Script::UnaryOperation
- Sass::Script::Variable
- Sass::Selector
- Sass::Selector::AbstractSequence
- Sass::Selector::Attribute
- Sass::Selector::Class
- Sass::Selector::CommaSequence
- Sass::Selector::Element
- Sass::Selector::Id
- Sass::Selector::Interpolation
- Sass::Selector::Parent
- Sass::Selector::Placeholder
- Sass::Selector::Pseudo
- Sass::Selector::SelectorPseudoClass
- Sass::Selector::Sequence
- Sass::Selector::Simple
- Sass::Selector::SimpleSequence
- Sass::Selector::Universal
- Sass::Shared
- Sass::Supports
- Sass::Supports::Condition
- Sass::Supports::Declaration
- Sass::Supports::Interpolation
- Sass::Supports::Negation
- Sass::Supports::Operator
- Sass::SyntaxError
- Sass::Tree
- Sass::Tree::CharsetNode
- Sass::Tree::CommentNode
- Sass::Tree::ContentNode
- Sass::Tree::CssImportNode
- Sass::Tree::DebugNode
- Sass::Tree::DirectiveNode
- Sass::Tree::EachNode
- Sass::Tree::ExtendNode
- Sass::Tree::ForNode
- Sass::Tree::FunctionNode
- Sass::Tree::IfNode
- Sass::Tree::ImportNode
- Sass::Tree::MediaNode
- Sass::Tree::MixinDefNode
- Sass::Tree::MixinNode
- Sass::Tree::Node
- Sass::Tree::PropNode
- Sass::Tree::ReturnNode
- Sass::Tree::RootNode
- Sass::Tree::RuleNode
- Sass::Tree::SupportsNode
- Sass::Tree::TraceNode
- Sass::Tree::VariableNode
- Sass::Tree::Visitors
- Sass::Tree::Visitors::Base
- Sass::Tree::Visitors::CheckNesting
- Sass::Tree::Visitors::Convert
- Sass::Tree::Visitors::Cssize
- Sass::Tree::Visitors::DeepCopy
- Sass::Tree::Visitors::Extend
- Sass::Tree::Visitors::Perform
- Sass::Tree::Visitors::SetOptions
- Sass::Tree::Visitors::ToCss
- Sass::Tree::WarnNode
- Sass::Tree::WhileNode
- Sass::UnitConversionError
- Sass::Util
- Sass::Util::MultibyteStringScanner
- Sass::Util::StaticConditionalContext
- Sass::Util::SubsetMap
- Sass::Util::Test
- Sass::Version
- ActionController
- ActionController::Base
- Object

No matching classes.

# Sass::Script::Color

A SassScript object representing a CSS color.

A color may be represented internally as RGBA, HSLA, or both. It's originally represented as whatever its input is; if it's created with RGB values, it's represented as RGBA, and if it's created with HSL values, it's represented as HSLA. Once a property is accessed that requires the other representation -- for example, {#red} for an HSL color -- that component is calculated and cached.

The alpha channel of a color is independent of its RGB or HSL representation. It's always stored, as 1 if nothing else is specified. If only the alpha channel is modified using {#with}, the cached RGB and HSL values are retained.

### Constants

COLOR_NAMES

  A hash from color names to `[red, green, blue]` value arrays.

COLOR_NAMES_REVERSE

  A hash from `[red, green, blue]` value arrays to color names.

### Public Class Methods

new(attrs, allow_both_rgb_and_hsl = false) click to toggle source

Constructs an RGB or HSL color object, optionally with an alpha channel.

The RGB values must be between 0 and 255. The saturation and lightness values must be between 0 and 100. The alpha value must be between 0 and 1.

@raise [Sass::SyntaxError] if any color value isn't in the specified range

@overload initialize(attrs)

    The attributes are specified as a hash.
    This hash must contain either `:hue`, `:saturation`, and `:value` keys,
    or `:red`, `:green`, and `:blue` keys.
    It cannot contain both HSL and RGB keys.
    It may also optionally contain an `:alpha` key.

    @param attrs [{Symbol => Numeric}] A hash of color attributes to values
    @raise [ArgumentError] if not enough attributes are specified,
      or both RGB and HSL attributes are specified

@overload initialize(rgba)

    The attributes are specified as an array.
    This overload only supports RGB or RGBA colors.

    @param rgba [Array<Numeric>] A three- or four-element array
      of the red, green, blue, and optionally alpha values (respectively)
      of the color
    @raise [ArgumentError] if not enough attributes are specified

    # File lib/sass/script/color.rb, line 202
    def initialize(attrs, allow_both_rgb_and_hsl = false)
      super(nil)

      if attrs.is_a?(Array)
        unless (3..4).include?(attrs.size)
          raise ArgumentError.new("Color.new(array) expects a three- or four-element array")
        end

        red, green, blue = attrs[0...3].map {|c| c.to_i}
        @attrs = {:red => red, :green => green, :blue => blue}
        @attrs[:alpha] = attrs[3] ? attrs[3].to_f : 1
      else
        attrs = attrs.reject {|k, v| v.nil?}
        hsl = [:hue, :saturation, :lightness] & attrs.keys
        rgb = [:red, :green, :blue] & attrs.keys
        if !allow_both_rgb_and_hsl && !hsl.empty? && !rgb.empty?
          raise ArgumentError.new("Color.new(hash) may not have both HSL and RGB keys specified")
        elsif hsl.empty? && rgb.empty?
          raise ArgumentError.new("Color.new(hash) must have either HSL or RGB keys specified")
        elsif !hsl.empty? && hsl.size != 3
          raise ArgumentError.new("Color.new(hash) must have all three HSL values specified")
        elsif !rgb.empty? && rgb.size != 3
          raise ArgumentError.new("Color.new(hash) must have all three RGB values specified")
        end

        @attrs = attrs
        @attrs[:hue] = 360 if @attrs[:hue]
        @attrs[:alpha] ||= 1
      end

      [:red, :green, :blue].each do |k|
        next if @attrs[k].nil?
        @attrs[k] = @attrs[k].to_i
        Sass::Util.check_range("#{k.to_s.capitalize} value", 0..255, @attrs[k])
      end

      [:saturation, :lightness].each do |k|
        next if @attrs[k].nil?
        value = Number.new(@attrs[k], ['%']) # Get correct unit for error messages
        @attrs[k] = Sass::Util.check_range("#{k.to_s.capitalize}", 0..100, value, '%')
      end

      @attrs[:alpha] = Sass::Util.check_range("Alpha channel", 0..1, @attrs[:alpha])
    end

### Public Instance Methods

alpha() click to toggle source

The alpha channel (opacity) of the color. This is 1 unless otherwise defined.

@return [Fixnum]

    # File lib/sass/script/color.rb, line 299
    def alpha
      @attrs[:alpha]
    end

alpha?() click to toggle source

Returns whether this color object is translucent; that is, whether the alpha channel is non-1.

@return [Boolean]

    # File lib/sass/script/color.rb, line 307
    def alpha?
      alpha < 1
    end

blue() click to toggle source

The blue component of the color.

@return [Fixnum]

    # File lib/sass/script/color.rb, line 266
    def blue
      hsl_to_rgb!
      @attrs[:blue]
    end

div(other) click to toggle source

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

    # File lib/sass/script/color.rb, line 461
    def div(other)
      if other.is_a?(Sass::Script::Number) || other.is_a?(Sass::Script::Color)
        piecewise(other, :/)
      else
        super
      end
    end

eq(other) click to toggle source

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

    # File lib/sass/script/color.rb, line 334
    def eq(other)
      Sass::Script::Bool.new(
        other.is_a?(Color) && rgb == other.rgb && alpha == other.alpha)
    end

green() click to toggle source

The green component of the color.

@return [Fixnum]

    # File lib/sass/script/color.rb, line 258
    def green
      hsl_to_rgb!
      @attrs[:green]
    end

hsl() click to toggle source

Returns the hue, saturation, and lightness components of the color.

@return [Array<Fixnum>] A frozen three-element array of the

    hue, saturation, and lightness values (respectively) of the color

    # File lib/sass/script/color.rb, line 323
    def hsl
      [hue, saturation, lightness].freeze
    end

hue() click to toggle source

The hue component of the color.

@return [Numeric]

    # File lib/sass/script/color.rb, line 274
    def hue
      rgb_to_hsl!
      @attrs[:hue]
    end

inspect() click to toggle source

Returns a string representation of the color.

@return [String] The hex value

    # File lib/sass/script/color.rb, line 505
    def inspect
      alpha? ? rgba_str : hex_str
    end

lightness() click to toggle source

The lightness component of the color.

@return [Numeric]

    # File lib/sass/script/color.rb, line 290
    def lightness
      rgb_to_hsl!
      @attrs[:lightness]
    end

minus(other) click to toggle source

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

    # File lib/sass/script/color.rb, line 418
    def minus(other)
      if other.is_a?(Sass::Script::Number) || other.is_a?(Sass::Script::Color)
        piecewise(other, :-)
      else
        super
      end
    end

mod(other) click to toggle source

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.

@param other [Number, Color] The right-hand side of the operator @return [Color] The resulting color @raise [Sass::SyntaxError] if `other` is a number with units

    # File lib/sass/script/color.rb, line 481
    def mod(other)
      if other.is_a?(Sass::Script::Number) || other.is_a?(Sass::Script::Color)
        piecewise(other, :%)
      else
        raise NoMethodError.new(nil, :mod)
      end
    end

plus(other) click to toggle source

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

    # File lib/sass/script/color.rb, line 395
    def plus(other)
      if other.is_a?(Sass::Script::Number) || other.is_a?(Sass::Script::Color)
        piecewise(other, :+)
      else
        super
      end
    end

red() click to toggle source

The red component of the color.

@return [Fixnum]

    # File lib/sass/script/color.rb, line 250
    def red
      hsl_to_rgb!
      @attrs[:red]
    end

rgb() click to toggle source

Returns the red, green, and blue components of the color.

@return [Array<Fixnum>] A frozen three-element array of the red, green, and blue

    values (respectively) of the color

    # File lib/sass/script/color.rb, line 315
    def rgb
      [red, green, blue].freeze
    end

saturation() click to toggle source

The saturation component of the color.

@return [Numeric]

    # File lib/sass/script/color.rb, line 282
    def saturation
      rgb_to_hsl!
      @attrs[:saturation]
    end

times(other) click to toggle source

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.

@param other [Number, Color] The right-hand side of the operator @return [Color] The resulting color @raise [Sass::SyntaxError] if `other` is a number with units

    # File lib/sass/script/color.rb, line 438
    def times(other)
      if other.is_a?(Sass::Script::Number) || other.is_a?(Sass::Script::Color)
        piecewise(other, :*)
      else
        raise NoMethodError.new(nil, :times)
      end
    end

to_s(opts = {}) click to toggle source

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

    # File lib/sass/script/color.rb, line 494
    def to_s(opts = {})
      return rgba_str if alpha?
      return smallest if options[:style] == :compressed
      return COLOR_NAMES_REVERSE[rgb] if COLOR_NAMES_REVERSE[rgb]
      hex_str
    end

Also aliased as: to_sass
to_sass(opts = {}) click to toggle source
Alias for: to_s
with(attrs) click to toggle source

Returns a copy of this color with one or more channels changed. RGB or HSL colors may be changed, but not both at once.

For example:

    Color.new([10, 20, 30]).with(:blue => 40)
      #=> rgb(10, 40, 30)
    Color.new([126, 126, 126]).with(:red => 0, :green => 255)
      #=> rgb(0, 255, 126)
    Color.new([255, 0, 127]).with(:saturation => 60)
      #=> rgb(204, 51, 127)
    Color.new([1, 2, 3]).with(:alpha => 0.4)
      #=> rgba(1, 2, 3, 0.4)

@param attrs [{Symbol => Numeric}]

    A map of channel names (`:red`, `:green`, `:blue`,
    `:hue`, `:saturation`, `:lightness`, or `:alpha`) to values

@return [Color] The new Color object @raise [ArgumentError] if both RGB and HSL keys are specified

    # File lib/sass/script/color.rb, line 358
    def with(attrs)
      attrs = attrs.reject {|k, v| v.nil?}
      hsl = !([:hue, :saturation, :lightness] & attrs.keys).empty?
      rgb = !([:red, :green, :blue] & attrs.keys).empty?
      if hsl && rgb
        raise ArgumentError.new("Cannot specify HSL and RGB values for a color at the same time")
      end

      if hsl
        [:hue, :saturation, :lightness].each {|k| attrs[k] ||= send(k)}
      elsif rgb
        [:red, :green, :blue].each {|k| attrs[k] ||= send(k)}
      else
        # If we're just changing the alpha channel,
        # keep all the HSL/RGB stuff we've calculated
        attrs = @attrs.merge(attrs)
      end
      attrs[:alpha] ||= alpha

      Color.new(attrs, :allow_both_rgb_and_hsl)
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.