=Optics::ANSI
* by Mike Zazaian
* http://optics-ansi.rubyforge.org
== DESCRIPTION:
The most flexible, syntactically elegant library for the colorization
of text in ANSI terminals. Has more options and better support for
adding effects to entire areas than the Rainbow gem, and with a more
elegant syntax than the ssoroka-ansi gem.
== FEATURES/PROBLEMS:
* Adds colors and text effects to instances of the String object.
* Allows user to toggle colors and effects for all text in the
terminal through the Optics module.
== SYNOPSIS:
=== Optics::ANSI String methods
==== Font Color
If you want to apply effects to the text only in a single string,
then you can access the Optics::ANSI methods included in the
String class, like this:
"this will be blue".dark(:blue)
"this will be blue".color(:blue) # alias
"this will be blue".dark_color(:blue) # alias
or, if you want a nice, lighter color:
"this will be yellow".light(:yellow)
"this will be yellow".light_color(:yellow) # alias
"this will be yellow".pale(:yellow) # alias
Optics supports all of the standard ANSI colors :
:black
:red
:green
:yellow
:blue
:magenta
:cyan
:white
:default
==== Background Color
Works just like the text color methods. To call a dark background:
"this has a dark cyan background".dark_bg(:cyan)
And a light one:
"this has a light magenta background".light_bg(:magenta)
==== Effects
There are also a number of methods that Optics::ANSI includes in the
String class for adding other effects. For the most part, they're all
pretty self-explanatory:
# Bold
"this will be bold".bold
"this will be bold".bright # alias
# Italic
"this will be italicized".italic
"this will be italicized".italics # alias
"this will be italicized".italicize # alias
# Underline
"this will be underlined".underline
# Blink: makes the text blink
"this will blink".blink
# Inverse: swaps the text and background colors
"this will appear inverted".inverse
"this will appear inverted".invert #alias
# Conceal: hides the text
"you won't be able to see this".conceal
"you won't be able to see this".hide # alias
Dark colors will always be converted to their lighter variant when
the bold or bright methods are applied.
==== Stacking effects and colors
You can also stack effects on a string. This will print text to the
terminal in a bolded, light blue font with an underline:
puts "this will be very pretty".light(:blue).bold.underline
or
puts "this will also be pretty".dark(:green).light_bg(:green).italics.blink
==== A note on 'puts'
If you're testing this in irb, all of the methods above will only
return the encoded string. To actually see the effects, you'll need
to print them to the terminal like this:
puts "this actually looks pretty".color(:white).light_bg(:yellow).bright
=== Methods in the Optics module
Calling these effects directly from the Optics module works exactly
as it does on String objects, but with a few exceptions, being:
* When you call a method from the Optics module, it doesn't close
itself.
* Some methods in the Optics module take blocks {}.
* There are more aliases available for colors.
* There are methods for cancelling colors or effects:
* Optics.cancel
* Optics.normal
* Optics.no_underline
* Optics.blink_off
* Optics.reveal
==== Optics.color
The Optics.color methods initialize the use of a color in the
terminal until cancelled or overwritten. This code will make
everything in the terminal dark blue until Optics.cancel is called:
puts Optics.dark(:blue)
The Optics module also has method aliases for each color, so all of
following are valid ways to call Optics.dark(:blue):
puts Optics.blue # alias
puts Optics.dk_blue # alias
puts Optics.dark_blue # alias
The lighter variant of blue can be initialized with:
puts Optics.light(:blue)
puts Optics.lt_blue # alias
puts Optics.light_blue # alias
Background colors can be initialized with:
puts Optics.dark_bg(:yellow)
puts Optics.light_bg(:red)
When you want things to stop being blue, you can reset them with:
puts Optics.reset
or:
puts Optics.cancel
Note that these will also cancel ALL other effects that have been
activated in the terminal, including bolding, underline and italics.
==== Optics.color "string"
The base, non-alias Optics.color methods can also take blocks in
order to act like the "string".color methods.
For example, this will print a green "snaaaaaaaaaaaaaaake" in the terminal:
puts Optics.light(:green) { "snnaaaaaaaaaaaake" }
This will also work with:
puts Optics.dark(:green) { "snnaaaaaaaaaaaaake" }
puts Optics.dark_bg(:green) { "snnaaaaaaaaaaaaake" }
puts Optics.light_bg(:green) { "snnaaaaaaaaaaaaake" }
But because none of the aliases can take blocks, the following
examples WILL NOT WORK:
puts Optics.dark_green { "snaaaaaaaaaaake" }
puts Optics.light_yellow { "canary" }
puts Optics.black { "crow" }
However, because these { blocks } call the Optics.reset method to
stop the color at the end of the word, calling one of these WILL
ALSO CANCEL ALL OTHER EFFECTS IN THE TERMINAL.
==== Optics.effects
Because effects called by Optics.effects don't automatically close
themselves, they're a little more flexible.
You can, for example, turn on an underline (in addition to any
existing colors or effects), then turn it off later without
cancelling the other active effects, like this:
puts Optics.underline
Then, to turn it back off:
puts Optics.no_underline.
The following pairs work in the same way:
*# Blink*
puts Optics.blink
*# No Blink*
puts Optics.blink_off
puts Optics.no_blink # alias
*# Bright*
puts Optics.bright
puts Optics.bold # alias
*# No Bright*
puts Optics.normal
puts Optics.normalize # alias
puts Optics.unbold # alias
*# Conceal*
puts Optics.conceal
puts Optics.hide # alias
*# No Conceal (Reveal)*
puts Optics.reveal
puts Optics.unhide # alias
There are also a couple of Optics methods that don't have their own
closing methods, and can only be cleared with Optics.reset:
# Italic
Optics.italic
Optics.italics # alias
Optics.italicize # alias
# Inverse
Optics.inverse
Optics.invert # alias
== REQUIREMENTS:
You must have rubygems installed to use Optics as a gem. To install
Rubygems on a debian or ubuntu linux system, do:
sudo aptitude update && sudo aptitude install rubygems
== INSTALL:
=== As a Rubygem
sudo gem install --remote optics-ansi
Then, add Optics to your script with:
require 'rubygems'
require 'optics'
=== Directly into your script
If you want to include Optics directly into your script, you can
download Optics as a .tgz or .zip package from the Optics homepage at:
http://optics-ansi.rubygems.org
Once you have the package, add Optics to your script's directory, add
the optics directory to your $LOAD_PATH variable...
$LOAD_PATH << "./optics"
.. and require Optics at the top of your script:
require 'optics'
== LICENSE:
(The MIT License)
Copyright (c) 2009 Mike Zazaian
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
* by Mike Zazaian
* http://optics-ansi.rubyforge.org
== DESCRIPTION:
The most flexible, syntactically elegant library for the colorization
of text in ANSI terminals. Has more options and better support for
adding effects to entire areas than the Rainbow gem, and with a more
elegant syntax than the ssoroka-ansi gem.
== FEATURES/PROBLEMS:
* Adds colors and text effects to instances of the String object.
* Allows user to toggle colors and effects for all text in the
terminal through the Optics module.
== SYNOPSIS:
=== Optics::ANSI String methods
==== Font Color
If you want to apply effects to the text only in a single string,
then you can access the Optics::ANSI methods included in the
String class, like this:
"this will be blue".dark(:blue)
"this will be blue".color(:blue) # alias
"this will be blue".dark_color(:blue) # alias
or, if you want a nice, lighter color:
"this will be yellow".light(:yellow)
"this will be yellow".light_color(:yellow) # alias
"this will be yellow".pale(:yellow) # alias
Optics supports all of the standard ANSI colors :
:black
:red
:green
:yellow
:blue
:magenta
:cyan
:white
:default
==== Background Color
Works just like the text color methods. To call a dark background:
"this has a dark cyan background".dark_bg(:cyan)
And a light one:
"this has a light magenta background".light_bg(:magenta)
==== Effects
There are also a number of methods that Optics::ANSI includes in the
String class for adding other effects. For the most part, they're all
pretty self-explanatory:
# Bold
"this will be bold".bold
"this will be bold".bright # alias
# Italic
"this will be italicized".italic
"this will be italicized".italics # alias
"this will be italicized".italicize # alias
# Underline
"this will be underlined".underline
# Blink: makes the text blink
"this will blink".blink
# Inverse: swaps the text and background colors
"this will appear inverted".inverse
"this will appear inverted".invert #alias
# Conceal: hides the text
"you won't be able to see this".conceal
"you won't be able to see this".hide # alias
Dark colors will always be converted to their lighter variant when
the bold or bright methods are applied.
==== Stacking effects and colors
You can also stack effects on a string. This will print text to the
terminal in a bolded, light blue font with an underline:
puts "this will be very pretty".light(:blue).bold.underline
or
puts "this will also be pretty".dark(:green).light_bg(:green).italics.blink
==== A note on 'puts'
If you're testing this in irb, all of the methods above will only
return the encoded string. To actually see the effects, you'll need
to print them to the terminal like this:
puts "this actually looks pretty".color(:white).light_bg(:yellow).bright
=== Methods in the Optics module
Calling these effects directly from the Optics module works exactly
as it does on String objects, but with a few exceptions, being:
* When you call a method from the Optics module, it doesn't close
itself.
* Some methods in the Optics module take blocks {}.
* There are more aliases available for colors.
* There are methods for cancelling colors or effects:
* Optics.cancel
* Optics.normal
* Optics.no_underline
* Optics.blink_off
* Optics.reveal
==== Optics.color
The Optics.color methods initialize the use of a color in the
terminal until cancelled or overwritten. This code will make
everything in the terminal dark blue until Optics.cancel is called:
puts Optics.dark(:blue)
The Optics module also has method aliases for each color, so all of
following are valid ways to call Optics.dark(:blue):
puts Optics.blue # alias
puts Optics.dk_blue # alias
puts Optics.dark_blue # alias
The lighter variant of blue can be initialized with:
puts Optics.light(:blue)
puts Optics.lt_blue # alias
puts Optics.light_blue # alias
Background colors can be initialized with:
puts Optics.dark_bg(:yellow)
puts Optics.light_bg(:red)
When you want things to stop being blue, you can reset them with:
puts Optics.reset
or:
puts Optics.cancel
Note that these will also cancel ALL other effects that have been
activated in the terminal, including bolding, underline and italics.
==== Optics.color "string"
The base, non-alias Optics.color methods can also take blocks in
order to act like the "string".color methods.
For example, this will print a green "snaaaaaaaaaaaaaaake" in the terminal:
puts Optics.light(:green) { "snnaaaaaaaaaaaake" }
This will also work with:
puts Optics.dark(:green) { "snnaaaaaaaaaaaaake" }
puts Optics.dark_bg(:green) { "snnaaaaaaaaaaaaake" }
puts Optics.light_bg(:green) { "snnaaaaaaaaaaaaake" }
But because none of the aliases can take blocks, the following
examples WILL NOT WORK:
puts Optics.dark_green { "snaaaaaaaaaaake" }
puts Optics.light_yellow { "canary" }
puts Optics.black { "crow" }
However, because these { blocks } call the Optics.reset method to
stop the color at the end of the word, calling one of these WILL
ALSO CANCEL ALL OTHER EFFECTS IN THE TERMINAL.
==== Optics.effects
Because effects called by Optics.effects don't automatically close
themselves, they're a little more flexible.
You can, for example, turn on an underline (in addition to any
existing colors or effects), then turn it off later without
cancelling the other active effects, like this:
puts Optics.underline
Then, to turn it back off:
puts Optics.no_underline.
The following pairs work in the same way:
*# Blink*
puts Optics.blink
*# No Blink*
puts Optics.blink_off
puts Optics.no_blink # alias
*# Bright*
puts Optics.bright
puts Optics.bold # alias
*# No Bright*
puts Optics.normal
puts Optics.normalize # alias
puts Optics.unbold # alias
*# Conceal*
puts Optics.conceal
puts Optics.hide # alias
*# No Conceal (Reveal)*
puts Optics.reveal
puts Optics.unhide # alias
There are also a couple of Optics methods that don't have their own
closing methods, and can only be cleared with Optics.reset:
# Italic
Optics.italic
Optics.italics # alias
Optics.italicize # alias
# Inverse
Optics.inverse
Optics.invert # alias
== REQUIREMENTS:
You must have rubygems installed to use Optics as a gem. To install
Rubygems on a debian or ubuntu linux system, do:
sudo aptitude update && sudo aptitude install rubygems
== INSTALL:
=== As a Rubygem
sudo gem install --remote optics-ansi
Then, add Optics to your script with:
require 'rubygems'
require 'optics'
=== Directly into your script
If you want to include Optics directly into your script, you can
download Optics as a .tgz or .zip package from the Optics homepage at:
http://optics-ansi.rubygems.org
Once you have the package, add Optics to your script's directory, add
the optics directory to your $LOAD_PATH variable...
$LOAD_PATH << "./optics"
.. and require Optics at the top of your script:
require 'optics'
== LICENSE:
(The MIT License)
Copyright (c) 2009 Mike Zazaian
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.