Update copyright year.
[tfortune.git] / tfortune.suite.m4
1 # SPDX-License-Identifier: GPL-3.0-only
2
3 [suite tfortune]
4 caption = Subcommands
5 [supercommand tfortune]
6 purpose = fortune cookies with tags
7 [description]
8 DESCRIPTION1()
9
10 DESCRIPTION2()
11
12 DESCRIPTION3()
13 [/description]
14 synopsis = [global-options...] [--] [<subcommand> [subcommand-options...]]
15 [option help]
16 summary = print help and exit
17 short_opt = h
18 [option detailed-help]
19 summary = print help, including all details, and exit
20 [option version]
21 summary = print version and exit
22 short_opt = V
23 [option loglevel]
24 summary = control amount of logging
25 short_opt = l
26 arg_info = required_arg
27 arg_type = string
28 typestr = severity
29 values = {
30 LSGLL_DEBUG = "debug",
31 LSGLL_INFO = "info",
32 LSGLL_NOTICE = "notice",
33 LSGLL_WARNING = "warning",
34 LSGLL_ERROR = "error",
35 LSGLL_CRIT = "crit",
36 LSGLL_EMERG = "emerg"
37 }
38 default_val = warning
39 [help]
40 Log only messages with severity greater or equal than the given
41 value. Possible values:
42
43 debug: Produces really noisy output.
44 info: Still noisy, but won't fill up the disk quickly.
45 notice: Indicates normal, but significant event.
46 warning: Unexpected events that can be handled.
47 error: Unhandled error condition.
48 crit: System might be unreliable.
49 emerg: Last message before exit.
50 [/help]
51 [option basedir]
52 summary = where to look for input files
53 short_opt = b
54 arg_info = required_arg
55 arg_type = string
56 typestr = directory
57 default_val = "~/.tfortune"
58 [help]
59 This is used to locate epigrams and named tag expressions.
60 If any filename argument does not start with a slash, the
61 filename is interpreted as relative to this base directory.
62
63 Epigrams are expected in the "epigrams" subdirectory of the base
64 directory while tag expressions are expected to be stored below
65 "expressions".
66 [/help]
67
68 [subcommand compgen]
69 purpose = perform bash command line completion
70 non-opts-name = arg...
71 [description]
72 This subcommand is executed from the bash completer for tfortune. The
73 completer sets the non-option arguments for the subcommand to the
74 words of the current command line. It obtains these words from the
75 elements of the special COMP_WORDS array which is maintained by bash.
76
77 The compgen subcommand writes all possible completions to stdout. The
78 completer reads in the completions and builds the COMPREPLY array
79 containing the matching entries. Bash examines the elements of this
80 array and completes the command line if there is a single matching
81 completion, or prints out the list of completions in case of ambiguity.
82
83 [/description]
84 [option current-word-index]
85 short_opt = c
86 summary = index of the current word in the command line
87 typestr = num
88 arg_info = required_arg
89 arg_type = uint32
90 [help]
91 An index into the argument vector of the word containing the current
92 cursor position. See the description of the $CWORD special variable
93 in the bash manual.
94 [/help]
95
96 [subcommand completer]
97 purpose = print the bash completer to stdout
98 [description]
99 The output of this command is designed to be re-used as input for bash.
100 Specifically, bash completion for tfortune can be activated by adding
101 the following to .bashrc: eval "$(tfortune completer)".
102 [/description]
103 [option alias]
104 summary = also add an alias and a completer for it
105 short_opt = a
106 arg_info = required_arg
107 arg_type = string
108 typestr = name
109 [help]
110 Specify this to define a bash alias for tfortune along with the
111 completer. Unlike the regular tfortune program, the alias will
112 contain the double dash argument which separates the subcommand and
113 its options from the options to tfortune itself.
114 [/help]
115
116 [subcommand ede]
117 purpose = edit epigrams
118 non-opts-name = basename...
119 [description]
120 Opens the named epigram file an interactive editor. The executable
121 of the editor is determined as follows: First the contents of the
122 environment variable TFORTUNE_EDITOR is examined. If this variable
123 is empty or unset, EDITOR is tried. If EDITOR is also unset, vi
124 is executed.
125
126 The given basename is interpreted as described in the help text of the
127 --basedir option above. If --basedir is not given and the "epigrams"
128 directory does not exist, it is created.
129 [/description]
130
131 [subcommand edx]
132 purpose = edit tag expressions
133 non-opts-name = basename...
134 [description]
135 Opens the named tag expression file an interactive editor. The editor
136 to execute is determined in the same way as for the "ede" subcommand.
137 Also, a non-existing "expressions" subdirectory is handled in the same
138 way.
139 [/description]
140 [subcommand help]
141 purpose = list available subcommands or print command-specific help
142 non-opts-name = [command]
143 [description]
144 Without any arguments, help prints the list of available commands. When
145 called with a command name argument, it prints the help text of the
146 given command.
147 [/description]
148 [option long]
149 short_opt = l
150 summary = show the long help text
151 [help]
152 If the optional argument is supplied, the long help text contains the
153 synopsis, the purpose and the description of the specified command,
154 followed by the option list including summary and help text of each
155 option. Without --long, the short help is shown instead. This omits
156 the description of the command and the option help.
157
158 If no command is supplied but --long is given, the list contains the
159 purpose of each command.
160 [/help]
161
162 [subcommand lse]
163 purpose = list epigram files
164 [description]
165 Print the list of all epigram files.
166 [/description]
167 [option long]
168 short_opt = l
169 summary = long listing
170 [help]
171 This is similar to the long output of the standard ls(1) command.
172 [/help]
173
174 [subcommand lst]
175 purpose = list tags
176 [description]
177 This lists all tags contained in any of the given input files.
178 [/description]
179 non-opts-name = <file>...
180 [option long]
181 short_opt = l
182 summary = long listing
183 [help]
184 Also show how many times this tag appears.
185 [/help]
186 [option sort-by-count]
187 short_opt = c
188 summary = sort by occurrence count rather than alphabetically.
189 [option reverse]
190 short_opt = r
191 summary = reverse sort order
192
193 [subcommand lsx]
194 purpose = list tag expressions
195 [description]
196 Print the list of all named tag expressions.
197 [/description]
198 [option long]
199 short_opt = l
200 summary = long listing
201 [help]
202 This is similar to the long output of the standard ls(1) command.
203 [/help]
204 [subcommand print]
205 purpose = print epigram(s)
206 [description]
207 Unless --all is given, this picks an epigram by random from the
208 given file(s) which is admissible with respect to the given named
209 tag expression. If no file is given, all files are taken into account.
210 [/description]
211 non-opts-name = [file...]
212 [option expression]
213 short_opt = x
214 summary = name of the tag expression
215 arg_info = required_arg
216 arg_type = string
217 typestr = filename
218 default_val = /dev/null
219 [help]
220 Use the tag expression stored in the given file to define the
221 admissible epigrams. The special string "-" means to read the tag
222 expression from stdin. The default value corresponds to the empty
223 tag expression for which all epigrams are admissible.
224 [/help]
225 [option all]
226 short_opt = a
227 summary = print all admissible epigrams, not just a random one.
228 [option tags]
229 short_opt = t
230 summary = print also the tags of the selected epigram
231 [subcommand stats]
232 purpose = show statistics
233 [description]
234 This prints several counts and averages about the epigrams, tags and
235 tag expressions.
236 [/description]
237 [option verbose]
238 short_opt = v
239 summary = include statistics about hash table utilization
240
241 [section Input file format]
242 Input files may contain arbitrary many epigrams. The end of each
243 epigram must be marked with a "tag" line. The tag line consists of
244 four dashes, a space character, and a comma separated list of tags.
245 Tags may span multiple words, but no comma is allowed. The following
246 is an example input file for tfortune. It contains a single epigram
247 with two tags.
248
249 .RS
250 .EX
251 Anyone who attempts to generate random numbers by deterministic means
252 is, of course, living in a state of sin. -- John von Neumann
253 ---- math,religion
254 .EE
255 .RE
256 [/section]
257
258 [section Tag Expressions]
259 Tag expressions are based on a context-free grammar in which the
260 following keywords are defined:
261 .IP \(bu 4
262 .B tag("foo")
263 evaluates to
264 .I true
265 if the epigram contains a tag named
266 .IR foo ,
267 .I false
268 otherwise.
269 .IP \(bu 4
270 .B len
271 evaluates to the number of bytes of the epigram.
272 .IP \(bu 4
273 .B text
274 evaluates to contents of the epigram. This is useful for pattern
275 matching.
276 .P
277
278 The grammar admits the following operators and relations:
279 .IP \(bu 4
280 .BR && ,
281 .BR || ,
282 .BR !:
283 logical operators for
284 .IR and ,
285 .IR or ,
286 and
287 .IR not .
288 .IP \(bu 4
289 .BR + ,
290 .BR - ,
291 .BR * ,
292 .BR + :
293 arithmetic operators for addition, negation or subtraction (unary
294 or binary minus), multiplication and division. Arithmetic is always
295 performed on 64 bit signed integers.
296 .IP \(bu 4
297 .BR < ,
298 .BR > ,
299 .BR <=,
300 .BR >=,
301 .BR ==,
302 .BR != :
303 .BR =~ :
304 less than, greater than, less or equal than, greater or equal than,
305 equal to, not equal to, regular expression match.
306 Regular expression patterns are of the form
307 .IR /pattern/[flags] .
308 That is, the pattern is delimited by slashes, and is followed by
309 zero or more characters, each specifying a flag according to the
310 following list
311 .RS
312 .IP \(bu 4
313 .BR i :
314 Ignore case in match
315 .RI ( REG_ICASE )
316 .IP \(bu 4
317 .BR n :
318 Treat newline as an ordinary character
319 .RI ( REG_NEWLINE )
320
321 .RE
322 .RS
323 Note that only extended regular expression patterns are supported. See
324 regex(3) for details.
325 .RE
326
327 The above operators obey the usual associativity and precedence
328 rules. Parentheses can be used to change precedence.
329
330 A
331 .I tag expression
332 is an expression in this grammar which evaluates to either
333 .I true
334 or
335 .IR false .
336 Epigrams for which the expression is
337 .I true
338 are called
339 .IR admissible .
340
341 For example, the above epigram is admissible for the tag expression
342
343 .RS
344 .EX
345 (tag("math") || tag("physics")) && len < 1000 && text =~ /neumann/i
346 .EE
347 .RE
348
349 It is not admissible for
350
351 .RS
352 .EX
353 (tag("math") && tag("physics")) || len > 1000 || text =~ /neumann/
354 .EE
355 .RE
356 [/section]
357
358 [section Examples]
359 .IP \(bu 2
360 Print a random epigram:
361
362 .RS 6
363 .EX
364 tfortune print
365 .EE
366 .RE
367 .IP \(bu 2
368 Print a random short (less than 100 bytes) epigram:
369
370 .RS 6
371 .EX
372 echo 'len < 100' | tfortune -l debug -- print -x -
373 .EE
374 .RE
375 .IP \(bu 2
376 List tags, including usage counts, sort by count in descending order:
377
378 .RS 6
379 .EX
380 tfortune -- lst -lcr
381 .EE
382 .RE
383 .IP \(bu 2
384 Activate bash completion and define the
385 .I tf
386 alias:
387
388 .RS 6
389 .EX
390 eval "$(tfortune completer -a tf)"
391 .EE
392 .RE
393
394 [/section]
395
396 [section copyright]
397 Written by AUTHOR()
398 .br
399 Copyright (C) COPYRIGHT_YEAR() AUTHOR()
400 .br
401 License: LICENSE()
402 .br
403 This is free software: you are free to change and redistribute it.
404 .br
405 There is NO WARRANTY, to the extent permitted by law.
406 .br
407 Report bugs to
408 .MT <PACKAGE_BUGREPORT()>
409 AUTHOR()
410 .ME
411 .br
412 Homepage:
413 .UR PACKAGE_URL()
414 .UE
415 [/section]
416 [section see also]
417 .BR fortune (6)
418 [/section]