-
Notifications
You must be signed in to change notification settings - Fork 2
/
stdlib.sh
3805 lines (3079 loc) · 108 KB
/
stdlib.sh
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
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
#! /usr/bin/env bash
#
# Copyright 2013-2017 Stuart Shelton
# Distributed under the terms of the GNU General Public License v2
#
# stdlib.sh standardised shared shell functions...
set +o xtrace
###############################################################################
#
# stdlib.sh - How to load ...
#
###############################################################################
# Pull this file into external scripts as follows:
#
: >/dev/null <<\EOC
# --- CUT HERE ---
# stdlib.sh should be in /usr/local/lib/stdlib.sh, which can be found as
# follows by scripts located in /usr/local/{,s}bin/...
declare std_LIB='stdlib.sh'
type -pf 'dirname' >/dev/null 2>&1 || function dirname() { : ; }
# shellcheck disable=SC2153
for std_LIBPATH in \
"$( dirname -- "${BASH_SOURCE:-${0:-.}}" )" \
'.' \
"$( dirname -- "$( type -pf "${std_LIB}" 2>/dev/null )" )" \
"$( dirname -- "${BASH_SOURCE:-${0:-.}}" )/../lib" \
'/usr/local/lib' \
${FPATH:+${FPATH//:/ }} \
${PATH:+${PATH//:/ }}
do
if [[ -r "${std_LIBPATH}/${std_LIB}" ]]; then
break
fi
done
unset -f dirname
# Attempt to use colourised output if the environment indicates that this is
# an appropriate choice...
[[ -n "${LS_COLORS:-}" ]] &&
export STDLIB_WANT_COLOUR="${STDLIB_WANT_COLOUR:-1}"
# We want the non if-then-else functionality here - the third element should be
# executed if either of the first two fail...
#
# N.B. The shellcheck 'source' option is only valid with shellcheck 0.4.0 and
# later...
#
# shellcheck disable=SC1091,SC2015
# shellcheck source=/usr/local/lib/stdlib.sh
[[ -r "${std_LIBPATH}/${std_LIB}" ]] && source "${std_LIBPATH}/${std_LIB}" || {
# shellcheck disable=SC2154
echo >&2 "FATAL: Unable to source ${std_LIB} functions:" \
"${?}${std_ERRNO:+ (ERRNO ${std_ERRNO})}"
exit 1
}
# --- CUT HERE ---
EOC
# If you wish to ensure that a given minimum version of stdlib.sh is present
# from within a script, then this can be acheieved as follows (substituting
# versions '2.0.0' and '2.0.4' as appropriate):
#
: >/dev/null <<\EOC
# --- CUT HERE ---
# std_RELEASE was only added in release 1.3, and std::vcmp appeared immediately
# after in release 1.4...
if [[ "${std_RELEASE:-1.3}" == "1.3" ]] || std::vcmp "${std_RELEASE}" -lt "2.0.0"; then
die "stdlib is too old - please update '${std_LIBPATH}/${std_LIB}' to at least v2.0.0" # for API 2
elif std::vcmp "${std_RELEASE}" -lt "2.0.4"; then
warn "stdlib is outdated - please update '${std_LIBPATH}/${std_LIB}' to at least v2.0.4" # for std_LASTOUTPUT
fi
# --- CUT HERE ---
EOC
# Externally set control-variables:
#
# STDLIB_WANT_API - Specify the stdlib API to adhere to, currently only
# API versions '1' and '2' are supported values;
#
# Set (to '1') to activate:
#
# STDLIB_WANT_MEMCACHED - Load native memcached functions, requires presence of
# - external '/usr/local/lib/memcached.sh' script;
# STDLIB_WANT_COLOUR - Enable coloured output;
# STDLIB_WANT_WORDWRAP - Set to zero to explicitly disable word-wrapping,
# leave unset to word-wrap if the terminal width can be
# determined, or set to one to explicitly force word-
# wrapping - to 80 columns if no width can be
# determined;
# (Invoking 'export COLUMNS' prior to executing a
# a script which in turn calls stdlib.sh may help)
#
# STDLIB_COLOUR_MAP - Specify the path to an optional custom colour map
# file, defaulting to '/etc/stdlib/colour.map';
#
# Exported control-variables:
#
# STDLIB_HAVE_STDLIB - Set once stdlib functions have been loaded;
# STDLIB_HAVE_BASH_4 - Set if interpreter is bash-4 or above;
# STDLIB_HAVE_ERRNO - Set if errno functions have been initialised;
# STDLIB_HAVE_MEMCACHED - Set if bash memcached interace is available.
# STDLIB_HAVE_COLOUR - Enable coloured output;
#
# Externally referenced variables:
#
# std_USAGE - Specify simple usage strings. For more complex
# requirements, instead override usage-message;
# std_ERRNO - Return an additional error-indication from a
# function.
# std_LASTOUTPUT - A copy of the last output written, to aid in output
# formatting (in order to determine whether the last
# thing written was a blank line, for example...)
#
###############################################################################
#
# stdlib.sh - Initialisation
#
###############################################################################
# Only load stdlib once, and provide support for loading stdlib from bashrc to
# reduce startup times...
#
if [[ "$( type -t 'std::sentinel' 2>&1 )" == 'function' ]]; then # {{{
# We've already initialised, and all funcions are (assumed to be)
# present.
# ... however, if we're the child of a parent which included stdlib,
# then we appear to inherit all functions and non-array variables, but
# lose (at least) associative arrays. In this case, we need to re-load
# these data-structures. This does mean that we can no longer unset
# one-shot functions for efficiency's sake :(
# N.B. __STDLIB_SHLVL is initialised below on first load, and so should
# still be present (and set) if std::sentinel exists as a function
if ! (( __STDLIB_SHLVL == SHLVL )); then
__STDLIB_oneshot_errno_init
__STDLIB_oneshot_colours_init
# ... also reset NAME, which likely now refers to the parent
# also:
NAME="$( basename -- "${0:-${std_LIB:-stdlib.sh}}" )"
[[ "${NAME:-}" == "$( basename -- "${SHELL:-bash}" )" ]] &&
NAME="${std_LIB:-stdlib.sh}"
fi
else # See line 3339
declare -i __STDLIB_SHLVL=${SHLVL:-1}
if [[ -n "${STDLIB_HAVE_STDLIB:-}" ]]; then
# We only get here if std::sentinel (see above) is unset but we still
# have STDLIB_HAVE_STDLIB set - this has been observed post-Shellshock
# due to the security changes applied to bash...
if [[ -z "${NAME:-}" ]]; then
# shellcheck disable=SC2031
if [[ -z "${std_LIB:-}" ]]; then
std_LIB="${std_LIB:-stdlib.sh}"
fi
NAME="$( basename -- "${0:-${std_LIB}}" )"
[[ "${NAME:-}" == "$( basename -- "${SHELL:-bash}" )" ]] &&
NAME="${std_LIB}"
fi
echo >&2
echo >&2 "WARN: ${NAME} variables have been imported, but function definitions are"
echo >&2 'WARN: missing - parent shell may be running in restricted, setuid, or'
echo >&2 'WARN: privileged mode.'
echo >&2
echo >&2 "NOTICE: Re-executing ${NAME} to re-generate all functions."
echo >&2
fi # }}}
###############################################################################
#
# stdlib.sh - Release notes
#
###############################################################################
# What API version are we exporting?
#
# The version format used for this project is:
# <Highest API version>.<Major version>[.<Minor version>]
#
#export std_RELEASE='1.3' # Initial import;
#export std_RELEASE='1.4' # Add std::parseargs;
#export std_RELEASE='1.4.1' # Add std::define;
#export std_RELEASE='1.4.2' # Add std::getfilesection, std::configure;
#export std_RELEASE='1.4.4' # Re-load stdlib if functions aren't present due
# to bash privileged_mode changes;
#export std_RELEASE='1.4.5' # Update exit-code and and add HTTP mapping
# functions;
#export std_RELEASE='1.4.6' # Fix issues identified by shellcheck.net, and
# improve MacOS compatibility;
#export std_RELEASE='1.4.7' # Fix warnings identified by shellcheck.net, add
# std::wordsplit;
#export std_RELEASE='1.5.0' # Add std::inherit, finally make errno functions
# work! Set std_ERRNO where appropriate;
#export std_RELEASE='1.5.1' # Added support for coloured output via
# std::colour and add std::findfile, fix
# std::parseargs to handle multi-element input and
# to return arrays (which is luckily non API-
# breaking);
#export std_RELEASE='2.0.0' # std::inherit becomes the first function to be
# available in multiple API versions. std::wrap
# now appends a lower-case (optional) prefix to
# wrapped follow-on lines. Many fixes for correct
# operation when inheriting stdlib from parent
# shell. std::requires now works properly ;)
#export std_RELEASE='2.0.1' # std::*mktemp now support '-directory' to cause
# creation a temporary directory. std::parseargs
# can now handle defined parameters with no value;
#export std_RELEASE='2.0.2' # Make wrapping via std::wrap optional;
#export std_RELEASE='2.0.3' # Ensure that required shell tools are available,
# and that traps are correctly initialised.
#export std_RELEASE='2.0.4' # Add std_LASTOUTPUT support.
#export std_RELEASE='2.0.5' # Enhance representation of std_TAB and std_NL,
# add std_CR and std_LF (as GitHub is unhappy with
# embedded carriage-return characters).
export std_RELEASE='2.0.6' # Disable tracing for internal functions, unless
# DEBUG=2, to aid external debugging.
readonly std_RELEASE
###############################################################################
#
# stdlib.sh - Debugging options
#
###############################################################################
declare std_DEBUG
# Standard usage is:
#
std_DEBUG="${DEBUG:-0}"
declare std_TRACE
# Standard usage is:
#
# shellcheck disable=SC2034
std_TRACE="${TRACE:-0}"
#
# ... and then include:
#
: >/dev/null <<\EOC
# --- CUT HERE ---
(( std_TRACE )) && set -o xtrace
# --- CUT HERE ---
EOC
#
# ... near the top of the calling script.
#
# A good way to tell whether 'xtrace' is enabled is `[[ "${-/x}" != "${-}" ]]`
###############################################################################
#
# stdlib.sh - Logging
#
###############################################################################
# If this is not overridden, then logging will be disabled:
#
declare std_LOGFILE='/dev/null'
#
# Note that std_LOGFILE may also be given the special value of "syslog" to use
# 'logger'(1) to send messages to any local syslogd.
###############################################################################
#
# stdlib.sh - Notes
#
###############################################################################
# All scripts should end with the following lines (or similar):
#
: >/dev/null <<\EOC
# --- CUT HERE ---
function main() {
...
} # main
main "${@:-}"
exit ${?}
# vi: set syntax=sh colorcolumn=80 foldmethod=marker:
# --- CUT HERE ---
EOC
# A note on standard/reserved return/exit codes with special meanings:
#
# Code Meaning
# ----------- -------
# 1 General error
# 2 Misuse of shell builtin (missing keyword or command, or
# permission problem)
# 126 Command invoked cannot execute (command is not an executable?)
# 127 "command not found" - specified command does not exist in $PATH
# 128 Invalid argument to exit
# 129 to 192 Exited due to signal 'x' where 'x' is ( ${?} - 128 )
# e.g. 130 == 2 + 128 == SIGINT (see `kill -l`) == Ctrl + C
# 255 Exit status out of range (e.g. `exit -1` is invalid)
#
# If possible, code should either try to employ these conventions or, at least,
# avoid the above reserved values - use of `exit 127`, for example, could be
# very confusing or misleading to the user or to other tools.
#
# Alternatively, attempt to exclusively use return-codes 0 and 1 to flag
# success and failure respectively, and then use the ERRNO functions below to
# provide richer context. stdlib.sh uses this convention, with 'return 255'
# appearing for debug purposes to signal the execution of code thought to be
# unreachable.
###############################################################################
#
# stdlib.sh - Setup and standard functions
#
########################################################################### {{{
# Throw an error if parameter-expansion occurs with an unset variable.
#
# Gentleman, start your debuggers ;)
#
set -u
# Try to impose sane handling of the '!' character...
#
set +o histexpand
# Prevent non-matching shell globs from being literally interpreted...
#
#shopt -qs nullglob
# ... or abort when a glob fails to match anything:
shopt -qs failglob
# Use 'output' rather than 'echo' to clearly differentiate user-visible
# output from pipeline-intermediate commands.
#
function output() {
local -i std_x_state=0
! (( std_DEBUG & 2 )) && [[ "${-/x}" != "${-}" ]] && set +o xtrace && std_x_state=1
local flags='-e'
if ! [[ -n "${*:-}" ]]; then
echo
std_LASTOUTPUT=""
else
[[ " ${1:-} " == ' -n ' ]] && { flags+='n' ; shift ; }
echo ${flags} "${*}"
std_LASTOUTPUT="${*}"
fi
std_ERRNO=0 # instead use 'std_ERRNO=$( errsymbol ENOERROR )'
(( std_x_state )) && set -o xtrace
return 0
} # output
# Use 'respond' rather than 'echo' to clearly differentiate function results
# from pipeline-intermediate commands.
#
function respond() {
local -i std_x_state=0
! (( std_DEBUG & 2 )) && [[ "${-/x}" != "${-}" ]] && set +o xtrace && std_x_state=1
[[ -n "${*:-}" ]] && echo "${*}"
std_ERRNO=0 # instead use 'std_ERRNO=$( errsymbol ENOERROR )'
(( std_x_state )) && set -o xtrace
return 0
} # respond
# Use of aliases requires more investigation to ensure reliability.
#
## N.B.: Set this in order to have aliases interpreted by scripts...
##
##shopt -qs expand_aliases
##alias output='echo -e'
##alias respond='echo'
# }}}
###############################################################################
#
# stdlib.sh - Standard functions and variables
#
########################################################################### {{{
unalias cp >/dev/null 2>&1
unalias ls >/dev/null 2>&1
unalias mv >/dev/null 2>&1
unalias rm >/dev/null 2>&1
export std_PREFIX="${std_PREFIX:-/usr/local}"
export std_BINPATH="${std_PREFIX}/bin"
# N.B.: Earlier auto-discovered value for std_LIBPATH is replaced here:
export std_LIBPATH="${std_PREFIX}/lib"
# ${0} may equal '-bash' if invoked directly, in which case some tools may fail
# if they try to interpret '-b ash'.
#
# At this point, before we've been able to run std::requires, try to work out
# our name without relying on external binaries such as 'basename' or
# 'dirname'...
#
declare NAME="${0:-${std_LIB:-stdlib.sh}}"
NAME="${NAME##*/}"
if [[ -n "${SHELL:-}" ]]; then
[[ "${NAME:-}" == "${SHELL##*/}" || "${NAME:-}" == "-${SHELL##*/}" ]] &&
NAME="${std_LIB:-stdlib.sh}"
else # [[ -z "${SHELL:-}" ]]; then
[[ "${NAME:-}" == 'bash' || "${NAME:-}" == '-bash' ]] &&
NAME="${std_LIB:-stdlib.sh}"
fi
export NAME
# Ensure a sane sorting order...
export LC_ALL='C'
# These values should make certain code much clearer...
declare std_TAB std_CR std_LF std_NL
std_TAB="$( printf "\t" )"
std_CR="$( printf "\r" )"
std_LF="$( printf "\n" )"
std_NL="${std_LF}"
export std_TAB std_CR std_LF std_NL
# We don't want to rely on $SHELL so, as an alternative, this should work - but
# is also a little bit scary...
#
declare -i STDLIB_HAVE_BASH_4=0
export STDLIB_HAVE_ERRNO=0
export STDLIB_HAVE_STDLIB=0
export STDLIB_HAVE_MEMCACHED=0
export std_ERRNO=0 # instead use 'std_ERRNO=$( errsymbol ENOERROR )'
export std_LASTOUTPUT=""
declare -a __STDLIB_OWNED_FILES
# }}}
###############################################################################
#
# stdlib.sh - Shell detection
#
###############################################################################
# N.B.: In general, we don't want to reference ${0} as it may be unreliable if
# we're sourced from a script itself sourced from another script... but
# in this case the ultimate parent does impose the interpreter.
#
function __STDLIB_oneshot_get_bash_version() { # {{{
set +o xtrace
local parent="${0:-}"
local int shell version
if [[ -n "${BASH_VERSION:-}" ]]; then
if (( ${BASH_VERSION%%.*} >= 4 )); then
STDLIB_HAVE_BASH_4=1
else
STDLIB_HAVE_BASH_4=0
fi
export STDLIB_HAVE_BASH_4
std_ERRNO=0 # instead use 'std_ERRNO=$( errsymbol ENOERROR )'
return ${STDLIB_HAVE_BASH_4}
fi
# Please note - this function may have unintended consequences if
# invoked from a script which has an interpreter which causes a
# permanent state-change if executed with '--version' as a parameter.
if [[ -z "${parent:-}" || "$( basename -- "${parent#-}" )" == 'bash' ]]; then
# If stdlib.sh is sourced directly, $0 will be 'bash' (or
# another shell name, which should be listed in /etc/shells)
#
if [[ -n "${SHELL:-}" ]]; then
shell="$( basename "${SHELL}" )"
else
shell='bash' # We'll assume...
fi
elif [[ -r "${parent}" ]]; then
# Our interpreter should be some valid shell...
int="$( head -n 1 "${parent}" )"
local sed='sed -r'
${sed} '' >/dev/null 2>&1 <<<'' || sed='sed -E' # ` # <- Ubuntu syntax highlight fail
int="$( ${sed} 's|^#\! ?||' <<<"${int}" )"
unset sed
if [[ \
"${int:0:4}" == 'env ' ||
"${int:0:9}" == '/bin/env ' ||
"${int:0:13}" == '/usr/bin/env ' \
]]; then
shell="$( cut -d' ' -f 2 <<<"${int}" )"
else
shell="$( cut -d' ' -f 1 <<<"${int}" )"
fi
else
warn 'Unknown interpretor'
fi
if [[ -n "${shell:-}" ]]; then
# XXX: Use std::readlink for cross-platform support...
shell="$( readlink -e "$( type -pf "${shell:-bash}" 2>/dev/null )" )"
if [[ -n "${shell:-}" && -x "${shell}" ]]; then
version="$( "${shell}" --version 2>&1 | head -n 1 )" ||
die 'Cannot determine version for' \
"interpreter '${shell}'"
if grep -q '^GNU bash, version ' >/dev/null 2>&1 \
<<<"${version}"; then
if ! grep -q " version [0-3]" >/dev/null 2>&1 \
<<<"${version}"; then
STDLIB_HAVE_BASH_4=1
fi
# N.B.: Don't abort if we can't determine our
# interpretor's capabilities - simply don't set
# STDLIB_HAVE_BASH_4.
#
#else
# die "Cannot determine version for interpreter '${BASH}' (from '${version}')"
fi
#else
# die "Cannot execute interpreter '${int}'"
fi
unset version shell int
#else
# die "Cannot locate this script (tried '${0}')"
fi
export STDLIB_HAVE_BASH_4
std_ERRNO=0 # instead use 'std_ERRNO=$( errsymbol ENOERROR )'
return ${STDLIB_HAVE_BASH_4}
} # __STDLIB_oneshot_get_bash_version # }}}
###############################################################################
#
# stdlib.sh - Validate syntax
#
###############################################################################
function __STDLIB_oneshot_syntax_check() { # {{{
set +o xtrace
local script
if ! (( STDLIB_HAVE_BASH_4 )) || ! [[ -n "${SHELL:-}" && "${SHELL}" =~ bash$ ]]; then
std_ERRNO=$( errsymbol ENOEXE )
return 0
else
local -Ai seen
while read -r script; do
(( ${seen[${script}]:-0} )) && continue
seen[${script}]=1
if ! [[ -s "${script}" ]]; then
(( std_DEBUG )) && echo >&2 "DEBUG: Skipping syntax validation of unreadable script '${script}' ..."
else
(( std_DEBUG )) && echo >&2 "DEBUG: Syntax validating script '${script}' ..."
"${SHELL}" -n "${script}" || {
echo >&2 "FATAL: Syntax error detected in '${script}'"
std_ERRNO=5 # instead use 'std_ERRNO=$( errsymbol ESYNTAX )'
return 1
}
fi
done < <( printf '%s\n' "${BASH_SOURCE[@]:-}" /usr/local/lib/stdlib.sh | sort | uniq )
fi
std_ERRNO=0 # instead use 'std_ERRNO=$( errsymbol ENOERROR )'
return 0
} # __STDLIB_oneshot_syntax_check # }}}
###############################################################################
#
# stdlib.sh - Initialise coloured output
#
###############################################################################
## shellcheck gets confused by the constants used below...
# shellcheck disable=SC2154
function __STDLIB_oneshot_colours_init() { # {{{
set +o xtrace
local file key value val
local -l section
local -i fg bg mode
if ! (( ${STDLIB_WANT_COLOUR:-0} )); then
std_ERRNO=0 # instead use 'std_ERRNO=$( errsymbol ENOERROR )'
return 0
fi
# For efficiency purposes, we'll store colour mappings in an
# associatve array and so only support colouration with bash-4
#
if ! (( STDLIB_HAVE_BASH_4 )); then
STDLIB_WANT_COLOUR=0
std_ERRNO=$( errsymbol EENV )
return 1
fi
if ! (( $( tput cols 2>/dev/null || echo '0' ) )); then
# We're not connected to a terminal
STDLIB_WANT_COLOUR=0
std_ERRNO=$( errsymbol EACCESS )
return 0
fi
# XXX: Somehow, this breaks standard shell '-e' and '-x' functions!?
#tput init 2>/dev/null
# We can't use -Agix here, because we can't then differentiate between
# unset and zero (black)...
# XXX: It might be worth storing SGR values rather than colour indices
# here to avoid this ambiguity?
declare -Agx __STDLIB_COLOURMAP
# TODO: Support 16 colours using values 90 (fg-black) to 107 (bg-white)
# and 88/256 colour mode using '38;5;<bg>' and '48;5;<fg>' escape
# sequences...
#
# black is \e[30m.
local -i black=0 red=1 green=2 yellow=3 blue=4 magenta=5 cyan=6 white=7
local -i default=9
local -i bold=1 underline=4 inverse=7
# TODO: Read in categories from config file?
# __STDLIB_COLOURMAP['type']=$(( ( mode << 16 ) + ( background << 8 ) + foreground ))
#
__STDLIB_COLOURMAP['debug']=$(( cyan ))
__STDLIB_COLOURMAP['error']=$(( red ))
__STDLIB_COLOURMAP['exec']=$(( magenta ))
__STDLIB_COLOURMAP['fail']=$(( red ))
__STDLIB_COLOURMAP['fatal']=$(( ( bold << 16 ) + red ))
__STDLIB_COLOURMAP['info']=$(( white ))
__STDLIB_COLOURMAP['note']=$(( blue ))
__STDLIB_COLOURMAP['okay']=$(( green ))
__STDLIB_COLOURMAP['warn']=$(( yellow ))
file="$( std::findfile -app stdlib -name colour.map -dir /etc "${STDLIB_COLOUR_MAP:-}" )"
if (( 0 == std_ERRNO )) && [[ -s "${file:-}" ]]; then
section="$( std::getfilesection "${file}" 'colours' | sed 's/#.*$//' | grep -v '^\s*$' )"
(( std_DEBUG & 2 )) && debug "Read $( wc -l <<<"${section}" ) lines of configuration:"
(( std_DEBUG & 2 )) && debug "${section}"
(( std_ERRNO )) && return 1
for key in debug error exec fail fatal info note okay warn; do
value="$( grep -m 1 "^\s*${key}\s*=\s*[^[:space:]]\+\s*$" <<<"${section}" | cut -d'=' -f 2- | sed -r 's/\s+//g' )"
(( std_DEBUG & 2 )) && debug "Read '${value:-}' for key '${key}'"
if [[ -n "${value:-}" ]]; then
case "${value}" in
*,*,*)
val="$( cut -d',' -f 1 <<<"${value}" )"
fg=${!val:-}
val="$( cut -d',' -f 2 <<<"${value}" )"
bg=${!val:-}
val="$( cut -d',' -f 3 <<<"${value}" )"
mode=${!val:-}
;;
*,*)
val="$( cut -d',' -f 1 <<<"${value}" )"
fg=${!val:-}
val="$( cut -d',' -f 2 <<<"${value}" )"
bg=${!val:-}
mode=0
;;
*)
val="${value}"
fg=${!val:-}
bg=$(( default ))
mode=0
;;
esac
if (( fg )); then
__STDLIB_COLOURMAP["${key}"]=$(( ( mode << 16 ) + ( bg << 8 ) + fg ))
fi
fi
done
else
debug 'Colour-map file not found, using default colours only'
fi
# shellcheck disable=2034
typeset -gix STDLIB_HAVE_COLOUR=1
std_ERRNO=0 # instead use 'std_ERRNO=$( errsymbol ENOERROR )'
return 0
} # __STDLIB_oneshot_colours_init # }}}
###############################################################################
#
# stdlib.sh - Standard overridable functions - Initialisation & clean-up
#
###############################################################################
# This function MUST be overridden, and contain all script code except for
# variable and function declarations.
#
# The code to include stdlib.sh may appear at top-level, within a separate
# function, or within main().
#
# N.B.: No API-version declaration here - this is fixed.
#
function main() {
die 'No override main() function defined'
} # main
# This function may be overridden
#
function __STDLIB_API_1_std::cleanup() { # {{{
local -i std_x_state=0
! (( std_DEBUG & 2 )) && [[ "${-/x}" != "${-}" ]] && set +o xtrace && std_x_state=1
# N.B.: 'rc' initially contains ${?}, not ${1}
local -i rc=${?}
local file
if [[ -n "${1:-}" ]]; then
if [[ "${1}" == '0' ]]; then
rc=${1}; shift
elif (( ${1} )); then
rc=${1}; shift
fi
fi
# Remove any STDLIB-generated temporary files and exit.
for file in "${__STDLIB_OWNED_FILES[@]:-}"; do
if [[ -n "${file:-}" && -e "${file}" ]]; then
# TODO: It would be nice to run stdlib.sh functions as
# a dedicated unprivileged user by default, so
# that cleanup couldn't be maliciously or even
# accidentally used to cause system damage if
# run by UID 0...
# XXX: Use std::readlink for cross-platform support...
if [[ "$( readlink -e "${file}" )" == '/' ]]; then
die "Attempt made to cleanup/remove '/' - serious bug or malicious code suspected"
fi
if rmdir "${file}" >/dev/null 2>&1; then
(( std_DEBUG & 2 )) && debug "${FUNCNAME[0]##*_} succeeded removing empty directory '${file}'"
elif rm -f "${file}" >/dev/null 2>&1; then
(( std_DEBUG & 2 )) && debug "${FUNCNAME[0]##*_} succeeded removing file '${file}'"
elif rm -rf "${file}" >/dev/null 2>&1; then
(( std_DEBUG & 2 )) && debug "${FUNCNAME[0]##*_} succeeded removing non-empty file or directory '${file}'"
else
warn "${FUNCNAME[0]##*_} unable to remove filesystem object '${file}': ${?}"
# We'd expect this to fail again, but tell us
# what happened. This is arguably less correct
# than capturing the output in the first place,
# but the distinction is likely marginal...
error "$( rm -rv "${file}" 2>&1 )"
(( rc )) || (( rc++ ))
fi
else
(( std_DEBUG & 2 )) && [[ -n "${file:-}" ]] && debug "${FUNCNAME[0]##*_} unable to remove missing object '${file}'"
fi
done
unset file
if [[ "${BASH_SOURCE:-${0:-}}" =~ ${std_LIB:-stdlib.sh}$ ]]; then
trap - EXIT QUIT TERM
else
trap - EXIT INT QUIT TERM
fi
[[ -n "${__STDLIB_SIGEXIT:-}" ]] && trap ${__STDLIB_SIGEXIT} EXIT
[[ -n "${__STDLIB_SIGINT:-}" ]] && trap ${__STDLIB_SIGINT} INT
[[ -n "${__STDLIB_SIGQUIT:-}" ]] && trap ${__STDLIB_SIGQUIT} QUIT
[[ -n "${__STDLIB_SIGTERM:-}" ]] && trap ${__STDLIB_SIGTERM} TERM
(( std_x_state )) && set -o xtrace # ... for code trapping exit?
# 'rc' is numeric, and therefore not subject to word-splitting
# shellcheck disable=SC2086
exit ${rc}
} # __STDLIB_API_1_std::cleanup # }}}
# This function should be overridden, or the ${std_USAGE} variable defined
#
function __STDLIB_API_1_usage-message() { # {{{
warn "${FUNCNAME[0]##*_} invoked - please use 'std::usage-message' instead"
std::usage-message "${@:-}"
} # __STDLIB_API_1_usage-message # }}}
# Heavyweight compatibility work-around:
declare __STDLIB_usage_message_definition
__STDLIB_usage_message_definition="$( typeset -f usage-message )"
export __STDLIB_usage_message_definition
# This function must be overridden, or the ${std_USAGE} variable defined
#
function __STDLIB_API_1_std::usage-message() { # {{{
die 'No override std::usage-message() function defined'
local -i std_x_state=0
! (( std_DEBUG & 2 )) && [[ "${-/x}" != "${-}" ]] && set +o xtrace && std_x_state=1
# The following output will appear in-line after 'Usage: ${NAME} '...
output 'Command summary, e.g. "-f|--file <filename> [options]"'
output <<-\END
Further instructions here, e.g.
-f : Process the specified <filename>
-h : Show this help information
END
std_ERRNO=0 # instead use 'std_ERRNO=$( errsymbol ENOERROR )'
(( std_x_state )) && set -o xtrace
return 0
} # __STDLIB_API_1_std::usage-message # }}}
# This function may be overridden
#
function __STDLIB_API_1_std::usage() { # {{{
local -i std_x_state=0
! (( std_DEBUG & 2 )) && [[ "${-/x}" != "${-}" ]] && set +o xtrace && std_x_state=1
local rc="${1:-0}" ; shift
# Optional arguments should be denoted as '[parameter]', required
# arguments as '<parameter>'. Short and long options should be
# separated by a vertical-bar, e.g.
# showfiles [-l|--long] <directory>
output -n "Usage: ${NAME} "
if [[ -n "${std_USAGE:-}" ]]; then
output "${std_USAGE}"
else
if [[ "$( typeset -f usage-message )" == "${__STDLIB_usage_message_definition}" ]]; then
std::usage-message
else
usage-message
fi
fi
(( std_x_state )) && set -o xtrace
# 'rc' is numeric, and therefore not subject to word-splitting
# shellcheck disable=SC2086
__STDLIB_API_1_std::cleanup ${rc}
} # __STDLIB_API_1_std::usage # }}}
###############################################################################
#
# stdlib.sh - Standard overridable functions - Logging functions
#
###############################################################################
function __STDLIB_API_1_std::wrap() { # {{{
local -i std_x_state=0
! (( std_DEBUG & 2 )) && [[ "${-/x}" != "${-}" ]] && set +o xtrace && std_x_state=1
local prefix="${1:-}" ; shift
local text="${*:-}"
local -i wrap=$(( ${STDLIB_WANT_WORDWRAP:-1} ))
[[ -n "${prefix}" && -z "${text}" ]] && {
text="${prefix}"
prefix=""
}
[[ -n "${text:-}" ]] || {
std_ERRNO=$( errsymbol EARGS )
(( std_x_state )) && set -o xtrace
return 1
}
# It turns out that working out the width of the current terminal width
# is remarkably difficult, and differs between various implementations.
# 'tput cols' is fairly consistent in terms of which OS support it, but
# doesn't appear to provide a value under non-interactive use. 'stty'
# is able to output dimensions in a wider range of circumstances, but
# must be invoked as 'stty --file /dev/stdin' or 'stty -F /dev/stdin'
# on Linux, but 'stty -f /dev/stdin' on macOS (where the order of
# arguments is also significant).
# N.B.: It may be necessary to 'export COLUMNS' before this
# works - this variable isn't exported to scripts by default, and
# is lost on invocation.
#local -i columns=${COLUMNS:-$( stty size --file /dev/stdin 2>/dev/null | cut -d' ' -f 2 )}
local -i columns=${COLUMNS:-$( tput cols 2>/dev/null )}
if ! (( columns )); then
# If invoked with a specific indication that word-wrapping is
# required, then wrap to 80 columns - otherwise, don't wrap at
# all...
if [[ -z "${STDLIB_WANT_WORDWRAP:-}" ]]; then
wrap=0
else
columns=80
fi
fi
if [[ -n "${prefix:-}" ]]; then
# Attempt to sanitise input to sed, which can break in many
# non-obvious ways...
prefix="$( LC_ALL=C sed -e 's/[^a-zA-Z0-9,._+@%/-]/\\&/g; 1{$s/^$/""/}; 1!s/^/"/; $!s/$/"/' <<<"${prefix}" )"
local -l lprefix="${prefix}"
if (( wrap )) && (( columns > ( ${#prefix} + 2 ) )); then
output "${text}" \
| fold -sw "$(( columns - ( ${#prefix} + 1 ) ))" \
| sed "s|^|${lprefix} | ; 1{s|^${lprefix}|${prefix}|}"
std_LASTOUTPUT="$( sed "s|^|${lprefix} | ; 1{s|^${lprefix}|${prefix}|}" <<<"${text}" )"
else
output "${text}" \
| sed "s|^|${prefix} | ; 1{s|^${lprefix}|${prefix}|}"
std_LASTOUTPUT="$( sed "s|^|${prefix} | ; 1{s|^${lprefix}|${prefix}|}" <<<"${text}" )"
fi
else
if (( wrap )) && (( columns > 1 )); then
output "${text}" \
| fold -sw "$(( columns - 1))"
else
output "${text}"
fi
fi
std_ERRNO=0 # instead use 'std_ERRNO=$( errsymbol ENOERROR )'
(( std_x_state )) && set -o xtrace
return 0
} # __STDLIB_API_1_std::wrap # }}}
function __STDLIB_API_1_std::log() { # {{{
local -i std_x_state=0
! (( std_DEBUG & 2 )) && [[ "${-/x}" != "${-}" ]] && set +o xtrace && std_x_state=1
local prefix="${1:-${std_LIB}}" ; shift
local data="${*:-}" message
# Assume that log messages should be written to a file (unless we're
# debugging) ... otherwise, use note(), warn(), or error() to output
# to screen.
if [[ -z "${data:-}" ]]; then
data="$( cat - )"
fi
[[ -n "${data:-}" ]] || {
std_ERRNO=$( errsymbol EARGS )
(( std_x_state )) && set -o xtrace
return 1
}
data="$( sed 's/\r//' <<<"${data}" )"
if [[ "${std_LOGFILE:-}" == 'syslog' ]]; then
# We'll emulate 'logger -i' here, as we need to return and so
# can't use 'exec logger' to maintain PID...
message="[${$}]: ${prefix} ${data}"