Add format string doku, simplify format string handling.
[adu.git] / select.ggo
1
2 option "uid" u
3 #~~~~~~~~~~~~~
4 "user id(s) to take into account"
5 string typestr="uid_spec"
6 optional
7 details="
8 An uid specifier may be a single number, or a range of uids.
9 Example:
10
11 --uid 42 # only consider uid 42
12 --uid 42- # only consider uids greater or equal than 42
13 --uid 23-42 # only consider uids between 23 and 42, inclusively.
14 --uid 23-42,666-777,88 # consider uids 23-42, 666-777 and 88.
15 "
16
17 option "limit" L
18 #~~~~~~~~~~~~~~~
19 "Limit output"
20 int typestr="num"
21 default="-1"
22 optional
23 details="
24 Only print num lines of output. If negative (the default),
25 print all lines.
26 "
27
28 option "no-headers" -
29 #~~~~~~~~~~~~~~~~~~~~
30 "supress descriptions for listings/summaries"
31 flag off
32 details="
33 This is mostly useful to feed the output of adu to scripts.
34 "
35
36 option "select-mode" m
37 #~~~~~~~~~~~~~~~~~~~~~
38 "How to print the results of the query"
39 enum typestr="<key>"
40 values="global_list","global_summary","user_list","user_summary"
41 default="global_list"
42 optional
43 details="
44 global_list: List of directories, regardless of owner.
45 global_summary: Only print totals.
46 user_list: Print a list for each admissible uid.
47 user_summary Print totals for each admissible uid.
48 "
49
50 option "list-sort" s
51 #~~~~~~~~~~~~~~~~~~~
52 "how to sort the user list or the global list"
53 enum typestr="<key>"
54 values="size","file_count"
55 default="size"
56 optional
57 details="
58 This option is ignored if select-mode is neither \"user_list\", nor
59 \"global_list\".
60 "
61
62 option "output" o
63 #~~~~~~~~~~~~~~~~
64 "file to write output to"
65 string typestr="<path>"
66 optional
67 default="-"
68 details="
69 If empty, or not given, use stdout.
70 "
71
72 option "user-summary-sort" -
73 #~~~~~~~~~~~~~~~~~~~~~~~~~~~
74 "how to sort the user-summary"
75 enum typestr="col_spec"
76 values="name","uid","dir_count","file_count","size"
77 default="size"
78 optional
79 details="
80 It is enough to specify the first letter of the column specifier,
81 e.g. \"--user-summary-sort f\" sorts by file count.
82 "
83
84 option "print-base-dir" -
85 #~~~~~~~~~~~~~~~~~~~~~~~~
86 "whether to include the base-dir in the output"
87 flag off
88 details="
89 If this flag is given, all directories printed are prefixed
90 with the base directory. The default is to print paths relative
91 to the base dir.
92 "
93
94 option "format" f
95 #~~~~~~~~~~~~~~~~
96 "How to format the output"
97 string typestr="<format_string>"
98 optional
99 details="
100 A string that specifies how the output of the select query is
101 goint to be formated. Depending on the chosen select-mode,
102 several conversion specifiers are available and a different
103 default value for this option applies.
104
105 adu knows four different types of directives: string, id,
106 count and size. These are explained in more detail below.
107
108 The general syntax for string and id directives is %(name:a:w)
109 where \"name\" is the name of the directive, \"a\" specifies
110 the alignment and \"w\" is the width specifier which allows
111 to give a field width.
112
113 The alignment specifier is a single character: Either \"l\",
114 \"r\", or \"c\" may be given to specify left, right and
115 centered alignment respectively. The with specifier is a
116 positive integer. Both \"a\" and \"w\" are optional.
117
118 A string directive supported by adu is \"dirname\" which is
119 subsitituted by the name of the directory. It is available
120 if either user_list or global_list mode was selected via
121 --select-mode.
122
123 Examples:
124
125 \"%(diname)\" # print dirname without any padding
126 \"%(dirname:c:20)\" # center dirname in a 20 chars wide field
127
128 The other two types of directives, count and size, are used
129 for numbers. The syntax for these is %(name:a:w:u). The \"a\"
130 and the \"w\" specifier have the same meaning as for the string
131 and id directives. The additional \"u\" specifier selects a unit
132 in which the number that corresponds to the directive should
133 be formated. All three specifiers are optional.
134
135 Possible units are the characters of the set \" bkmgtBKMGT\"
136 specifying bytes, kilobytes, megabytes, gigabytes and
137 terabytes respectively. The difference between the lower and
138 the upper case variants is that the lower case specifiers
139 select 1024-based units while the upper case specifiers use
140 1000 as the basis.
141
142 The whitespace character is like \"b\", but a space character
143 is printed instead of a unit.
144
145 Two more characters \"h\" and \"H\" (human-readable) are also
146 available that choose an appropriate unit depending on the
147 size of the number being printed.
148
149 An asterisk prepended to the unit specifier prevents the
150 unit from being printed. This is useful mainly for feeding
151 the output of adu to scripts that do not expect units.
152
153 In order to print a percent sign, use \"%%\". Moreover, adu
154 understands \"\n\" and \"\t\" and outputs a newline and a
155 tab character for these combinations respectively.
156
157 Examples:
158
159 \"%(size:r::G)\" # print size in gigabytes right-aligned
160 \"%(size:r5::G)\" # as before, but use 5 char wide field
161 \"%(size:r5::*G)\" # as before, but supress trailing \"G\"
162
163 List of directives and types known to adu, together with their types:
164
165 name type meaning
166 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
167 pw_name string user name
168 uid id user id
169 files count number of files
170 dirname string name of the directory
171 size size total size/ directory size
172 dirs count number of directories
173
174 Not all directives are available for each mode:
175
176 name available in directives
177 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
178 pw_name user_list, user_summary
179 uid user_list, user_summary
180 files everywhere
181 dirname user_list, global_list
182 size everywhere
183 dirs suer_summary, global_summary
184 "