README.md in pastel-0.3.0 vs README.md in pastel-0.4.0
- old
+ new
@@ -1,15 +1,17 @@
# Pastel
[][gem]
[][travis]
[][codeclimate]
+[][coverage]
[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
-Terminal output styling with intuitive and clean API that doesn't monkey patch String class.
+> 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.
@@ -41,38 +43,39 @@
* [1. Usage](#1-usage)
* [2. Interface](#2-interface)
* [2.1 Color](#21-color)
* [2.2 Decorate](#22-decorate)
- * [2.3 Strip](#23-strip)
- * [2.4 Styles](#24-styles)
- * [2.5 Valid?](#25-valid)
- * [2.6 Enabled?](#26-enabled)
- * [2.7 Alias Color](#27-alias-color)
+ * [2.3 Detach](#23-detach)
+ * [2.4 Strip](#24-strip)
+ * [2.5 Styles](#25-styles)
+ * [2.6 Valid?](#26-valid)
+ * [2.7 Enabled?](#27-enabled)
+ * [2.8 Alias Color](#28-alias-color)
* [3. Supported Colors](#3-supported-colors)
* [4. Environment](#4-environment)
## 1 Usage
**Pastel** provides a simple, minimal and intuitive API for styling your strings:
```ruby
pastel = Pastel.new
-pastel.red('Unicorns!')
+puts pastel.red('Unicorns!')
```
-It allows you to combine styled strings with regular ones:
+You can compose multiple styles through chainable API:
```ruby
-pastel.red('Unicorns') + ' will rule ' + pastel.green('the World!')
+pastel.red.on_green.bold('Unicorns!')
```
-You can compose multiple styles through chainable API:
+It allows you to combine styled strings with unstyled ones:
```ruby
-pastel.red.on_green.bold('Unicorns!')
+pastel.red('Unicorns') + ' will rule ' + pastel.green('the World!')
```
It supports variable number of arguments:
```ruby
@@ -83,10 +86,36 @@
```ruby
pastel.red('Unicorns ', pastel.on_green('everywhere!'))
```
+Nesting is smart enough to know where one color ends and another one starts:
+
+```ruby
+pastel.red('Unicorns ' + pastel.green('everywhere') + pastel.on_yellow('!'))
+```
+
+You can also nest styles inside blocks:
+
+```ruby
+pastel.red.on_green('Unicorns') {
+ green.on_red('will ', 'dominate') {
+ yellow('the world!')
+ }
+}
+```
+
+You can also predefine needed styles and reuse them:
+
+```ruby
+error = pastel.red.on_bold.detach
+warning = pastel.yellow.detach
+
+puts error('Error!')
+puts warning('Warning')
+```
+
## 2 Interface
### 2.1 Color
You can pass variable number of styled strings like so:
@@ -105,36 +134,46 @@
pastel.decorate('Unicorn', :green, :on_blue, :bold)
```
This method will be useful in situations where colors are provided as a list of parameters.
-### 2.3 Strip
+### 2.3 Detach
+The `detach` method allows to keep all the coloring for later reference. This method is useful when detached colors are being resued frequently and thus shorthand version is preferred.
+
+```ruby
+notice = pastel.blue.bold.detach
+puts notice.call('Unicorns running')
+puts notice.call('They are super wild')
+```
+
+### 2.4 Strip
+
Strip all color sequence characters from the provided strings. The return value will be eithre 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[1m\e[34mbold blue text\e[0m") # => "bold blue text"
```
-### 2.4 Styles
+### 2.5 Styles
To get a full list of supported styles with the corresponding color codes do:
```ruby
pastel.styles
```
-### 2.5 Valid?
+### 2.6 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.6 Enabled?
+### 2.7 Enabled?
In order to detect if your terminal supports coloring do:
```ruby
pastel.enabled? # => false
@@ -145,11 +184,11 @@
```ruby
pastel = Pastel.new(enabled: true)
pastel.enabled? # => false
```
-### 2.7 Alias Color
+### 2.8 Alias Color
In order to setup an alias for the standard color do:
```ruby
pastel.alias_color(:funky, :red)
@@ -229,10 +268,10 @@
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 `_` are allowed in the alias names with the following format:
```ruby
-PASTEL_COLORS_ALIASES='newcolor_1=red,newcolor_2=on_gree'
+PASTEL_COLORS_ALIASES='newcolor_1=red,newcolor_2=on_green'
```
## Contributing
1. Fork it ( https://github.com/peter-murach/pastel/fork )