Colir

Repository: https://github.com/kyrylo/colir

Description

This tiny library provides support for RGB colours and some simple manipulations with them.

Installation

gem install colir

Synopsis

The name Colir means “colour” in Ukrainian (roughly). OK, enough of rant, let's talk about the API instead.

Basics

You can create colours with human readable names. For example, the following code would create opaque red colour (0xff000000).

require 'colir'

# Create a new Colir.
red = Colir.red #=> #<Colir:...>
# Get a valid RGB colour, represented as an integer number.
red.hex #=> 16711680
# Why do you never trust me?
red.hex.to_s(16) #=> "ff0000"

# You can also get the same colour, but with alpha channel.
red.hexa #=> 4278190080
# Okay, okay!
red.hexa.to_s(16) #=> "ff000000"

The list of all human readable colour names can be found at w3schools. Actually, you can create any valid RGB colours, not just the predefined ones.

# This is valid.
yup = Colir.new(0xff0000) #=> #<Colir:...>
# This isn't. There is no such RGB colour.
nope = Colir.new(0xff00001) #=> RangeError: out of allowed RGB values

Transparency

As you may have noticed, the library supports transparent colours.

# Shortcut methods have only 1 parameter, which is transparency. It must lie
# within the range of 0..1
red = Colir.red(0.3)
red.hexa #=> 4278190110
red.hexa.to_s(16) #=> "ff00001e"
red.transparency #=> 0.3

# With arbitrary colours you can pass the second parameter.
green = Colir.new(0x00ff00, 0.3)
green.hexa #=> 16711710
green.hexa.to_s(16) #=> "0x00ff001e"
green.transparency #=> 0.3

# The default transparency is 0.0
green = Colir.new(0x00ff00)
green.transparency #=> 0.0

It's possible to adjust a Colir's transparency.

# `#opaque!` and `#transparent!` set a Colir's transparency to `0.0`
# and `1.0` respectively.
blue = Colir.new(0x0000ff, 0.45)
blue.transparency #=> 0.3
blue.transparent! #=> (Colir: 0x00ff00e1)
blue.transparency #=> 0.0
blue.opaque! #=> (Colir: 0x00ff00ff)
blue.transparency #=> 1.0

# You can set your own transparency value.
blue.transparency = 0.9 #=> 0.9
blue.transparency #=> 0.9

# But be careful, as the valid value is anything in between 0 and 1.
blue.transparency = 1.01 #=> RangeError: ...

Shades

Last but not least, you can use colour shades.

yellow = Colir.yellow
yellow.shade #=> 0

# Let's make it a bit darker.
yellow.darken #=> #<Colir:...>
yellow.shade #=> -1
yellow.hex #=> 13421568

# Hum, that's not dark enough. Let's do it one more time.
yellow.darken
yellow.shade #=> -2
yellow.hex #=> 10066176

# Actually, the previous shade was better!
yellow.lighten
yellow.shade #=> -1
yellow.hex #=> 13421568

The previous examples modify the Colir object (#darken and #lighten). Hovewer, there are two other methods that return a new object: #darker and #lighter.

# HEXes
orange = Colir.orange
orange.hex #=> 16753920
orange.darker.hex #=> 13403392
orange.hex #=> 16753920

# Shades
orange = Colir.orange
orange.shade #=> 0
orange.lighter.shade #=> 1
orange.shade #=> 0

There is a handy way to reset the shade level. Can you guess it? Of course, it's the #reset_shade method!

indigo = Colir.indigo
indigo.lighten
indigo.lighten
indigo.lighten
indigo.lighten
indigo.lighten
indigo.shades #=> 5
indigo.reset_shade #=> #<Colir:...>
indigo.shade #=> 0

Limitations

OS support

Colir is a cross-platform library.

Rubies

Ruby 1.9.3 and higher
Rubinius 2.0.0rc1 and higher (mode 1.9 and higher)

Initially I wanted to support JRuby 1.7.3 (mode 1.9), but it has a critical bug in BigDecimal library, which Colir actively utilises.

Credits

The first contributor badge goes to kachick

Licence

The project uses Zlib licence. See LICENCE file for more information.

colir

Development