aboutsummaryrefslogtreecommitdiffstats
path: root/colorize.1
blob: 5168dac60f95b0b58f7c62822c243625f6e168f1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
.TH COLORIZE 1 "2019-09-01" "colorize v0.65" "User Commands"
.SH NAME
colorize \- colorize text on terminal with ANSI escape sequences
.SH SYNOPSIS
\fBcolorize\fR [\fIoption\fR]... (\fIforeground\fR) [\fI-|file\fR]
.PP
\fBcolorize\fR [\fIoption\fR]... (\fIforeground\fR)/(\fIbackground\fR) [\fI-|file\fR]
.PP
\fBcolorize\fR \-\-clean[\-all] [\fI-|file\fR]
.PP
\fBcolorize\fR \-hV
.SH DESCRIPTION
Colorizes text read from standard input stream or file by using ANSI
escape sequences (and also vice versa, i.e. cleaning text from sequences)
and prints resulting output to the terminal.
.PP
When colorizing text, (foreground) and eventually (background) may be either
one of following color values: none, black, red, green, yellow, blue, magenta,
cyan, white, default or random.  First character of color name in upper
case denotes increased intensity, whereas for lower case colors will be of
normal intensity.  If "none" is chosen, no escape sequences will be emitted.
.PP
Color escape sequences are added per each line, hence colored lines can be
safely extracted.
.PP
When de-colorizing text, \-\-clean omits color escape sequences which
were emitted by colorize (see NOTES for list), whereas \-\-clean\-all
omits all valid ones.  If in doubt, consider using \-\-clean\-all.
.SH OPTIONS
.TP
.BR \-\-attr=\fIATTR1,ATTR2,...\fR
set attributes by name
.RS
Attributes: bold, underscore, blink, reverse and concealed.
.RE
.TP
.BR \-\-clean
clean text from color escape sequences emitted by colorize
.TP
.BR \-\-clean\-all
clean text from all valid color escape sequences
.TP
.BR \-c ", " \-\-config=\fIPATH\fR
alternate configuration file location
.TP
.BR \-\-exclude\-random=\fICOLOR\fR
text color to be excluded when selecting a random foreground color
.TP
.BR \-\-omit\-color\-empty
omit printing color escape sequences for empty lines
.TP
.BR \-h ", " \-\-help
show help screen and exit
.TP
.BR \-V ", " \-\-version
display version data and exit
.SH FILES
.TP
.B ~/.colorize.conf
user configuration file
.PP
.RS
If the aforementioned file exists, it is read, parsed and processed
prior to handling the command-line options.  Command-line options
override configuration values, but are currently not capable of
unsetting them.  If unsetting is desired, comment them out or remove
them.
.RE
.PP
.RS
.B Sample configuration file
.RS
.nf
# ~/.colorize.conf
attr = bold,underscore
color = magenta # favorite one
exclude-random = black
omit-color-empty = yes
.fi
.RE
.RE
.PP
.RS
.B Configurable options and values
.RS
.nf
attr             (values same as command-line option)
color            (value  same as command-line colors)
exclude-random   (value  same as command-line option)
omit-color-empty (yes/no)
.fi
.RE
.RE
.PP
.RS
.B Syntax
.RS
Each line ought to start with a name of an option, followed by = and
an optional value.  Leaving the value blank, unsets the option.
.PP
Whitespace is allowed before the option name, after the option name,
before the option value and after the option value.
.PP
Comments may be placed before or after the option is set.  Everything
following the '#' sign is treated as being commented out.
.RE
.RE
.SH NOTES
The list of color escape sequence codes being emitted and omitted is
as follows:
.IP * 4
30-37,39 (foreground colors)
.IP * 4
1-9;30-37,39 (foreground colors with attributes)
.IP * 4
40-47,49 (background colors)
.IP * 4
0 (reset)
.SH EXAMPLES
.TP
$ \fBcolorize green /etc/motd\fR
Print file /etc/motd with green as foreground color
.TP
$ \fBcolorize green/black /etc/motd\fR
Print file /etc/motd with green as foreground and black as background color
.TP
$ \fBcolorize green /etc/motd | colorize --clean\fR
Print input from stdin with color escape sequences omitted
.TP
$ \fBgit log -1 -p --color | colorize --clean-all\fR
Print input from stdin with all color escape sequences omitted
.TP
$ \fBcolorize --attr=bold green /etc/motd\fR
Print file /etc/motd with bold green as foreground color
.SH AUTHOR
Steven Schubiger <stsc@refcnt.org>