README.md in pastel-0.5.3 vs README.md in pastel-0.6.0
- old
+ new
@@ -4,11 +4,11 @@
# Pastel
[][gem]
[][travis]
[][codeclimate]
[][coverage]
-[][inchpages]
+[][inchpages]
[gem]: http://badge.fury.io/rb/pastel
[travis]: http://travis-ci.org/peter-murach/pastel
[codeclimate]: https://codeclimate.com/github/peter-murach/pastel
[coverage]: https://coveralls.io/r/peter-murach/pastel
@@ -49,20 +49,23 @@
* [1. Usage](#1-usage)
* [2. Interface](#2-interface)
* [2.1 Color](#21-color)
* [2.2 Decorate](#22-decorate)
- * [2.3 Detach](#23-detach)
- * [2.4 Strip](#24-strip)
- * [2.5 Styles](#25-styles)
- * [2.6 Valid?](#26-valid)
- * [2.7 Colored?](#27-colored)
- * [2.8 Enabled?](#28-enabled)
- * [2.9 Eachline](#29-eachline)
- * [2.10 Alias Color](#30-alias-color)
+ * [2.3 Undecorate](#23-undecorate)
+ * [2.4 Detach](#24-detach)
+ * [2.5 Strip](#25-strip)
+ * [2.6 Styles](#26-styles)
+ * [2.7 Lookup](#27-lookup)
+ * [2.8 Valid?](#28-valid)
+ * [2.9 Colored?](#29-colored)
+ * [2.10 Enabled?](#30-enabled)
+ * [2.11 Eachline](#211-eachline)
+ * [2.12 Alias Color](#212-alias-color)
* [3. Supported Colors](#3-supported-colors)
* [4. Environment](#4-environment)
+* [5. Command line](#5-command-line)
## 1 Usage
**Pastel** provides a simple, minimal and intuitive API for styling your strings:
@@ -128,10 +131,16 @@
puts error.('Error!')
puts warning.('Warning')
```
+**Pastel** has companion library called `pastel-cli` that allows you to style text in terminal via `pastel` executable:
+
+```bash
+$ pastel green 'Unicorns & rainbows!'
+```
+
## 2 Interface
### 2.1 Color
pastel.`<color>[.<color>...](string, [string...])`
@@ -152,56 +161,75 @@
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 Detach
+### 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.
+
+```ruby
+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](#27-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:
```ruby
notice = pastel.blue.bold.detach
notice.call('Unicorns running')
notice.('Unicorns running')
notice['Unicorns running']
```
-### 2.4 Strip
+### 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.
```ruby
-pastel.strip("\e[1m\e[34mbold blue text\e[0m") # => "bold blue text"
+pastel.strip("\e[1A\e[1m\e[34mbold blue text\e[0m") # => "\e[1Abold blue text"
```
-### 2.5 Styles
+### 2.6 Styles
To get a full list of supported styles with the corresponding color codes do:
```ruby
pastel.styles
```
-### 2.6 Valid?
+### 2.7 Lookup
+To perform translation of color name into ansi escape code use `lookup`:
+
+```ruby
+color.lookup(:red) # => "\e[31m"
+```
+
+### 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.
```ruby
pastel.valid?(:red, :blue) # => true
pastel.valid?(:unicorn) # => false
```
-### 2.7 Colored?
+### 2.9 Colored?
In order to determine if string has color escape codes use `colored?` like so
```ruby
pastel.colored?("\e[31mcolorful\e[0m") # => true
```
-### 2.8 Enabled?
+### 2.10 Enabled?
In order to detect if your terminal supports coloring do:
```ruby
pastel.enabled? # => false
@@ -212,20 +240,20 @@
```ruby
pastel = Pastel.new(enabled: true)
pastel.enabled? # => true
```
-### 2.9 Eachline
+### 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:
```ruby
pastel = Pastel.new(eachline: "\n")
pastel.red("foo\nbar") # => "\e[31mfoo\e[0m\n\e[31mbar\e[0m"
```
-### 2.10 Alias Color
+### 2.12 Alias Color
In order to setup an alias for the standard color do:
```ruby
pastel.alias_color(:funky, :red)
@@ -308,16 +336,24 @@
```ruby
PASTEL_COLORS_ALIASES='newcolor_1=red,newcolor_2=on_green'
```
+## 5. Command line
+
+You can also install [pastel-cli](https://github.com/peter-murach/pastel-cli) to use `pastel` executable in terminal:
+
+```bash
+$ pastel green 'Unicorns & rainbows!'
+```
+
## Contributing
1. Fork it ( https://github.com/peter-murach/pastel/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request
## Copyright
-Copyright (c) 2014-2015 Piotr Murach. See LICENSE for further details.
+Copyright (c) 2014-2016 Piotr Murach. See LICENSE for further details.