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.
@@ -0,0 +1,4 @@
1
+ *.gem
2
+ debug.log
3
+ tags
4
+ Gemfile.lock
data/Gemfile ADDED
@@ -0,0 +1,4 @@
1
+ source "http://rubygems.org"
2
+
3
+ # Specify your gem's dependencies in col.gemspec
4
+ gemspec
@@ -0,0 +1,10 @@
1
+ === 1.0.1 / 2012-01-01
2
+
3
+ * 1 minor enhancement:
4
+
5
+ * Col#to_str implemented to play nicely with puts
6
+ (problem became apparent with Ruby 1.9.3?)
7
+
8
+ === 1.0.0 / 2010-07-25
9
+
10
+ * First release
@@ -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
- Synopsis
7
+ === SYNOPSIS
8
8
 
9
9
  require 'col'
10
10
 
@@ -0,0 +1 @@
1
+ require "bundler/gem_tasks"
@@ -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
@@ -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
@@ -0,0 +1,4 @@
1
+ #!/usr/bin/env bash
2
+
3
+ attest=../attest
4
+ exec ruby -rubygems -Ilib -I${attest}/lib ${attest}/bin/attest $*
@@ -0,0 +1,2 @@
1
+ gem build etc/col.gemspec
2
+ gem install ./col-*.gem --no-rdoc --no-ri
@@ -0,0 +1,11 @@
1
+ require 'attest/auto'
2
+ require 'col'
3
+
4
+ D "String does not have Term::ANSIColor mixed in" do
5
+ E(NoMethodError) { "col".red }
6
+ end
7
+
8
+ D "The result of Col#fmt does not have Term::ANSIColor mixed in" do
9
+ str = Col("string").r
10
+ E { str.red }
11
+ end
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)
@@ -0,0 +1,3 @@
1
+ class Col
2
+ VERSION = "1.0.1"
3
+ end
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.1a
5
- prerelease: 5
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: 2011-12-31 00:00:00.000000000 Z
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: &2164543120 !ruby/object:Gem::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: *2164543120
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
- email: gsinclair@gmail.com
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
- - lib/col.rb
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: 1.3.1
78
+ version: '0'
56
79
  requirements: []
57
- rubyforge_project:
58
- rubygems_version: 1.8.10
80
+ rubyforge_project: ''
81
+ rubygems_version: 1.8.13
59
82
  signing_key:
60
83
  specification_version: 3
61
- summary: high-level console color formatting
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: true
89
+ has_rdoc: false