README.md in pastel-0.4.0 vs README.md in pastel-0.5.0
- old
+ new
@@ -1,15 +1,20 @@
+<div align="center">
+ <img width="215" src="https://cdn.rawgit.com/peter-murach/pastel/master/assets/pastel_logo.png" alt="pastel logo" />
+</div>
# Pastel
-[][gem]
-[][travis]
-[][codeclimate]
-[][coverage]
+[][gem]
+[][travis]
+[][codeclimate]
+[][coverage]
+[][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
+[inchpages]: http://inch-ci.org/github/peter-murach/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.
@@ -21,10 +26,11 @@
* 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:
@@ -47,23 +53,25 @@
* [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 Enabled?](#27-enabled)
- * [2.8 Alias Color](#28-alias-color)
+ * [2.7 Colored?](#27-colored)
+ * [2.8 Enabled?](#28-enabled)
+ * [2.9 Eachline](#29-eachline)
+ * [2.10 Alias Color](#30-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
-puts pastel.red('Unicorns!')
+pastel.red('Unicorns!')
```
You can compose multiple styles through chainable API:
```ruby
@@ -102,10 +110,16 @@
yellow('the world!')
}
}
```
+When dealing with multiline strings you can set `eachline` option(more info see [eachline](#29-eachline)):
+
+```
+pastel = Pastel.new(eachline: "\n")
+```
+
You can also predefine needed styles and reuse them:
```ruby
error = pastel.red.on_bold.detach
warning = pastel.yellow.detach
@@ -116,27 +130,29 @@
## 2 Interface
### 2.1 Color
-You can pass variable number of styled strings like so:
+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.
+
```ruby
pastel.red('Unicorns ', pastel.bold.underline('everywhere'), '!')
```
Please refer to [3. Supported Colors](#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 and any number of attributes, and returns string wrapped in styles.
+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.
```ruby
pastel.decorate('Unicorn', :green, :on_blue, :bold)
```
-This method will be useful in situations where colors are provided as a list of parameters.
+This method will be useful in situations where colors are provided as a list of parameters that have been generated dynamically.
### 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.
@@ -146,11 +162,11 @@
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.
+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"
```
@@ -169,12 +185,20 @@
```ruby
pastel.valid?(:red, :blue) # => true
pastel.valid?(:unicorn) # => false
```
-### 2.7 Enabled?
+### 2.7 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?
+
In order to detect if your terminal supports coloring do:
```ruby
pastel.enabled? # => false
```
@@ -184,12 +208,21 @@
```ruby
pastel = Pastel.new(enabled: true)
pastel.enabled? # => false
```
-### 2.8 Alias Color
+### 2.9 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
+
In order to setup an alias for the standard color do:
```ruby
pastel.alias_color(:funky, :red)
```
@@ -281,6 +314,6 @@
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request
## Copyright
-Copyright (c) 2014 Piotr Murach. See LICENSE for further details.
+Copyright (c) 2014-2015 Piotr Murach. See LICENSE for further details.