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
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
|
libremessages(1) -- common Bash routines
========================================
## SYNOPSIS
`. $(librelib messages)`<br>
`. libremessages`<br>
`libremessages` <COMMAND>
## DESCRIPTION
`libremessages` is a shell library containing many common routines.
The name is a bit of a misnomer, it mostly deals with printing
messages, but also has other things.
`libremessages` uses `common.sh`(3) internally for a large portion of
it's functionality. The authors make no promises that functionality
that is implemented in `libremessages` won't move into `common.sh` or
vice-versa. So, it is recommended that you use `libremessages`, not
`common.sh`.
### STAND ALONE USAGE
The "normal" way to use libremessages is to source it, then call the
provided routines.
However, if you call libremessages directly, the first argument is
taken as a the function to call, and the remaining arguments are
passed to it. The only cases where this doesn't work are the lockfile
routines (`lock`, `slock`, and `lock_close`), because lockfiles are
managed as file descriptors.
### VARIABLES
The following variables for printing terminal color codes are set:
`ALL_OFF`, `BOLD`, `BLUE`, `GREEN`, `RED`, `YELLOW`. If standard
error is not a terminal (see `isatty`(3)), they are set, but empty.
They are marked as readonly, so it is an error to try to set them
afterwords.
### MESSAGE FORMAT
All routines feed the message/format string through `gettext`(1), if
it is available.
The descriptions will frequently reference `printf`(1)--this isn't
really that `printf`. The program described by the manual page
`printf`(1) is probably the version from GNU coreutils, every time it
is used here, it is `bash`(1)'s internal implementation; try running
the command `help printf` from a Bash shell for more information.
### GENERAL ROUTINES
Unless otherwise noted, these do not implicitly call `gettext`.
* `_` <MESSAGE>:
If `gettext` is available, calls `gettext`, otherwise just prints
the arguments given.
* `in_array` <NEEDLE> <HAYSTACK>...:
Evaluates whether <HAYSTACK> includes <NEEDLE>; returns 0 if it
does, non-zero if it doesn't.
* `panic`:
For the times when you can't reasonably continue, similar to
"assert" in some programming languages.
* `term_title` <MESSAGE>...:
Joins all arguments with whitespace, and sets the terminal title
to that.
* `setup_traps` [<HANDLER>]:
Sets traps on TERM, HUP, QUIT and INT signals, as sell as the ERR
event, similar to makepkg. If <HANDLER> is specified, instead of
using the default handler (which is good for most purposes), it
will call <HANDLER> with the arguments
`<HANDLER> <SIGNAL_NAME> <MESSAGE> [<MESSAGE_ARGS>...]`, where
<MESSAGE> is a `printf`(1)-formatted string, and <MESSAGE_ARGS>
are its arguments.
### PROSE ROUTINES
These routines print to standard output, ande are useful for printing
word-wrapped prose.
For each of these, <MESSAGE> is fed through `gettext` automatically.
* `print` <MESSAGE> [<ARGS>...]:
Like `printf`(1), but `gettext`-aware, and automatically prints a
trailing newline.
* `prose` <MESSAGE> [<ARGS>...]:
Takes a `printf`(1)-formatted string, collapses whitespace
(HTML-style), and then word-wraps it.
* `bullet` <MESSAGE> [<ARGS>...]:
Similar to `prose`, but prints a bullet point before the first
line, and indents the remaining lines.
* `flag` <FLAG> <DESCRIPTION>:
Print a flag and description formatted for `--help` text. For
example:<br>
`flag '-N' 'Disable networking in the chroot'`<br>
The description is fed through `gettext`, the flag is not, so if
part of the flag needs to be translated, you must do that
yourself:<br>
`flag "-C <$(_ FILE)>" 'Use this file instead of pacman.conf'`<br>
Newlines in the description are ignored; it is
whitespace-collapsed (so newlines are stripped), then it is
re-word-wrapped, in the same way as `prose` and `bullet`.
### NOTIFICATION ROUTINES
These routines print to standard error, and all take arguments in the
same format as `printf`(1), except for `stat_done`, which doesn't take
any arguments. Each of these print to stderr, not stdout.
For each of these, <MESSAGE> is fed through `gettext` automatically.
* `plain` <MESSAGE> [<ARGS>...]:
Prints "plain" message in bold, indented with 4 spaces.
* `msg` <MESSAGE> [<ARGS>...]:
Prints a top-level priority notification.
* `msg2` <MESSAGE> [<ARGS>...]:
Prints a secondary notification.
* `warning` <MESSAGE> [<ARGS>...]:
Prints a warning.
* `error` <MESSAGE> [<ARGS>...]:
Prints an error message.
* `stat_busy` <MESSAGE> [<ARGS>...]:
Prints a "working..." type message without a trailing newline.
* `stat_done`:
Prints a "done" type message to terminate `stat_busy`.
### TEMPORARY DIRECTORY MANAGEMENT
These are used by devtools, and not used within the rest of
libretools.
They work by creating and removing the directory referred to by the
variable $<WORKDIR>; `libretools.conf`(5) uses the same variable to
where the user saves all their work. If you aren't careful with
these, you could end up deleting a lot of someone's work.
* `setup_workdir`:
Creates a temporary directory, and sets the environmental
variable $<WORKDIR> to it. Also sets traps for the signals INT,
QUIT, TERM and HUP to run `abort`; and EXIT to run `cleanup`
(see `signal`(7)).
* `cleanup` [<EXIT_STATUS>]:
*If* `setup_workdir` has been run, `rm -rf "$WORKDIR"`. If given
a numeric argument, it will then call `exit`(1) with that argument.
* `abort`:
Calls `msg` with the message "Aborting...", then calls
`cleanup 0`.
* `die` <MESSAGE> [<ARGS>...]:
Exactly like `error`, but calls `cleanup` and calls `exit`(1)
with a status of 1.
### LOCKFILE ROUTINES
* `lock` <FD> <LOCKFILE> <MESSAGE> [<MSG_ARGS>...]:
Opens (creating if nescessary) the file <LOCKFILE> with file
descriptor <FD> in the current process, and gets an exclusive
lock on it. If another program already has a lock on the file,
and this program needs to wait for the lock to be release, then
it uses `stat_busy`/`stat_done` to print <MESSAGE>.
* `slock` <FD> <LOCKFILE> <MESSAGE> [<MSG_ARGS>...]:
Identical like `lock`, but opens a shared lock. This is also
known as a "read lock". Many programs can have a shared lock at
the same time, as long as no one has an exclusive lock on it.
* `lock_close` <FD>:
Closes file descriptor <FD>, releasing the lock opened on it.
### MAKEPKG ROUTINES
These routines relate to `makepkg`(8).
* `find_cached_package` <PKGNAME> <PKGVER>[-<PKGREL] <ARCH>:
Searches for a localy built copy of the specified package, in
<PKGDEST> and the current working directory. If <PKGREL> is not
specified, any value will match. If multiple matching files are
found (not counting duplicate links), then an error is printed to
stderr and nothing is prented to stdout.
* `get_full_version` [<PKGNAME>]:
Inspects variables that are set, and prints the full version
spec, including <epoch> if necessary, <pkgver>, and <pkgrel>. By
default, it will print the information for <pkgbase>, following
the normal rules for finding <pkgbase>. If <PKGNAME> is given,
it will print the information for that sub-package. The versions
for different parts of a split package don't have to be the same!
## BUGS
Generating `.pot` files for the prose functions is a pain. The
libretools Makefiles have rules to do it, but it might make sense to
pull it into a separate program.
`term_title` currently only knows about the terminals screen, tmux,
xterm and rxvt (and their various <TERM> values;
"rxvt-unicode-256color" is still rxvt).
Also, I think `abort` calling `cleanup 1` would make more sense than
`cleanup 0`.
## SEE ALSO
librelib(7), gettext(1), common.sh(3)
Things that were mentioned:
bash(1), exit(1), isatty(3), libretools.conf(5), makepkg(8),
printf(1), signal(7)
|
