Debian Codegraph @

tools/__tool

raw
1 #!/usr/bin/env sh
2
3 # shellcheck disable=SC3043,SC1111
4
5 true <<EOF
6 This script is intended for use with preparing a container environment, providing
7 a pile of common utilities that are useful for environment setup and management.
8
9 Basic usage:
10
11 __tool <subcommand> [args...]
12
13 where "<subcommand>" is any top-level function in this file.
14
15 The special '__init' subcommand installs several system-wide aliases for
16 common subcommands that are available in this file.
17
18 Running __init or __alias requires permission to install files into '/usr/local'.
19 Other commands, except for package management ones, do not require any special
20 permissions.
21 EOF
22
23 set -eu
24
25 __init() {
26 __alias __alias __tool __alias
27 __alias __bool __tool __bool
28 __alias __boolstr __tool __boolstr
29 __alias __can_install __tool __can_install
30 __alias __do __tool __do
31 __alias __download __tool __download
32 __alias __fail __tool __fail
33 __alias __have_command __tool __have_command
34 __alias __install __tool __install
35 __alias __purpose __tool __purpose
36 __alias __silently __tool __silently
37 __alias __str __tool __str
38 }
39
40 # ? __fail <f-string> [args...]
41 # This formats the given arguments using shell `printf` and writes the message
42 # to stderr, then immediately returns 1.
43 __fail() {
44 # shellcheck disable=SC2059
45 printf "$@" 1>&2
46 printf "\n" 1>&2
47 return 1
48 }
49
50 # ? __alias <name> [command...]
51 # This subcommand will generate a system-wide persistent subcommand alias by
52 # the name `<name>`, installed in `/usr/local/bin`. The generated alias will
53 # execute the given `[command...]`. Any arguments passed to the generated alias
54 # command will be forwarded on to the underlying command cleanly.
55 #
56 # No special quoting should be used for `command`.
57 __alias() {
58 command='' name="$1"
59 shift
60 # Append each argument to the command with proper quoting
61 for x in "$@"; do
62 x=$(__quote "$x") || return
63 command="$command$x "
64 done
65 command="$command\"\$@\""
66 filename="/usr/local/bin/$name"
67
68 echo "#!/usr/bin/env sh" > "$filename" || return
69 echo "$command" >> "$filename" || return
70 chmod a+x "$filename" || return
71 echo "Created command alias '$filename' of [$command]" 1>&2 || return
72 }
73
74 # ? __bool <b>
75 # Evaluate a string `<b>` as a boolean, returning zero if it is truthy. This
76 # follows the same truthy-ness rules as CMake, and is case-insensitive.
77 __bool() {
78 # Normalize the case of the passed argument
79 bool=$(echo "${1-}" | __str upper)
80 case "$bool" in
81 0|OFF|NO|FALSE|N|IGNORE|NOTFOUND|""|*-NOTFOUND)
82 return 1;;
83 *)
84 return 0;;
85 esac
86 }
87
88 # ? __boolstr <b>
89 # As with `__bool`, but instead of returning 0/1, it will print the word `true`
90 # or `false` to stdout, and always returns 0
91 __boolstr() {
92 if __bool "$@"; then
93 printf "true"
94 else
95 printf "false"
96 fi
97 }
98
99 # ? __have_command <cmd>
100 # Test whether the command `<cmd>` can be executed by the shell, regardless of
101 # the underlying command type. Returns 0 if-and-only-if the command can be executed.
102 __have_command() {
103 __silently type "$1"
104 }
105
106 # ? __do <message> [command...]
107 # Print `<message>`, and execute `command` silently, only printing its output
108 # if it exits non-zero.
109 __do() {
110 printf '%s\n' "$1"
111 shift
112 local output
113 output="$("$@")"
114 rc=$?
115 if [ $rc != 0 ]; then
116 printf %s "$output"
117 return $rc
118 fi
119 }
120
121 # ? __download --from=<url> --to=<filepath> --hash=<hashspec>
122 # Download a file from the given `<url>` using Curl, saving to the filepath named by `<filepath>.
123 # If `<hashspec>` is the literal word "unchecked", then no hash verification will take place,
124 # otherwise `<hashspec>` should be in the form of `<program>=<expect-digest>`, and the __download
125 # tool will invoke `<program>` to calculate the hash digest, and compares the resulting hash to
126 # `<expect-digest>`. If the hash does not match, the download operation fails.
127 #
128 # All arguments are required and must be specified in the `--foo=bar` format
129 __download() {
130 # Split out the named arguments
131 local from='' to_file='' hash_arg='' hash_prog='' hash_expect='[placeholder]'
132 for arg in "$@"; do
133 case $arg in
134 --from=*) from=${arg#*=};;
135 --to=*) to_file=${arg#*=};;
136 --hash=*)
137 hash_arg="${arg#*=}"
138 hash_prog=${hash_arg%%=*}
139 hash_expect=${hash_arg#*=}
140 ;;
141 *)
142 __fail "Unkown __download argument: “%s”" "$arg" || return;;
143 esac
144 done
145
146 # Check required arguments
147 test "$from" || __fail "__download expects a --from=... argument" || return
148 test "$to_file" || __fail "__download requires a --to=... argument" || return
149 test "$hash_arg" || __fail "__download expects a --hash=<algo>=<digest> argument" || return
150
151 # We save to a temporary file while checking its hash
152 local tmp="$to_file.tmp"
153 # Create the destination directory for the file
154 local pardir
155 pardir="$(dirname "$tmp")" || return
156 mkdir -p "$pardir" || return
157
158 # Do the download now
159 if __have_command curl; then
160 curl --location --silent --fail --show-error --output "$tmp" "$from" || return
161 elif __have_command wget; then
162 wget --quiet --output-document="$tmp" "$from" || return
163 else
164 __fail "We require either Curl or Wget to be available to use __download" || return
165 fi
166
167 # If the hash argument was literal "unchecked", then we don't check the hash
168 if test "$hash_arg" != 'unchecked'; then
169 # Grab the actual hash by invoking the algorithm program:
170 local hash_actual
171 hash_actual=$("$hash_prog" "$tmp")
172 # Trim content to only the actual part that we want
173 hash_actual=${hash_actual%% *}
174
175 # Case-insensitive compare with the digest that the caller provided
176 if ! __str test "$hash_expect" -ieq "$hash_actual"; then
177 __fail "Downloaded file hash in an incorrect hash. Expected “%s”, but got “%s” (used %s)" \
178 "$hash_expect" "$hash_actual" "$hash_prog" || return
179 fi
180 fi
181
182 # Remove any possible destination file to overwrite it
183 rm -f -- "$to_file" || return
184 # Move the temporary into its final place
185 mv -- "$tmp" "$to_file" || return
186 }
187
188 # ? __install [pkgs...]
189 # Installs zero or more named packages using the platform's package manager.
190 # This script "just does the right thing" to install a package as a single step,
191 # primarily to improve caching and reliability in a container image build, as a bare
192 # "pkg-tool install" might be insufficient or subtly broken, and we only really
193 # care about installing a list of packages
194 __install() {
195 if test $# = 0; then
196 return 0
197 fi
198 if test -f /etc/debian_version ; then
199 # We *must* do a repo update as part of the install step in a single cache
200 # layer, as a cached apt-get update can become stale and prevent a later
201 # apt-get install from working properly
202 apt-get -y update || return
203 # DEBIAN_FRONTEND suppresses all interactivity. For some reason some
204 # packages like to prompt as part of their config, even if we're not on
205 # a TTY.
206 test $# = 0 || env DEBIAN_FRONTEND=noninteractive \
207 apt-get -y install -- "$@" || return
208 elif test -f /etc/redhat-release || grep 'ID="amzn"' /etc/os-release >/dev/null 1>&2; then
209 # Install using dnf. This has been the preferred package manager command since
210 # RHEL 8, and has somewhat better behavior that Yum. If we want to support older
211 # systems, this block will need to be updated to detect Yum if dnf is unavailable.
212 test $# = 0 || dnf install -y "$@" || return
213 elif test -f /etc/SuSE-brand \
214 || (test -f /etc/os-release && grep "opensuse" /etc/os-release); then
215 test $# = 0 || zypper --non-interactive install "$@" || return
216 elif test -f /etc/arch-release; then
217 test $# = 0 || pacman --sync --refresh --sysupgrade --quiet --noconfirm -- "$@" || return
218 elif test -f /etc/alpine-release; then
219 test $# = 0 || apk add -- "$@" || return
220 else
221 echo "$0: We don't know how to manage packages on this system" 1>&2
222 return 1
223 fi
224 }
225
226 # ? __can_install [pkgs...]
227 # Test whether it is possible to install all of the given packages with the system package manager
228 __can_install() {
229 # Refresh local package databases
230 if test -f /etc/debian_version; then
231 __silently apt-get -y update
232 elif test -f /etc/alpine-release; then
233 __silently apk update
234 elif test -f /etc/arch-release; then
235 __silently pacman --sync --refresh --quiet --noconfirm || :
236 fi
237 # If more than one package, test each one individually:
238 if test $# -ne 1; then
239 for pkg in "$@"; do
240 __can_install_1 "$pkg" || return
241 done
242 return 0
243 fi
244 __can_install_1 "$1"
245 }
246
247 __can_install_1() {
248 local package="$1"
249 # Package checks:
250 if test -f /etc/debian_version; then
251 __silently apt-cache show -- "$package"
252 return
253 elif test -f /etc/redhat-release; then
254 # "Yum" may be an alias for dnf, but this still works:
255 __silently yum info "$package"
256 return
257 elif test -f /etc/arch-release; then
258 __silently pacman --sync --info -- "$package"
259 return
260 elif test -f /etc/alpine-release; then
261 __silently apk info -- "$package"
262 return
263 elif __have_command zypper; then
264 __silently zypper info -- "$package"
265 return
266 else
267 echo "$0: We don't know how to manage packages on this system" 1>&2
268 return 1
269 fi
270 }
271
272 # ? __silently [command...]
273 # Execute the given shell command, but do it silently, supressing all output no
274 # matter what.
275 __silently() {
276 "$@" > /dev/null 2>&1
277 }
278
279 __STR_HELP='Usage:
280 __str {lower,upper}
281 __str test
282
283 Commands:
284 lower, upper
285 Convert input (stdin) to all-lowercase or all-uppercase, respectively
286
287 test <str1> (-ieq|-ine|-contains|-matches) <str2>
288 Like "test", but with additional string comparisons:
289 -ieq • case-insensitive equal
290 -ine • case-insensitive not-equal
291 -contains • Check if <str1> contains <str2>
292 -matches • Check if <str1> matches pattern <str2> (A grep -E pattern)
293 '
294 __str() {
295 local _Command="$1"
296 local _CommandIdent
297 _CommandIdent="$(echo "__str__$_Command" | sed '
298 s/-/_/g
299 s/\./__/g
300 ')"
301 shift
302 "$_CommandIdent" "$@"
303 }
304
305 __str__upper() {
306 __justStdin upper __upper "$@"
307 }
308 __upper() {
309 tr '[:lower:]' '[:upper:]'
310 }
311
312 __str__lower() {
313 __justStdin lower __lower "$@"
314 }
315 __lower() {
316 tr '[:upper:]' '[:lower:]'
317 }
318
319 __justStdin() {
320 if test $# -gt 2; then
321 __fail "Command '%s' does not take any arguments (write input into stdin)" "$1" || return
322 fi
323 "$2"
324 }
325
326 __str__help() {
327 printf %s "$__STR_HELP"
328 }
329 __str____help() {
330 __str help
331 }
332 __str___h() {
333 __str help
334 }
335 __str___help() {
336 __str help
337 }
338
339 __str__test() {
340 test "$#" -eq 3 || fail '“str test” expects three arguments (Got %d: “%s”)' $# "$*" \
341 || return
342 local lhs="$1"
343 local op="$2"
344 local rhs="$3"
345 local norm_lhs norm_rhs;
346 norm_lhs=$(echo "$lhs" | __str lower) || return
347 norm_rhs=$(echo "$rhs" | __str lower) || return
348 case $op in
349 -ieq)
350 test "$norm_lhs" = "$norm_rhs";;
351 -ine)
352 test "$norm_lhs" != "$norm_rhs";;
353 -matches)
354 printf %s "$lhs" | grep -qE -- "$rhs";;
355 -contains)
356 printf %s "$lhs" | grep -qF -- "$rhs";;
357 -*|=*)
358 # Just defer to the underlying test command
359 test "$lhs" "$op" "$rhs"
360 esac
361 }
362
363 # $ __strsub_inplace <varname> <needle> <repl>
364 # Replace each occurrence of <needle> with <repl> within the string variable <varname>
365 __strsub_inplace() {
366 test $# -eq 3 || __fail "__strsub_inplace expects three arguments (Got %s)" $# || return
367 local __strsub_varname="$1" __strsub_needle="$2" __strsub_repl="$3"
368 # Read the value of <varname> into __strsub_remaining
369 __readvar __strsub_remaining "$__strsub_varname"
370 # Accumulate into __strsub_acc
371 local __strsub_head __strsub_acc=''
372 while true; do
373 # Grab all content until the next needle:
374 __strsub_head=${__strsub_remaining%%"$__strsub_needle"*}
375 if test "$__strsub_head" = "$__strsub_remaining"; then
376 # Nothing match the needle, so we are done
377 __strsub_acc="$__strsub_acc$__strsub_remaining"
378 break
379 fi
380 # Everything after the needle:
381 __strsub_remaining=${__strsub_remaining#*"$__strsub_needle"}
382 # Accumulate the result:
383 __strsub_acc="$__strsub_acc$__strsub_head$__strsub_repl"
384 done
385 # Read the accumulated string back into the output variable:
386 __readvar "$__strsub_varname" __strsub_acc
387 }
388
389 _ESCAPES="$(printf '[][ \t\n\r\a*?!\\\$;()\\{\\}'"'"']')"
390 __quote() {
391 local __quote_input="$1"
392 # shellcheck disable=SC2295
393 local __quote_tmp="${__quote_input#*$_ESCAPES}" || return
394 if test "$__quote_input" = ""; then
395 # Empty string: Just emit empty quotes
396 printf '""'
397 return
398 elif test "$__quote_tmp" = "$__quote_input"; then
399 # No special chars, so don't quote it:
400 printf %s "$__quote_input"
401 return
402 else
403 # Special chars. Escape any inner quotes, then wrap in quotes
404 __strsub_inplace __quote_input "'" "'\\''"
405 printf "'%s'" "$__quote_input"
406 fi
407 }
408
409 # Usage: __readvar <dest> <varname>
410 # Read the value of the variable named by <varname> into a variable <dest>
411 __readvar() {
412 local __readvar_tmp
413 eval "__readvar_tmp=\$(printf %s. \"\${$2}\"); $1=\${__readvar_tmp%.}"
414 }
415
416 cmd=$1
417 shift
418 "$cmd" "$@"