col 1.0.1a → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- data/.gitignore +4 -0
- data/Gemfile +4 -0
- data/History.txt +10 -0
- data/{README → README.txt} +1 -1
- data/Rakefile +1 -0
- data/col.gemspec +32 -0
- data/doc/col.markdown +362 -0
- data/etc/at +4 -0
- data/etc/build_install_gem.sh +2 -0
- data/etc/test-no-string-extension.rb +11 -0
- data/lib/col.rb +1 -2
- data/lib/col/version.rb +3 -0
- metadata +38 -15
data/.gitignore
ADDED
data/Gemfile
ADDED
data/History.txt
ADDED
data/{README → README.txt}
RENAMED
@@ -4,7 +4,7 @@ If you want a dash of color in your Ruby console program, use Term::ANSIColor.
|
|
4
4
|
If your color formatting requirements are more complicated, use Col.
|
5
5
|
Col provides as much convenience as possible without modifying builtin classes.
|
6
6
|
|
7
|
-
|
7
|
+
=== SYNOPSIS
|
8
8
|
|
9
9
|
require 'col'
|
10
10
|
|
data/Rakefile
ADDED
@@ -0,0 +1 @@
|
|
1
|
+
require "bundler/gem_tasks"
|
data/col.gemspec
ADDED
@@ -0,0 +1,32 @@
|
|
1
|
+
# -*- encoding: utf-8 -*-
|
2
|
+
$:.push File.expand_path("../lib", __FILE__)
|
3
|
+
require "col/version"
|
4
|
+
|
5
|
+
Gem::Specification.new do |s|
|
6
|
+
s.name = "col"
|
7
|
+
s.version = Col::VERSION
|
8
|
+
s.authors = ["Gavin Sinclair"]
|
9
|
+
s.email = ["gsinclair@gmail.com"]
|
10
|
+
s.homepage = "http://gsinclair.github.com/col.html"
|
11
|
+
s.summary = "High-level console color formatting"
|
12
|
+
s.description = <<-EOF
|
13
|
+
Console color formatting library with abbreviations (e.g. 'rb' for
|
14
|
+
red and bold), and the ability to format several strings easily.
|
15
|
+
No methods are added to core classes.
|
16
|
+
EOF
|
17
|
+
|
18
|
+
s.rubyforge_project = ""
|
19
|
+
s.has_rdoc = false
|
20
|
+
|
21
|
+
s.files = `git ls-files`.split("\n")
|
22
|
+
s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
|
23
|
+
s.executables = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
|
24
|
+
s.require_paths = ["lib"]
|
25
|
+
|
26
|
+
s.add_runtime_dependency "term-ansicolor", ">= 1.0"
|
27
|
+
|
28
|
+
#s.add_development_dependency "T"
|
29
|
+
s.add_development_dependency "bundler"
|
30
|
+
|
31
|
+
s.required_ruby_version = '>= 1.8.6' # Not sure about this.
|
32
|
+
end
|
data/doc/col.markdown
ADDED
@@ -0,0 +1,362 @@
|
|
1
|
+
---
|
2
|
+
layout: default
|
3
|
+
title: Col
|
4
|
+
---
|
5
|
+
|
6
|
+
# Col
|
7
|
+
|
8
|
+
* This list will contain the table of contents
|
9
|
+
{:toc}
|
10
|
+
|
11
|
+
## Name
|
12
|
+
|
13
|
+
Col -- high-level console color formatting
|
14
|
+
|
15
|
+
## Synopsis
|
16
|
+
|
17
|
+
{% highlight ruby %}
|
18
|
+
require 'col'
|
19
|
+
|
20
|
+
puts Col("Hello world!").red.bold
|
21
|
+
puts Col("Hello world!").rb
|
22
|
+
puts Col("Hello world!").fmt [:red, :bold]
|
23
|
+
puts Col("Hello world!").fmt :rb
|
24
|
+
|
25
|
+
puts Col("Hello ", "world!").fmt :red, :green
|
26
|
+
puts Col("Hello ", "world!").fmt "r,g"
|
27
|
+
|
28
|
+
puts Col("Hello ", "world!").fmt [:red, :bold], [:green, :bold]
|
29
|
+
puts Col("Hello ", "world!").fmt "rb,gb"
|
30
|
+
|
31
|
+
puts Col("Hello ", "world!").fmt [:bold], [:cyan, :italic, :on_white]
|
32
|
+
puts Col("Hello ", "world!").fmt "_b,ciow"
|
33
|
+
|
34
|
+
puts Col("Hello ", "world!").fmt [:blue, :on_yellow], [:on_green]
|
35
|
+
puts Col("Hello ", "world!").fmt "b_oy,__og"
|
36
|
+
|
37
|
+
puts Col.inline( "Hello ", :red, "world!", :blue )
|
38
|
+
|
39
|
+
puts Col.inline(
|
40
|
+
"Hello ", [:red, :bold, :on_white],
|
41
|
+
"world!", :b_oy
|
42
|
+
)
|
43
|
+
|
44
|
+
{% endhighlight %}
|
45
|
+
|
46
|
+
|
47
|
+
## Installation
|
48
|
+
|
49
|
+
$ [sudo] gem install col
|
50
|
+
|
51
|
+
Source-code access is via Github. See [Project details](#project_details).
|
52
|
+
|
53
|
+
## Description
|
54
|
+
|
55
|
+
Col offers high-level access to the ANSI codes used to create colorful output on
|
56
|
+
the console. It is optimised for dealing with multiple strings at once,
|
57
|
+
applying different color formatting to each string. It does not add any methods
|
58
|
+
to the String class.
|
59
|
+
|
60
|
+
For simple console-coloring requirements, there is little or nothing to be
|
61
|
+
gained from using Col instead of Term::ANSIColor.
|
62
|
+
|
63
|
+
If formatting a single string, you can send the method names directly, or use
|
64
|
+
their abbreviation if applicable:
|
65
|
+
|
66
|
+
{% highlight ruby %}
|
67
|
+
|
68
|
+
puts Col("Hello world!").red.bold.on_white
|
69
|
+
puts Col("Hello world!").rbow
|
70
|
+
|
71
|
+
puts Col("Hello world!").bold.italic.strikethrough
|
72
|
+
# No abbreviation for this
|
73
|
+
|
74
|
+
{% endhighlight %}
|
75
|
+
|
76
|
+
If formatting multiple strings, you are limited to using the `fmt` method.
|
77
|
+
|
78
|
+
{% highlight ruby %}
|
79
|
+
|
80
|
+
puts Col("Hello ", "world!").fmt [:red, :bold], [:green, :bold]
|
81
|
+
puts Col("Hello ", "world!").fmt :rb, :gb
|
82
|
+
puts Col("Hello ", "world!").fmt "rb,rg"
|
83
|
+
|
84
|
+
puts Col("Hello ", "world!").fmt [:italic, :underline], [:green, :on_white]
|
85
|
+
# No abbreviation for [:italic, :underline]
|
86
|
+
{% endhighlight %}
|
87
|
+
|
88
|
+
Abbreviations are available if the format you wish to use comprises:
|
89
|
+
* at most one foreground color
|
90
|
+
* at most one style
|
91
|
+
* at most one background color
|
92
|
+
|
93
|
+
See [Abbreviations](#abbreviations) below for details.
|
94
|
+
|
95
|
+
|
96
|
+
### Classes, methods, return values
|
97
|
+
|
98
|
+
`Col(...)` and `Col[...]` create a `Col` object, whose only interesting methods are
|
99
|
+
`fmt` (to apply formatting) and `to_s`. Any other method will be interpreted as
|
100
|
+
a format specifier.
|
101
|
+
|
102
|
+
`Col#fmt` returns a `String`:
|
103
|
+
|
104
|
+
{% highlight ruby %}
|
105
|
+
|
106
|
+
Col("string").fmt :red, :bold, :on_white # -> String
|
107
|
+
Col("string").fmt "rbow" # -> String
|
108
|
+
Col("string").fmt :rbow # -> String
|
109
|
+
Col("str1", "str2").fmt :rb, gi # -> String
|
110
|
+
|
111
|
+
{% endhighlight %}
|
112
|
+
|
113
|
+
Directly-applied formatting methods return a `Col` object:
|
114
|
+
|
115
|
+
{% highlight ruby %}
|
116
|
+
|
117
|
+
Col("string").red # -> Col
|
118
|
+
Col("string").red.bold # -> Col
|
119
|
+
Col("string").red.bold.underscore.italic # -> Col
|
120
|
+
|
121
|
+
{% endhighlight %}
|
122
|
+
|
123
|
+
Because `Col#to_s` is implemented, you can use `puts` directly on a `Col`
|
124
|
+
object:
|
125
|
+
|
126
|
+
{% highlight ruby %}
|
127
|
+
|
128
|
+
puts Col("string").red.bold
|
129
|
+
|
130
|
+
{% endhighlight %}
|
131
|
+
|
132
|
+
Directly-applied _abbreviated_ formatting methods return a `String`:
|
133
|
+
|
134
|
+
{% highlight ruby %}
|
135
|
+
|
136
|
+
Col("string").rbow # -> String
|
137
|
+
# internally converted to
|
138
|
+
# Col("string).fmt :red, :bold, :on_white
|
139
|
+
|
140
|
+
{% endhighlight %}
|
141
|
+
|
142
|
+
Incorrect use of Col results in a `Col::Error` being raised:
|
143
|
+
|
144
|
+
{% highlight ruby %}
|
145
|
+
|
146
|
+
Col("string").turquoise # non-existent format
|
147
|
+
Col("one", "two).fmt :red, :green, :cyan # too many arguments
|
148
|
+
Col("string").gZow # invalid style: Z
|
149
|
+
|
150
|
+
{% endhighlight %}
|
151
|
+
|
152
|
+
### Abbreviations
|
153
|
+
|
154
|
+
Here are some illustrative examples of abbreviations you can use with `col`.
|
155
|
+
|
156
|
+
Code Effect(s) applied
|
157
|
+
--------------- -------------------
|
158
|
+
Col["..."].g green
|
159
|
+
Col["..."].gb green bold
|
160
|
+
Col["..."]._b bold
|
161
|
+
Col["..."].gbow green bold on_white
|
162
|
+
Col["..."].g_ow green on_white
|
163
|
+
Col["..."].__ow on_white
|
164
|
+
|
165
|
+
These examples show that the abbreviations are positional. If you only want to
|
166
|
+
specify `on_white`, you must use underscores for the color and style properties.
|
167
|
+
|
168
|
+
Using these abbreviations, you can apply at most one color, at most one style,
|
169
|
+
and at most one background color. These are listed in full here:
|
170
|
+
|
171
|
+
{% highlight ruby %}
|
172
|
+
|
173
|
+
COLORS = { STYLES = { BACKGROUND = {
|
174
|
+
'B' => :black, 'b' => :bold, 'oB' => :on_black,
|
175
|
+
'r' => :red, 'd' => :dark, 'or' => :on_red,
|
176
|
+
'g' => :green, 'i' => :italic, 'og' => :on_green,
|
177
|
+
'y' => :yellow, 'u' => :underline, 'oy' => :on_yellow,
|
178
|
+
'b' => :blue, 'U' => :underscore, 'ob' => :on_blue,
|
179
|
+
'm' => :magenta, 'k' => :blink, 'om' => :on_magenta,
|
180
|
+
'c' => :cyan, 'r' => :rapid_blink, 'oc' => :on_cyan,
|
181
|
+
'w' => :white 'n' => :negative, 'ow' => :on_white
|
182
|
+
} 'c' => :concealed, }
|
183
|
+
's' => :strikethrough,
|
184
|
+
}
|
185
|
+
|
186
|
+
{% endhighlight %}
|
187
|
+
|
188
|
+
Note the following solutions to abbreviation clashes:
|
189
|
+
|
190
|
+
* `b` for blue, `B` for black
|
191
|
+
* `u` for underline, `U` for underscore
|
192
|
+
* `b` for bold; `k` for blink.
|
193
|
+
|
194
|
+
### Unabbreviated usage
|
195
|
+
|
196
|
+
Col is designed to make colorising a string (or collection of strings) easy, and
|
197
|
+
is optimised for the common case of applying a single color, a single style and
|
198
|
+
a background color. If you need to apply more than one style to a single
|
199
|
+
string, you can send them all as methods:
|
200
|
+
|
201
|
+
{% highlight ruby %}
|
202
|
+
|
203
|
+
Col("text...").rapid_blink.strikethrough.negative.cyan
|
204
|
+
|
205
|
+
{% endhighlight %}
|
206
|
+
|
207
|
+
Or you can pass all of them, in full, to the `fmt` method.
|
208
|
+
|
209
|
+
{% highlight ruby %}
|
210
|
+
|
211
|
+
Col("text...").fmt [:rapid_blink, :strikethrough, :negative, :cyan]
|
212
|
+
|
213
|
+
{% endhighlight %}
|
214
|
+
|
215
|
+
If you are using `Col` to format a number of strings, `fmt` is your only option.
|
216
|
+
|
217
|
+
{% highlight ruby %}
|
218
|
+
|
219
|
+
Col("one", "two", "three").fmt(
|
220
|
+
[:green, :bold, :underline, :italic, :on_yellow],
|
221
|
+
[:blue, :strikethrough, :dark, :blink],
|
222
|
+
[:red]
|
223
|
+
)
|
224
|
+
|
225
|
+
{% endhighlight %}
|
226
|
+
|
227
|
+
Naturally, the need for such usage should be extremely rare!
|
228
|
+
|
229
|
+
### Formatting multiple strings
|
230
|
+
|
231
|
+
Assuming your formatting needs are straightforward, the most convenient way to
|
232
|
+
format multiple strings is with a comma-separated format specification.
|
233
|
+
|
234
|
+
{% highlight ruby %}
|
235
|
+
|
236
|
+
puts Col(str1, str2, ...).fmt "f1,f2,..."
|
237
|
+
|
238
|
+
{% endhighlight %}
|
239
|
+
|
240
|
+
For example:
|
241
|
+
|
242
|
+
{% highlight ruby %}
|
243
|
+
|
244
|
+
puts Col("Name: ", name, "Age: ", age).fmt "y,rb,y,rb"
|
245
|
+
|
246
|
+
# Equivalent to:
|
247
|
+
puts Col("Name: ", name, "Age: ", age ).fmt \
|
248
|
+
:yellow, [:red, :bold], :yellow, [:red, :bold]
|
249
|
+
|
250
|
+
{% endhighlight %}
|
251
|
+
|
252
|
+
An alternative is to provide a list of strings or symbols:
|
253
|
+
|
254
|
+
{% highlight ruby %}
|
255
|
+
|
256
|
+
puts Col("Name: ", name, "Age: ", age).fmt('y', 'rb', 'y', 'rb')
|
257
|
+
puts Col("Name: ", name, "Age: ", age).fmt(:y, :rb, :y, :rb)
|
258
|
+
|
259
|
+
{% endhighlight %}
|
260
|
+
|
261
|
+
### Inline usage
|
262
|
+
|
263
|
+
An alternative way to format multiple strings is to use `Col.inline`.
|
264
|
+
|
265
|
+
{% highlight ruby %}
|
266
|
+
|
267
|
+
Col.inline( str1, fmt1, str2, fmt2, ... )
|
268
|
+
|
269
|
+
{% endhighlight %}
|
270
|
+
|
271
|
+
For example:
|
272
|
+
|
273
|
+
{% highlight ruby %}
|
274
|
+
|
275
|
+
puts Col.inline( "Hello ", :red, "world!", :blue)
|
276
|
+
|
277
|
+
puts Col.inline(
|
278
|
+
"Hello ", [:red, :bold, :on_white],
|
279
|
+
"world!", :b_oy
|
280
|
+
)
|
281
|
+
|
282
|
+
{% endhighlight %}
|
283
|
+
|
284
|
+
### Removing color codes from a string
|
285
|
+
|
286
|
+
`Col.uncolored` or `Col.plain` will remove any ANSI color codes from a string.
|
287
|
+
|
288
|
+
{% highlight ruby %}
|
289
|
+
|
290
|
+
str = Col["foo"].yellow.bold.on_red.to_s
|
291
|
+
Col.uncolored(str) == "foo" # true
|
292
|
+
|
293
|
+
{% endhighlight %}
|
294
|
+
|
295
|
+
### Windows users
|
296
|
+
|
297
|
+
People using a native Windows build of Ruby in the Windows console should
|
298
|
+
include the following code in their program:
|
299
|
+
|
300
|
+
{% highlight ruby %}
|
301
|
+
|
302
|
+
require 'win32console' # win32console gem
|
303
|
+
include Win32::Console::ANSI
|
304
|
+
|
305
|
+
{% endhighlight %}
|
306
|
+
|
307
|
+
This does not apply to Cygwin users.
|
308
|
+
|
309
|
+
## Limitations
|
310
|
+
|
311
|
+
Col uses [Term::ANSIColor][1] to access ANSI codes, and offers access to all of
|
312
|
+
its codes/features _except_ `reset`.
|
313
|
+
|
314
|
+
[1]: http://flori.github.com/term-ansicolor/
|
315
|
+
|
316
|
+
The author of this library never applies anything other than a foreground color
|
317
|
+
and 'bold', so everything else is tested only in unit tests, not in practice.
|
318
|
+
Furthermore, the author has no knowledge of terminal issues and is just happy to
|
319
|
+
see a few colors appear in his Ruby 1.8 and 1.9 (Cygwin) programs -- no other
|
320
|
+
environment has been tested!
|
321
|
+
|
322
|
+
|
323
|
+
## Endnotes
|
324
|
+
|
325
|
+
### History
|
326
|
+
|
327
|
+
January 1 2012: Version 1.0.1 released (minor bug fix for 1.9.3)
|
328
|
+
July 25 2010: Version 1.0 released.
|
329
|
+
|
330
|
+
### Credits
|
331
|
+
|
332
|
+
Florian Flank for [Term::ANSIColor][1], which I've used heavily over the years.
|
333
|
+
|
334
|
+
### Motivation
|
335
|
+
|
336
|
+
I've used Term::ANSIColor many times and never sought anything more, but while
|
337
|
+
developing Attest, which makes much use of console color, I wanted an easier way
|
338
|
+
to apply color codes to groups of strings. Additionally, being a unit testing
|
339
|
+
library, I didn't want to add methods to the String class, the way I normally do
|
340
|
+
when using Term::ANSIColor.
|
341
|
+
|
342
|
+
### Project details
|
343
|
+
|
344
|
+
* Author: Gavin Sinclair (user name: `gsinclair`; mail server: `gmail.com`)
|
345
|
+
* Date: July 2010
|
346
|
+
* Licence: MIT licence
|
347
|
+
* Project homepage: [http://gsinclair.github.com/col.html][home]
|
348
|
+
* Source code: [http://github.com/gsinclair/col][code]
|
349
|
+
* Documentation: [project homepage](home)
|
350
|
+
|
351
|
+
[home]: http://gsinclair.github.com/col.html
|
352
|
+
[code]: http://github.com/gsinclair/col
|
353
|
+
|
354
|
+
### Future plans
|
355
|
+
|
356
|
+
Version 1.0.0 was released with no plans for future releases. Version 1.0.1
|
357
|
+
fixed a bug (18 months later), and still there are no plans for further
|
358
|
+
functionality.
|
359
|
+
|
360
|
+
One possible area of enhancement is to provide a way of disabling colored output
|
361
|
+
when outputing to a pipe. (I believe Term::ANSIColor may already do that.)
|
362
|
+
(Sometimes, however, colored output in a pipe is desirable, viz. git.)
|
data/etc/at
ADDED
data/lib/col.rb
CHANGED
@@ -1,11 +1,10 @@
|
|
1
|
-
require 'rubygems'
|
2
1
|
require 'term/ansicolor'
|
2
|
+
require 'col/version'
|
3
3
|
|
4
4
|
# --------------------------------------------------------------------------- #
|
5
5
|
|
6
6
|
class Col
|
7
7
|
|
8
|
-
VERSION = "1.0.1a"
|
9
8
|
|
10
9
|
# args: array of strings (to_s is called on each)
|
11
10
|
def initialize(*args)
|
data/lib/col/version.rb
ADDED
metadata
CHANGED
@@ -1,19 +1,19 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: col
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 1.0.
|
5
|
-
prerelease:
|
4
|
+
version: 1.0.1
|
5
|
+
prerelease:
|
6
6
|
platform: ruby
|
7
7
|
authors:
|
8
8
|
- Gavin Sinclair
|
9
9
|
autorequire:
|
10
10
|
bindir: bin
|
11
11
|
cert_chain: []
|
12
|
-
date:
|
12
|
+
date: 2012-01-01 00:00:00.000000000 Z
|
13
13
|
dependencies:
|
14
14
|
- !ruby/object:Gem::Dependency
|
15
15
|
name: term-ansicolor
|
16
|
-
requirement: &
|
16
|
+
requirement: &2155928480 !ruby/object:Gem::Requirement
|
17
17
|
none: false
|
18
18
|
requirements:
|
19
19
|
- - ! '>='
|
@@ -21,17 +21,40 @@ dependencies:
|
|
21
21
|
version: '1.0'
|
22
22
|
type: :runtime
|
23
23
|
prerelease: false
|
24
|
-
version_requirements: *
|
24
|
+
version_requirements: *2155928480
|
25
|
+
- !ruby/object:Gem::Dependency
|
26
|
+
name: bundler
|
27
|
+
requirement: &2155927760 !ruby/object:Gem::Requirement
|
28
|
+
none: false
|
29
|
+
requirements:
|
30
|
+
- - ! '>='
|
31
|
+
- !ruby/object:Gem::Version
|
32
|
+
version: '0'
|
33
|
+
type: :development
|
34
|
+
prerelease: false
|
35
|
+
version_requirements: *2155927760
|
25
36
|
description: ! " Console color formatting library with abbreviations (e.g. 'rb'
|
26
|
-
for\n red and bold), and the ability to format several strings easily.\n
|
27
|
-
|
37
|
+
for\n red and bold), and the ability to format several strings easily.\n No
|
38
|
+
methods are added to core classes.\n"
|
39
|
+
email:
|
40
|
+
- gsinclair@gmail.com
|
28
41
|
executables: []
|
29
42
|
extensions: []
|
30
43
|
extra_rdoc_files: []
|
31
44
|
files:
|
32
|
-
-
|
45
|
+
- .gitignore
|
46
|
+
- Gemfile
|
47
|
+
- History.txt
|
33
48
|
- LICENCE
|
34
|
-
- README
|
49
|
+
- README.txt
|
50
|
+
- Rakefile
|
51
|
+
- col.gemspec
|
52
|
+
- doc/col.markdown
|
53
|
+
- etc/at
|
54
|
+
- etc/build_install_gem.sh
|
55
|
+
- etc/test-no-string-extension.rb
|
56
|
+
- lib/col.rb
|
57
|
+
- lib/col/version.rb
|
35
58
|
- test/_setup.rb
|
36
59
|
- test/col.rb
|
37
60
|
- test/col_db.rb
|
@@ -50,17 +73,17 @@ required_ruby_version: !ruby/object:Gem::Requirement
|
|
50
73
|
required_rubygems_version: !ruby/object:Gem::Requirement
|
51
74
|
none: false
|
52
75
|
requirements:
|
53
|
-
- - ! '
|
76
|
+
- - ! '>='
|
54
77
|
- !ruby/object:Gem::Version
|
55
|
-
version:
|
78
|
+
version: '0'
|
56
79
|
requirements: []
|
57
|
-
rubyforge_project:
|
58
|
-
rubygems_version: 1.8.
|
80
|
+
rubyforge_project: ''
|
81
|
+
rubygems_version: 1.8.13
|
59
82
|
signing_key:
|
60
83
|
specification_version: 3
|
61
|
-
summary:
|
84
|
+
summary: High-level console color formatting
|
62
85
|
test_files:
|
63
86
|
- test/_setup.rb
|
64
87
|
- test/col.rb
|
65
88
|
- test/col_db.rb
|
66
|
-
has_rdoc:
|
89
|
+
has_rdoc: false
|