summaryrefslogtreecommitdiff
path: root/src/lib/libremessages.1.ronn
blob: d4fac85f4222c1322a1c3a21c715d6daae3b541f (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
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
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
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 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.

   * `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 that is fed through
     `gettext`, and <MESSAGE_ARGS> are its arguments.

   * `whitespace_collapse`:
	 Collapses whitespace on stadard I/O, similar to HTML whitespace
	 collapsing, with the exception that it puts two spaces between
	 sentences.  It considers newline, tab, and space to be
	 whitespace.

### PROSE ROUTINES

These routines print to standard output, and are useful for printing
word-wrapped prose.

For each of these, <MESSAGE> is fed through `gettext` automatically.

To generate gettext `.pot` files for programs using these routines,
plain `xgettext`(1) won't work because it doesn't know about
word-wrapping.  Instead, you should use the `librexgettext`(1) program
which knows how do handle word-wrapping, and knows about each of these
routines by default.

   * `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>|<HEADING>:]...:
     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`.  If you
     pass in multiple flag/description pairs to the same invocation,
     the descriptions are all aligned together.  The ability to do
     insert headings without resetting the alignment is the motivation
     for also allowing headings to be in the list.  In order to tell
     the difference between a flag and a heading, a heading must end
     with a colon (':'), and a flag must not.

### 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.

To generate gettext `.pot` files for programs using these routines,
plain `xgettext`(1) will work if given correct flags, but you'll find
it easier to use `librexgettext`(1), which will handle each of these
without any extra flags.

   * `plain` <MESSAGE> [<ARGS>...]:
     Prints a "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`.

   * `print` <MESSAGE> [<ARGS>...]:
     Like `printf`(1), but `gettext`-aware, and automatically prints a
     trailing newline.

   * `term_title` <MESSAGE> [<ARGS>...]:
     Sets the terminal title to the specified message.

### 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, otherwise it calls `exit`(1) with a status of 0.

   * `abort`:
     Calls `msg` with the message "Aborting...", then calls
     `cleanup 255`.

   * `die` <MESSAGE> [<ARGS>...]:
     Exactly like `error`, but calls `cleanup` and calls `exit`(1)
     with a status of 255.

### LOCKFILE ROUTINES

   * `lock` <FD> <LOCKFILE> <MESSAGE> [<MSG_ARGS>...]:
     Opens (creating if necessary) 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 released, 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 locally 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 printed 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

`term_title` currently only knows about the terminals screen, tmux,
xterm and rxvt (and their various <TERM> values;
"rxvt-unicode-256color" is still rxvt).

## SEE ALSO

librexgettext(1), librelib(7), gettext(1), common.sh(3)

Things that were mentioned:

bash(1), xgettext(1), exit(1), isatty(3), libretools.conf(5),
makepkg(8), printf(1), signal(7)