Awesome
<div align="center"> <img width="215" src="https://cdn.rawgit.com/piotrmurach/pastel/master/assets/pastel_logo.png" alt="pastel logo" /> </div>Pastel
Terminal output styling with intuitive and clean API that doesn't monkey patch String class.
Pastel is minimal and focused to work in all terminal emulators.
Pastel provides independent coloring component for TTY toolkit.
Features
- Doesn't monkey patch
String
- Intuitive and expressive API
- Minimal and focused to work on all terminal emulators
- Auto-detection of color support
- Allows nested styles
- Performant
Installation
Add this line to your application's Gemfile:
gem "pastel"
And then execute:
$ bundle
Or install it yourself as:
$ gem install pastel
Contents
1 Usage
Pastel provides a simple, minimal and intuitive API for styling your strings:
pastel = Pastel.new
puts pastel.red("Unicorns!")
Pastel doesn't print the colored string out, just returns it, you'll have to print it yourself.
You can compose multiple styles through chainable API:
pastel.red.on_green.bold("Unicorns!")
It allows you to combine styled strings with unstyled ones:
pastel.red("Unicorns") + " will rule " + pastel.green("the World!")
It supports variable number of arguments:
pastel.red("Unicorns", "are", "running", "everywhere!")
You can also nest styles as follows:
pastel.red("Unicorns ", pastel.on_green("everywhere!"))
Nesting is smart enough to know where one color ends and another one starts:
pastel.red("Unicorns " + pastel.green("everywhere") + pastel.on_yellow("!"))
You can also nest styles inside blocks:
pastel.red.on_green("Unicorns") {
green.on_red("will ", "dominate") {
yellow("the world!")
}
}
When dealing with multiline strings you can set eachline
option(more info see eachline):
pastel = Pastel.new(eachline: "\n")
You can also predefine needed styles and reuse them:
error = pastel.red.bold.detach
warning = pastel.yellow.detach
puts error.("Error!")
puts warning.("Warning")
If your output is redirected to a file, you probably don't want Pastel to add color to your text. See https://github.com/piotrmurach/pastel#210-enabled for a way to easily accomplish this.
Pastel has companion library called pastel-cli
that allows you to style text in terminal via pastel
executable:
$ pastel green "Unicorns & rainbows!"
2 Interface
2.1 Color
pastel.<color>[.<color>...](string, [string...])
Color styles are invoked as method calls with a string argument. A given color can take any number of strings as arguments. Then it returns a colored string which isn't printed out to terminal. You need to print it yourself if you need to. This is done so that you can save it as a string, pass to something else, send it to a file handle and so on.
pastel.red("Unicorns ", pastel.bold.underline("everywhere"), "!")
Please refer to 3. Supported Colors section for full list of supported styles.
2.2 Decorate
This method is a lower level string styling call that takes as the first argument the string to style followed by any number of color attributes, and returns string wrapped in styles.
pastel.decorate("Unicorn", :green, :on_blue, :bold)
This method will be useful in situations where colors are provided as a list of parameters that have been generated dynamically.
2.3 Undecorate
It performs the opposite to decorate
method by turning color escape sequences found in the string into a list of hash objects corresponding with the attribute names set by those sequences. Depending on the parsed string, each hash object may contain :foreground
, :background
, :text
and/or :style
keys.
pastel.undecorate("\e[32mfoo\e[0m \e[31mbar\e[0m")
# => [{foreground: :green, text: "foo"}, {text: " "}, {foreground: :red, text: "bar"}]
To translate the color name into sequence use lookup
2.4 Detach
The detach
method allows to keep all the associated colors with the detached instance for later reference. This method is useful when detached colors are being reused frequently and thus shorthand version is preferred. The detached object can be invoked using call
method or it's shorthand .()
, as well as array like access []
. For example, the following are equivalent examples of detaching colors:
notice = pastel.blue.bold.detach
notice.call("Unicorns running")
notice.("Unicorns running")
notice["Unicorns running"]
2.5 Strip
Strip only color sequence characters from the provided strings and preserve any movement codes or other escape sequences. The return value will be either array of modified strings or a single string. The arguments are not modified.
pastel.strip("\e[1A\e[1m\e[34mbold blue text\e[0m") # => "\e[1Abold blue text"
2.6 Styles
To get a full list of supported styles with the corresponding color codes do:
pastel.styles
2.7 Lookup
To perform translation of color name into ansi escape code use lookup
:
pastel.lookup(:red) # => "\e[31m"
pastel.lookup(:reset) # => "\e[0m"
2.8 Valid?
Determine whether a color or a list of colors are valid. valid?
takes one or more attribute strings or symbols and returns true if all attributes are known and false otherwise.
pastel.valid?(:red, :blue) # => true
pastel.valid?(:unicorn) # => false
2.9 Colored?
In order to determine if string has color escape codes use colored?
like so
pastel.colored?("\e[31mcolorful\e[0m") # => true
2.10 Enabled?
In order to detect if your terminal supports coloring do:
pastel.enabled? # => false
In cases when the color support is not provided no styling will be applied to the colored string. Moreover, you can force Pastel to always print out string with coloring switched on:
pastel = Pastel.new(enabled: true)
pastel.enabled? # => true
If you are outputting to stdout or stderr, and want to suppress color if output is redirected to a file, you can set the enabled attribute dynamically, as in:
stdout_pastel = Pastel.new(enabled: $stdout.tty?)
stderr_pastel = Pastel.new(enabled: $stderr.tty?)
2.11 Eachline
Normally Pastel colors string by putting color codes at the beginning and end of the string, but if you provide eachline
option set to some string, that string will be considered the line delimiter. Consequently, each line will be separately colored with escape sequence and reset code at the end. This option is desirable if the output string contains newlines and you're using background colors. Since color code that spans more than one line is often interpreted by terminal as providing background for all the lines that follow. This in turn may cause programs such as pagers to spill the colors throughout the text. In most cases you will want to set eachline
to \n
character like so:
pastel = Pastel.new(eachline: "\n")
pastel.red("foo\nbar") # => "\e[31mfoo\e[0m\n\e[31mbar\e[0m"
2.12 Alias Color
In order to setup an alias for standard colors do:
pastel.alias_color(:funky, :red, :bold)
From that point forward, :funky
alias can be passed to decorate
, valid?
with the same meaning as standard colors:
pastel.funky.on_green("unicorn") # => will use :red, :bold color
This method allows you to give more meaningful names to existing colors.
You can also use the PASTEL_COLORS_ALIASES
environment variable (see Environment) to specify aliases.
Note: Aliases are global and affect all callers in the same process.
3 Supported Colors
Pastel works with terminal emulators that support minimum sixteen colors. It provides 16
basic colors and 8
styles with further 16
bright color pairs. The corresponding bright color is obtained by prepending the bright
to the normal color name. For example, color red
will have bright_red
as its pair.
The variant with on_
prefix will style the text background color.
The foreground colors:
black
red
green
yellow
blue
magenta
cyan
white
bright_black
bright_red
bright_green
bright_yellow
bright_blue
bright_magenta
bright_cyan
bright_white
The background colors:
on_black
on_red
on_green
on_yellow
on_blue
on_magenta
on_cyan
on_white
on_bright_black
on_bright_red
on_bright_green
on_bright_yellow
on_bright_blue
on_bright_magenta
on_bright_cyan
on_bright_white
Generic styles:
clear
bold
dim
italic
underline
inverse
hidden
strikethrough
4 Environment
4.1 PASTEL_COLORS_ALIASES
This environment variable allows you to specify custom color aliases at runtime that will be understood by Pastel. The environment variable is read and used when the instance of Pastel is created. You can also use alias_color
to create aliases.
Only alphanumeric and _
and .
are allowed in the alias names with the following format:
PASTEL_COLORS_ALIASES="newcolor_1=red,newcolor_2=on_green,funky=red.bold"
5. Command line
You can also install pastel-cli to use pastel
executable in terminal:
$ pastel green 'Unicorns & rainbows!'
Contributing
- Fork it ( https://github.com/piotrmurach/pastel/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
Code of Conduct
Everyone interacting in the Pastel project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.
Copyright
Copyright (c) 2014 Piotr Murach. See LICENSE for further details.