#! /usr/bin/env bash # ___________________________________________________________________________ # # # # BashLIB -- A library for Bash scripting convenience. # # # # # # Licensed under the Apache License, Version 2.0 (the "License"); # # you may not use this file except in compliance with the License. # # You may obtain a copy of the License at # # # # http://www.apache.org/licenses/LICENSE-2.0 # # # # Unless required by applicable law or agreed to in writing, software # # distributed under the License is distributed on an "AS IS" BASIS, # # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # # See the License for the specific language governing permissions and # # limitations under the License. # # ___________________________________________________________________________ # # # # # # Copyright 2007-2013, lhunath # # * http://www.lhunath.com # # * Maarten Billemont # # # # ______________________________________________________________________ # | | # | .: TABLE OF CONTENTS :. | # |______________________________________________________________________| # # chr decimal # Outputs the character that has the given decimal ASCII value. # # ord character # Outputs the decimal ASCII value of the given character. # # hex character # Outputs the hexadecimal ASCII value of the given character. # # unhex character # Outputs the character that has the given decimal ASCII value. # # max numbers... # Outputs the highest of the given numbers. # # min numbers... # Outputs the lowest of the given numbers. # # totime "YYYY-MM-DD HH:MM:SS.mmm"... # Outputs the number of milliseconds in the given date string(s). # # exists application # Succeeds if the application is in PATH and is executable. # # eol message # Return termination punctuation for a message, if necessary. # # hr pattern [length] # Outputs a horizontal ruler of the given length in characters or the terminal column length otherwise. # # cloc # Outputs the current cursor location as two space-separated numbers: row column. # # readwhile command [args] # Outputs the characters typed by the user into the terminal's input buffer while running the given command. # # log [format] [arguments...] # Log an event at a certain importance level. # The event is expressed as a printf(1) format argument. # # ask [-c optionchars|-d default] [-s|-S maskchar] message... # Ask a question and read the user's reply to it. Then output the result on stdout. # # trim lines ... # Trim the whitespace off of the beginning and end of the given lines. # # reverse [-0|-d delimitor] [elements ...] [<<< elements] # Reverse the order of the given elements. # # order [-0|-d char] [-[cC] isAscending|-n] [-t number] [elements ...] [<<< elements] # Orders the elements in ascending order. # # mutex file # Open a mutual exclusion lock on the file, unless another process already owns one. # # pushjob [poolsize] command # Start an asynchronous command within a pool, waiting for space in the pool if it is full. # # fsleep time # Wait for the given (fractional) amount of seconds. # # showHelp name description author [option description]... # Generate a prettily formatted usage description of the application. # # shquote [-e] [argument...] # Shell-quote the arguments to make them safe for injection into bash code. # # requote [string] # Escape the argument string to make it safe for injection into a regex. # # shorten [-p pwd] path [suffix]... # Shorten an absolute path for pretty printing. # # up .../path|num # Walk the current working directory up towards root num times or until path is found. # # buildarray name terms... -- elements... # Create an array by adding all the terms to it for each element, replacing {} terms by the element. # # inArray element array # Checks whether a certain element is in the given array. # # xpathNodes query [files...] # Outputs every xpath node that matches the query on a separate line. # # hideDebug [on|off] # Toggle Bash's debugging mode off temporarily. # # stackTrace # Output the current script's function execution stack. # _tocHash=71e13f42e1ea82c1c7019b27a3bc71f3 # ______________________________________________________________________ # | | # | .: GLOBAL CONFIGURATION :. | # |______________________________________________________________________| # Unset all exported functions. Exported functions are evil. while read _ _ func; do command unset -f "$func" done < <(command declare -Fx) { shopt -s extglob shopt -s globstar } 2>/dev/null ||: # Generate Table Of Contents genToc() { local line= comments=() usage= whatis= lineno=0 out= outhash= outline= while read -r line; do (( ++lineno )) [[ $line = '#'* ]] && comments+=("$line") && continue [[ $line = +([[:alnum:]])'() {' ]] && IFS='()' read func _ <<< "$line" && [[ $func != $FUNCNAME ]] && { usage=${comments[3]##'#'+( )} whatis=${comments[5]##'#'+( )} [[ $usage = $func* && $whatis = *. ]] || err "Malformed docs for %s (line %d)." "$func" "$lineno" printf -v outline '# %s\n# %s\n#\n' "$usage" "$whatis" out+=$outline } comments=() done < ~/.bin/bashlib outhash=$(openssl md5 <<< "$out") if [[ $_tocHash = "$outhash" ]]; then inf 'Table of contents up-to-date.' else printf '%s' "$out" printf '_tocHash=%q' "$outhash" wrn 'Table of contents outdated.' fi } # ______________________________________________________________________ # | | # | .: GLOBAL DECLARATIONS :. | # |______________________________________________________________________| # Variables for convenience sequences. bobber=( '.' 'o' 'O' 'o' ) spinner=( '-' \\ '|' '/' ) crosser=( '+' 'x' '+' 'x' ) runner=( '> >' \ '>> ' \ ' >>' ) # Variables for terminal requests. [[ -t 2 && $TERM != dumb ]] && { COLUMNS=$({ tput cols || tput co;} 2>&3) # Columns in a line LINES=$({ tput lines || tput li;} 2>&3) # Lines on screen alt=$( tput smcup || tput ti ) # Start alt display ealt=$( tput rmcup || tput te ) # End alt display hide=$( tput civis || tput vi ) # Hide cursor show=$( tput cnorm || tput ve ) # Show cursor save=$( tput sc ) # Save cursor load=$( tput rc ) # Load cursor dim=$( tput dim || tput mh ) # Start dim bold=$( tput bold || tput md ) # Start bold stout=$( tput smso || tput so ) # Start stand-out estout=$( tput rmso || tput se ) # End stand-out under=$( tput smul || tput us ) # Start underline eunder=$( tput rmul || tput ue ) # End underline reset=$( tput sgr0 || tput me ) # Reset cursor blink=$( tput blink || tput mb ) # Start blinking italic=$( tput sitm || tput ZH ) # Start italic eitalic=$( tput ritm || tput ZR ) # End italic [[ $TERM != *-m ]] && { red=$( tput setaf 1|| tput AF 1 ) green=$( tput setaf 2|| tput AF 2 ) yellow=$( tput setaf 3|| tput AF 3 ) blue=$( tput setaf 4|| tput AF 4 ) magenta=$( tput setaf 5|| tput AF 5 ) cyan=$( tput setaf 6|| tput AF 6 ) } black=$( tput setaf 0|| tput AF 0 ) white=$( tput setaf 7|| tput AF 7 ) default=$( tput op ) eed=$( tput ed || tput cd ) # Erase to end of display eel=$( tput el || tput ce ) # Erase to end of line ebl=$( tput el1 || tput cb ) # Erase to beginning of line ewl=$eel$ebl # Erase whole line draw=$( tput -S <<< ' enacs smacs acsc rmacs' || { \ tput eA; tput as; tput ac; tput ae; } ) # Drawing characters back=$'\b' } 3>&2 2>/dev/null ||: # ______________________________________________________________________ # | | # | .: FUNCTION DECLARATIONS :. | # |______________________________________________________________________| # ______________________________________________________________________ # |__ Chr _______________________________________________________________| # # chr decimal # # Outputs the character that has the given decimal ASCII value. # chr() { printf "\\$(printf '%03o' "$1")" } # _____________________________________________________________________ # ______________________________________________________________________ # |__ Ord _______________________________________________________________| # # ord character # # Outputs the decimal ASCII value of the given character. # ord() { printf '%d' "'$1" } # _____________________________________________________________________ # ______________________________________________________________________ # |__ Hex _______________________________________________________________| # # hex character # # Outputs the hexadecimal ASCII value of the given character. # hex() { printf '%x' "'$1" } # _____________________________________________________________________ # ______________________________________________________________________ # |__ Unhex _______________________________________________________________| # # unhex character # # Outputs the character that has the given hexadecimal ASCII value. # unhex() { printf "\\x$1" } # _____________________________________________________________________ # ______________________________________________________________________ # |__ max _______________________________________________________________| # # max numbers... # # Outputs the highest of the given numbers. # max() { local max=$1 n for n; do (( n > max )) && max=$n done printf %d "$max" } # _____________________________________________________________________ # ______________________________________________________________________ # |__ min _______________________________________________________________| # # min numbers... # # Outputs the lowest of the given numbers. # min() { local min=$1 n for n; do (( n < min )) && min=$n done printf '%d' "$min" } # _____________________________________________________________________ # ______________________________________________________________________ # |__ totime ____________________________________________________________| # # totime "YYYY-MM-DD HH:MM:SS.mmm"... # # Outputs the number of milliseconds in the given date string(s). # # When multiple date string arguments are given, multiple time strings are output, one per line. # # The fields should be in the above defined order. The delimitor between the fields may be any one of [ -:.]. # If a date string does not follow the defined format, the result is undefined. # # Note that this function uses a very simplistic conversion formula which does not take any special calendar # convenions into account. It assumes there are 12 months in evert year, 31 days in every month, 24 hours # in every day, 60 minutes in every hour, 60 seconds in every minute and 1000 milliseconds in every second. # totime() { local arg time year month day hour minute second milli for arg; do IFS=' -:.' read year month day hour minute second milli <<< "$arg" && (( time = (((((((((((10#$year * 12) + 10#$month) * 31) + 10#$day) * 24) + 10#$hour) * 60) + 10#$minute) * 60) + 10#$second) * 1000) + 10#$milli )) && printf '%d\n' "$time" done } # _____________________________________________________________________ # ______________________________________________________________________ # |__ Exists ____________________________________________________________| # # exists application # # Succeeds if the application is in PATH and is executable. # exists() { [[ -x $(type -P "$1" 2>/dev/null) ]] } # _____________________________________________________________________ # ______________________________________________________________________ # |__ FirstExists ____________________________________________________________| # # firstExists file... # # Outputs the first of the arguments that is a file which exists. # firstExists() { local file; for file; do [[ -e "$file" ]] && printf %s "$file" && exit done } # _____________________________________________________________________ # ______________________________________________________________________ # |__ Eol _______________________________________________________________| # # eol message # # Return termination punctuation for a message, if necessary. # eol() { : #[[ $1 && $1 != *[\!\?.,:\;\|] ]] && printf .. ||: } # _____________________________________________________________________ # ______________________________________________________________________ # |__ Hr _______________________________________________________________| # # hr pattern [length] # # Outputs a horizontal ruler of the given length in characters or the terminal column length otherwise. # The ruler is a repetition of the given pattern string. # hr() { local pattern=${1:--} length=${2:-$COLUMNS} ruler= while (( ${#ruler} < length )); do ruler+=${pattern:0:length-${#ruler}} done printf %s "$ruler" } # _____________________________________________________________________ # ______________________________________________________________________ # |__ CLoc ______________________________________________________________| # # cloc # # Outputs the current cursor location as two space-separated numbers: row column. # cloc() { local old=$(stty -g) trap 'stty "$old"' RETURN stty raw # If the tty has input waiting then we can't read back its response. We'd only break and pollute the tty input buffer. read -t 0 < /dev/tty 2>/dev/null && return 1 printf '\e[6n' > /dev/tty IFS='[;' read -dR _ row col < /dev/tty printf '%d %d' "$row" "$col" } # _____________________________________________________________________ # ______________________________________________________________________ # |__ readwhile ______________________________________________________________| # # readwhile command [args] # # Outputs the characters typed by the user into the terminal's input buffer while running the given command. # readwhile() { local old=$(stty -g) in result REPLY trap 'stty "$old"' RETURN stty raw "$@" result=$? while read -t 0; do IFS= read -rd '' -n1 && in+=$REPLY done printf %s "$in" return $result } # _____________________________________________________________________ # ______________________________________________________________________ # |__ Latest ____________________________________________________________| # # latest [file...] # # Output the argument that represents the file with the latest modification time. # latest() ( shopt -s nullglob local file latest=$1 for file; do [[ $file -nt $latest ]] && latest=$file done printf '%s\n' "$latest" ) # _____________________________________________________________________ # _______________________________________________________________________ # |__ Iterate ____________________________________________________________| # # iterate [command] # # All arguments to iterate make up a single command that will be executed. # # Any of the arguments may be of the format {x..y[..z]} which causes the command # to be executed in a loop, each iteration substituting the argument for the # current step the loop has reached from x to y. We step from x to y by # walking from x's position in the ASCII character table to y's with a step of z # or 1 if z is not specified. # iterate() ( local command=( "$@" ) iterationCommand=() loop= a= arg= current=() step=() target=() for a in "${!command[@]}"; do arg=${command[a]} if [[ $arg = '{'*'}' ]]; then loop=${arg#'{'} loop=${loop%'}'} step[a]=${loop#*..*..} current[a]=${loop%%..*} target[a]=${loop#*..} target[a]=${target[a]%.."${step[a]}"} [[ ! ${step[a]} || ${step[a]} = $loop ]] && step[a]=1 fi done if (( ${#current[@]} )); then for loop in "${!current[@]}"; do while true; do iterationCommand=() for a in "${!command[@]}"; do (( a == loop )) \ && iterationCommand+=( "${current[a]}" ) \ || iterationCommand+=( "${command[a]}" ) done iterate "${iterationCommand[@]}" [[ ${current[loop]} = ${target[loop]} ]] && break current[loop]="$(chr "$(( $(ord "${current[loop]}") + ${step[loop]} ))")" done done else "${command[@]}" fi ) # _____________________________________________________________________ # ______________________________________________________________________ # |__ Logging ___________________________________________________________| # # log format [arguments...] # # Log an event at a certain importance level. The event is expressed as a printf(1) format argument. # The current exit code remains unaffected by the execution of this function. # # Instead of 'log', you can use a level as command name, to log at that level. Using log, messages are # logged at level inf. The supported levels are: trc, dbg, inf, wrn, err, ftl. # # If you prefix the command name with a p, the log message is shown as a spinner and waits for the next # closing statement. Eg. # # pinf 'Converting image' # convert image.png image.jpg # fnip # # The closing statement (here fnip) is the reverse of the opening statement and exits with the exit code # of the last command. If the last command failed, it shows the exit code in the spinner before it is stopped. # The closing statement also takes a format and arguments, which are displayed in the spinner. # log() { local exitcode=$? level=${level:-inf} supported=0 end=$'\n' type=msg conMsg= logMsg= format= colorFormat= date= info= arg= args=() colorArgs=() ruler= # Handle options. local OPTIND=1 while getopts :tpuPrR:d:n arg; do case $arg in p) end='.. ' type=startProgress ;; u) end='.. ' type=updateProgress ;; P) type=stopProgress ;; r) ruler='____' ;; R) ruler=$OPTARG ;; d) end=$OPTARG ;; n) end= ;; t) date=$(date +"${_logDate:-%H:%M}") ;; esac done shift "$((OPTIND-1))" format=$1 args=( "${@:2}" ) (( ! ${#args[@]} )) && [[ $format ]] && { args=("$format") format=%s; local bold=; } # Level-specific settings. local logLevelColor case $level in TRC) (( supported = _logVerbosity >= 4 )) logLevelColor=$_logTrcColor ;; DBG) (( supported = _logVerbosity >= 3 )) logLevelColor=$_logDbgColor ;; INF) (( supported = _logVerbosity >= 2 )) logLevelColor=$_logInfColor ;; WRN) (( supported = _logVerbosity >= 1 )) logLevelColor=$_logWrnColor ;; ERR) (( supported = _logVerbosity >= 0 )) logLevelColor=$_logErrColor ;; FTL) (( supported = 1 )) logLevelColor=$_logFtlColor ;; *) log FTL 'Log level %s does not exist' "$level" exit 1 ;; esac (( ! supported )) && return "$exitcode" local logColor=${_logColor:+$logLevelColor} # Generate the log message. case $type in msg|startProgress) printf -v logMsg "[${date:+%s }%-3s] $format$end" ${date:+"$date"} "$level" "${args[@]}" if (( _logColor )); then colorFormat=$(sed ${reset:+-e "s/$(requote "$reset")/$reset$logColor/g"} -e "s/%[^a-z]*[a-z]/$reset$bold$logColor&$reset$logColor/g" <<< "$format") colorArgs=("${args[@]//$reset/$reset$bold$logColor}") printf -v conMsg "$reset[${date:+%s }$logColor$bold%-3s$reset] $logColor$colorFormat$reset$black\$$reset$end$save" ${date:+"$date"} "$level" "${colorArgs[@]}" else conMsg=$logMsg fi ;; updateProgress) printf -v logMsg printf " [$format]" "${args[@]}" if (( _logColor )); then colorFormat=$(sed ${reset:+-e "s/$(requote "$reset")/$reset$logColor/g"} -e "s/%[^a-z]*[a-z]/$reset$bold$logColor&$reset$logColor/g" <<< "$format") colorArgs=("${args[@]//$reset/$reset$bold$logColor}") printf -v conMsg "$load$eel$blue$bold[$reset$logColor$colorFormat$reset$blue$bold]$reset$end" "${colorArgs[@]}" else conMsg=$logMsg fi ;; stopProgress) case $exitcode in 0) printf -v logMsg "done${format:+ ($format)}.\n" "${args[@]}" if (( _logColor )); then colorFormat=$(sed ${reset:+-e "s/$(requote "$reset")/$reset$logColor/g"} -e "s/%[^a-z]*[a-z]/$reset$bold$logColor&$reset$logColor/g" <<< "$format") colorArgs=("${args[@]//$reset/$reset$bold$logColor}") printf -v conMsg "$load$eel$green${bold}done${colorFormat:+ ($reset$logColor$colorFormat$reset$green$bold)}$reset.\n" "${colorArgs[@]}" else conMsg=$logMsg fi ;; *) info=${format:+$(printf ": $format" "${args[@]}")} printf -v logMsg "error(%d%s).\n" "$exitcode" "$info" if (( _logColor )); then printf -v conMsg "${eel}${red}error${reset}(${bold}${red}%d${reset}%s).\n" "$exitcode" "$info" else conMsg=$logMsg fi ;; esac ;; esac # Create the log file. if [[ $_logFile && ! -e $_logFile ]]; then [[ $_logFile = */* ]] || $_logFile=./$logFile mkdir -p "${_logFile%/*}" && touch "$_logFile" fi # Stop the spinner. if [[ $type = stopProgress && $_logSpinner ]]; then kill "$_logSpinner" wait "$_logSpinner" 2>/dev/null unset _logSpinner fi # Output the ruler. if [[ $ruler ]]; then printf >&2 '%s\n' "$(hr "$ruler")" [[ -w $_logFile ]] \ && printf >> "$_logFile" '%s' "$ruler" fi # Output the log message. printf >&2 '%s' "$conMsg" [[ -w $_logFile ]] \ && printf >> "$_logFile" '%s' "$logMsg" # Start the spinner. if [[ $type = startProgress && ! $_logSpinner && $TERM != dumb ]]; then { set +m trap 'printf >&2 %s "$show"' EXIT printf >&2 %s "$hide" while printf >&2 "$eel$blue$bold[$reset%s$reset$blue$bold]$reset\b\b\b" "${spinner[s++ % ${#spinner[@]}]}" && sleep .1 do :; done } & _logSpinner=$! fi return $exitcode } trc() { level=TRC log "$@"; } dbg() { level=DBG log "$@"; } inf() { level=INF log "$@"; } wrn() { level=WRN log "$@"; } err() { level=ERR log "$@"; } ftl() { level=FTL log "$@"; } plog() { log -p "$@"; } ulog() { log -u "$@"; } golp() { log -P "$@"; } ptrc() { level=TRC plog "$@"; } pdbg() { level=DBG plog "$@"; } pinf() { level=INF plog "$@"; } pwrn() { level=WRN plog "$@"; } perr() { level=ERR plog "$@"; } pftl() { level=FTL plog "$@"; } utrc() { level=TRC ulog "$@"; } udbg() { level=DBG ulog "$@"; } uinf() { level=INF ulog "$@"; } uwrn() { level=WRN ulog "$@"; } uerr() { level=ERR ulog "$@"; } uftl() { level=FTL ulog "$@"; } gtrc() { level=trc golp "$@"; } gbdp() { level=DBG golp "$@"; } fnip() { level=INF golp "$@"; } nrwp() { level=WRN golp "$@"; } rrep() { level=ERR golp "$@"; } ltfp() { level=FTL golp "$@"; } _logColor=${_logColor:-$([[ -t 2 ]] && echo 1)} _logVerbosity=2 _logTrcColor=$grey _logDbgColor=$blue _logInfColor=$white _logWrnColor=$yellow _logErrColor=$red _logFtlColor=$bold$red # _______________________________________________________________________ # ______________________________________________________________________ # |__ Ask _______________________________________________________________| # # ask [-c optionchars|-d default] [-s|-S maskchar] format [arguments...] # # Ask a question and read the user's reply to it. Then output the result on stdout. # # When in normal mode, a single line is read. If the line is empty and # -d was specified, the default argument is output instead of an empty line. # The exit code is always 0. # # When in option mode (-c), the user is shown the option characters with # which he can reply and a single character is read. # If the reply is empty (user hits enter) and any of the optionchars are # upper-case, the upper-case option (= the default option) character will # be output instead of an empty line. # If the reply character is not amoungst the provided options the default # option is again output instead if present. If no default was given, an # exit code of 2 is returned. # You may mark an optionchar as 'valid' by appending a '!' to it. As a # result, an exit code of 0 will only be returned if this valid option # is replied. If not, an exit code of 1 will be returned. # ask() { # Initialize the vars. local opt arg local option= local options= local default= local silent= local valid= local muteChar= local format= # Parse the options. local OPTIND=1 while getopts :sS:c:d: opt; do case $opt in s) silent=1 ;; S) silent=1 muteChar=$OPTARG ;; c) while read -n1 arg; do case $arg in [[:upper:]]) default=$arg ;; !) valid=${options: -1}; continue ;; esac options+=$arg done <<< "$OPTARG" ;; d) default=$OPTARG option=$default ;; esac done # Trim off the options. shift $((OPTIND-1)) # Figure out what FD to use for our messages. [[ -t 1 ]] && local fd=1 || local fd=2 # Ask the question. format=$1; shift level=${level:-WRN} log -n "$format${option:+ [%s]}${options:+ [%s]}" "$@" ${option:+"$option"} ${options:+"$options"} # Read the reply. exec 8<&0; [[ -t 8 ]] || exec 8</dev/tty if [[ $muteChar ]]; then local reply while read -u8 -s -n1 && [[ $REPLY ]]; do reply+=$REPLY printf '%s' "$muteChar" >&$fd done REPLY=$reply else read -u8 -e ${options:+-n1} ${silent:+-s} fi [[ $options && $REPLY ]] || (( silent )) && printf '\n' >&$fd # Evaluate the reply. while true; do if [[ $REPLY && ( ! $options || $options = *$REPLY* ) ]]; then if [[ $valid ]] then [[ $REPLY = $valid ]] else printf "%s" "$REPLY" fi return fi [[ -z $default || $REPLY = $default ]] \ && return 2 REPLY=$default done } # _____________________________________________________________________ # ______________________________________________________________________ # |__ Trim ______________________________________________________________| # # trim lines ... # # Trim the whitespace off of the beginning and end of the given lines. # Each argument is considdered one line; is treated and printed out. # # When no arguments are given, lines will be read from standard input. # trim() { { (( $# )) && printf '%s\n' "$@" || cat; } | \ sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//' } # _____________________________________________________________________ # ______________________________________________________________________ # |__ Reverse ___________________________________________________________| # # reverse [-0|-d delimitor] [elements ...] [<<< elements] # # Reverse the order of the given elements. # Elements are read from command arguments or standard input if no element # arguments are given. # They are reversed and output on standard output. # # If the -0 option is given, input and output are delimited by NUL bytes. # If the -d option is given, input and output are delimited by the # character argument. # Otherwise, they are delimited by newlines. # reverse() { # Initialize the vars. local elements=() delimitor=$'\n' i # Parse the options. local OPTIND=1 while getopts :0d: opt; do case $opt in 0) delimitor=$'\0' ;; d) delimitor=$OPTARG ;; esac done shift "$((OPTIND-1))" # Get the elements. if (( $# )); then elements=( "$@" ) else while IFS= read -r -d "$delimitor"; do elements+=("$REPLY") done fi # Iterate in reverse order. for (( i=${#elements[@]} - 1; i >=0; --i )); do printf "%s${delimitor:-'\0'}" "${elements[i]}" done } # _____________________________________________________________________ # ______________________________________________________________________ # |__ Order _____________________________________________________________| # # order [-0|-d char] [-[fF] isDesired] [-[cC] isAscending|-n|-r|-t] [-T number] [-a array|elements ...] [<<< elements] # # Orders the elements in ascending order. # Elements are read from command arguments or standard input if no element # arguments are given. # The result is output on standard output. # # By default, the elements will be ordered using lexicographic comparison. # If the -n option is given, the elements will be ordered numerically. # If the -r option is given, the elements will be ordered randomly. # If the -f option is given, the command name following it will be used # as a filter. # If the -c option is given, the command name following it will be used # as a comparator. # If the -C option is given, the bash code following it will be used # as a comparator. # If the -t option is given, only the first number results are returned. # If the -a option is given, the elements in array are ordered instead and # array is mutated to contain the result. # If number is 0, all results are returned. # # isDesired is a command name which will get one parameter. The parameter # is an element which will only be included if the command exits successfully. # isAscending is a command name which will be executed for each element # comparison and will be passed two element arguments. The command should # succeed if the first argument is less than the second argument for the # purpose of this sort. # # If the -0 option is given, input and output are delimited by NUL bytes. # If the -d option is given, input and output are delimited by the # character argument. # Otherwise, they are delimited by newlines. # # The ordering is implemented by an insertion sort algorithm. # order() { # Initialize the vars. local delimitor=$'\n' i isDesired=true isAscending=string_ascends top=0 arrayName= array= # Parse the options. local OPTIND=1 while getopts :0nrd:f:F:c:C:tT:a: opt; do case $opt in 0) delimitor=$'\0' ;; d) delimitor=$OPTARG ;; n) isAscending=number_ascends ;; r) isAscending=random_ascends ;; t) isAscending=mtime_ascends ;; f) isDesired=$OPTARG ;; F) isDesired=bash_desired bash_desired_code=$OPTARG ;; c) isAscending=$OPTARG ;; C) isAscending=bash_ascends bash_ascends_code=$OPTARG ;; T) top=$OPTARG ;; a) arrayName=$OPTARG array=$arrayName[@] ;; esac done shift "$((OPTIND-1))" # Get the elements. local elements=() element if [[ $arrayName ]]; then for element in "${!array}"; do "$isDesired" "$element" && elements+=("$element") done elif (( $# )); then for element; do "$isDesired" "$element" && elements+=("$element") done else while IFS= read -r -d "$delimitor" element; do "$isDesired" "$element" && elements+=("$element") done fi # Iterate in reverse order. for (( i = 1; i < ${#elements[@]}; ++i )); do for (( j = i; j > 0; --j )); do element=${elements[j]} if "$isAscending" "$element" "${elements[j-1]}"; then elements[j]=${elements[j-1]} elements[j-1]=$element fi done done (( top )) || top=${#elements[@]} if [[ $array ]]; then declare -ga "$array=($(printf '%q ' "${elements[@]:0:top}"))" else printf "%s${delimitor:-\0}" "${elements[@]:0:top}" fi } # _____________________________________________________________________ string_ascends() { [[ $1 < $2 ]]; } number_ascends() { (( $1 < $2 )); } random_ascends() { (( RANDOM % 2 )); } mtime_ascends() { [[ $1 -ot $2 ]]; } exists_desired() { [[ -e $1 ]]; } line_desired() { [[ $1 ]]; } code_desired() { line_desired "$1" && ! comment_desired "$1"; } comment_desired() { line_desired "$1" && [[ $1 = @(#|//|/\*)* ]]; } bash_desired() { bash -c "$bash_desired_code" -- "$@"; } bash_ascends() { bash -c "$bash_ascends_code" -- "$@"; } # ______________________________________________________________________ # |__ Mutex _____________________________________________________________| # # mutex file # # Open a mutual exclusion lock on the file, unless another process already owns one. # # If the file is already locked by another process, the operation fails. # This function defines a lock on a file as having a file descriptor open to the file. # This function uses FD 9 to open a lock on the file. To release the lock, close FD 9: # exec 9>&- # mutex() { local lockfile=${1:-${BASH_SOURCE[-1]}} pid pids [[ -e $lockfile ]] || err "No such file: $lockfile" || return exec 9>> "$lockfile" && [[ $({ fuser -f "$lockfile"; } 2>&- 9>&-) == $$ ]] } # ______________________________________________________________________ # |__ PushJob ___________________________________________________________| # # pushjob [poolsize] command # # Start an asynchronous command within a pool, waiting for space in the pool if it is full. # # The pool is pruned automatically as running jobs complete. This function # allows you to easily run asynchronous commands within a pool of N, # automatically starting the next command as soon as there's space. # pushjob() { local size=$1; shift 1 # Wait for space in the pool. until (( ${#jobpool[@]} < size )); do sleep 1 & pushjobsleep=$! wait "$pushjobsleep" done 2>/dev/null # Register prunejobs and start the pushed job. trap _prunejobs SIGCHLD set -m "$@" & jobpool[$!]= } _prunejobs() { # Prune all pool jobs that are no longer running. for pid in "${!jobpool[@]}"; do kill -0 "$pid" 2>/dev/null || unset "jobpool[$pid]" done # Unregister SIGCHLD if our pool is empty. (( ${#jobpool[@]} )) || trap - SIGCHLD # Wake up pushjob. kill "$pushjobsleep" 2>/dev/null } # ______________________________________________________________________ # |__ FSleep _____________________________________________________________| # # fsleep time # # Wait for the given (fractional) amount of seconds. # # This implementation solves the problem portably, assuming that either # bash 4.x or a fractional sleep(1) is available. # fsleep() { local fifo=${TMPDIR:-/tmp}/.fsleep.$$ trap 'rm -f "$fifo"' RETURN mkfifo "$fifo" && { read -t "$1" <> "$fifo" 2>/dev/null || sleep "$1"; } } # _____________________________________________________________________ # ______________________________________________________________________ # |__ options ___________________________________________________________| # # options [option description]... # # Specify and handle options in arguments. # # The 'setopt' function will be called for each option expected option # passed to the script, with $1 set to the option character and $2 # its description. Check OPTARG if the option takes an argument. # 'setopt' will be called with '?' if an invalid option is passed. # # Unless specified, the -h option will show a usage description, # explaining the options. # # Proposed usage: # setopt() { # case "$1" in # a) echo "got option a" ;; # b) echo "got option b with argument $OPTARG" ;; # esac # } # options \ # a 'option a' \ # b: 'option b with argument' # options() { # Parse the expected options and their description. declare -A options=() while (( $# )); do local optchar=$1 optdesc=$2 shift 2 || ftl 'Missing arguments, expected option (%s), description (%s).' "$optchar" "$optdesc" || exit options[$optchar]=$optdesc done # Find the script's options. local argc=${BASH_ARGC[@]: -1} argv=("${BASH_ARGV[@]: -argc}") arg local optstring=$(printf %s "${!options[@]}")h set -- # Sigh. BASH_ARGV is all backwards. for arg in "${argv[@]}"; do set -- "$arg" "$@" done # Handle the script's options. while getopts "$optstring" arg; do if [[ $arg = h && ! ${options[h]} ]]; then # Show usage message. [[ -t 1 ]]; local fd=$(( $? + 1 )) optarg # Print out the app usage. printf " Usage: $reset$bold%s$reset" "${BASH_SOURCE[1]##*/}" >&$fd for optchar in "${!options[@]}"; do [[ $optchar = *: ]] && optarg=" arg" || optarg= printf " [$bold$green-%s$reset%s]" "${optchar%:}" "$optarg" >&$fd done printf "\n\n" >&$fd # Print out the option descriptions. for optchar in "${!options[@]}"; do local optdesc=${options[$optchar]} [[ $optchar = *: ]] && optarg=" arg" || optarg= printf " $bold$green-%s$reset%s\t" "${optchar%:}" "$optarg" fmt -w "$COLUMNS" <<< "${optdesc//+( )/ }" | sed $'1!s/^/ \t/' printf "\n" done | column -t -s $'\t' >&$fd else optchar=$arg; [[ ! ${options[$arg]} && ${options[$arg:]} ]] && optchar=$arg: setopt "$arg" "${options[$arg]}" fi done } # _____________________________________________________________________ # ______________________________________________________________________ # |__ ShowHelp __________________________________________________________| # # showHelp name description author [option description]... # # Generate a prettily formatted usage description of the application. # # name Provide the name of the application. # # description Provide a detailed description of the application's # purpose and usage. # # option An option the application can take as argument. # # description A description of the effect of the preceding option. # showHelp() { # Parse the options. local appName=$1; shift local appDesc=${1//+([[:space:]])/ }; shift local appAuthor=$1; shift local cols=$(tput cols) (( cols = ${cols:-80} - 10 )) # Figure out what FD to use for our messages. [[ -t 1 ]]; local fd=$(( $? + 1 )) # Print out the help header. printf "$reset$bold\n" >&$fd printf "\t\t%s\n" "$appName" >&$fd printf "$reset\n" >&$fd printf "%s\n" "$appDesc" | fmt -w "$cols" | sed $'s/^/\t/' >&$fd printf "\t $reset$bold~ $reset$bold%s\n" "$appAuthor" >&$fd printf "$reset\n" >&$fd # Print out the application options and columnize them. while (( $# )); do local optName=$1; shift local optDesc=$1; shift printf " %s\t" "$optName" printf "%s\n" "${optDesc//+( )/ }" | fmt -w "$cols" | sed $'1!s/^/ \t/' printf "\n" done | column -t -s $'\t' \ | sed "s/^\( [^ ]*\)/$bold$green\1$reset/" >&$fd printf "\n" >&$fd } # _____________________________________________________________________ # ______________________________________________________________________ # |__ Quote _____________________________________________________________| # # shquote [-e] [argument...] # # Shell-quote the arguments to make them safe for injection into bash code. # # The result is bash code that represents a series of words, where each # word is a literal string argument. By default, quoting happens using # single-quotes. # # -e Use backslashes rather than single quotes. # -d Use double-quotes rather than single quotes (does NOT disable expansions!). # -a Normally, shquote doesn't quote arguments that don't need it. This forces all arguments to be quoted. # shquote() { # Initialize the defaults. local arg escape=0 sq="'\\''" dq='\"' quotedArgs=() type=single always=0 # Parse the options. while [[ $1 = -* ]]; do case $1 in -e) type=escape ;; -d) type=double ;; -a) always=1 ;; --) shift; break ;; esac shift done # Print out each argument, quoting it properly. for arg; do (( ! always )) && [[ $arg = "$(printf %q "$arg")" ]] && quotedArgs+=("$arg") && continue case "$type" in escape) quotedArgs+=("$(printf "%q" "$arg")") ;; single) arg=${arg//"'"/$sq} quotedArgs+=("$(printf "'%s'" "$arg")") ;; double) arg=${arg//'"'/$dq} quotedArgs+=("$(printf '"%s"' "$arg")") ;; esac done printf '%s\n' "$(IFS=' '; echo "${quotedArgs[*]}")" } # _____________________________________________________________________ # ______________________________________________________________________ # |__ ReQuote __________________________________________________________| # # requote [string] # # Escape the argument string to make it safe for injection into a regex. # # The result is a regular expression that matches the literal argument # string. # requote() { # Initialize the defaults. local char printf '%s' "$1" | while IFS= read -r -d '' -n1 char; do printf '[%s]' "$char" done } # _____________________________________________________________________ # ______________________________________________________________________ # |__ Shorten ___________________________________________________________| # # shorten [-p pwd] path [suffix]... # # Shorten an absolute path for pretty printing. # Paths are shortened by replacing the homedir by ~, making it relative and # cutting off given suffixes from the end. # # -p Use the given pathname as the base for relative filenames instead of PWD. # path The path string to shorten. # suffix Suffix strings that must be cut off from the end. # Only the first suffix string matched will be cut off. # shorten() { # Parse the options. local suffix path pwd=$PWD [[ $1 = -p ]] && { pwd=$2; shift 2; } path=$1; shift # Make path absolute. [[ $path = /* ]] || path=$PWD/$path # If the path denotes something that exists; it's easy. if [[ -d $path ]] then path=$(cd "$path"; printf "%s" "$PWD") elif [[ -d ${path%/*} ]] then path=$(cd "${path%/*}"; printf "%s" "$PWD/${path##*/}") # If not, we'll try readlink -m. elif readlink -m / >/dev/null 2>&1; then path=$(readlink -m "$path") # If we don't have that - unleash the sed(1) madness. else local oldpath=/ while [[ $oldpath != $path ]]; do oldpath=$path path=$(sed -e 's,///*,/,g' -e 's,\(^\|/\)\./,\1,g' -e 's,\(^\|/\)[^/]*/\.\.\($\|/\),\1,g' <<< "$path") done fi # Replace special paths. path=${path/#$HOME/'~'} path=${path#$pwd/} # Cut off suffix. for suffix; do [[ $path = *$suffix ]] && { path=${path%$suffix} break } done printf "%s" "$path" } # _____________________________________________________________________ # ______________________________________________________________________ # |__ Up ________________________________________________________________| # # up .../path|num # # Walk the current working directory up towards root num times or until path is found. # # Returns 0 if the destination was reached or 1 if we hit root. # # Prints PWD on stdout on success. # up() { local up=0 until [[ $PWD = / ]]; do cd ../ if [[ $1 = .../* ]]; then [[ -e ${1#.../} ]] && pwd && return elif (( ++up == $1 )); then pwd && return fi done } # _____________________________________________________________________ # ______________________________________________________________________ # |__ BuildArray ________________________________________________________| # # buildarray name terms... -- elements... # # Create an array by adding all the terms to it for each element, replacing {} terms by the element. # # name The name of the array to put the result into. # terms The values to add to the array for each of the elements. A {} term is replaced by the current element. # elements The elements to iterate the terms for. # buildarray() { local target=$1 term terms=() element value shift while [[ $1 != -- ]]; do terms+=("$1") shift done shift for element; do for term in "${terms[@]}"; do [[ $term = {} ]] && value="$element" || value="$term" declare -ag "$target+=($(printf '%q' "$value"))" done done } # _____________________________________________________________________ # ______________________________________________________________________ # |__ InArray ___________________________________________________________| # # inArray element array # # Checks whether a certain element is in the given array. # # element The element to search the array for. # array This is a list of elements to search through. # inArray() { # Parse the options. local element local search=$1; shift # Perform the search. for element do [[ $element = $search ]] && return 0; done return 1 } # _____________________________________________________________________ # ______________________________________________________________________ # |__ HideDebug _________________________________________________________| # # hideDebug [on|off] # # Toggle Bash's debugging mode off temporarily. # To hide Bash's debugging output for a function, you should have # hideDebug on # as its first line, and # hideDebug off # as its last. # hideDebug() { if [[ $1 = on ]]; then : -- HIDING DEBUG OUTPUT .. [[ $- != *x* ]]; bashlib_debugWasOn=$? set +x elif [[ $1 = off ]]; then : -- SHOWING DEBUG OUTPUT .. (( bashlib_debugWasOn )) && \ set -x fi } # ______________________________________________________________________ # |__ anfunc ____________________________________________________________| # # anfunc [on|off] # # Turn on or off support for annonymous functions. # # WARNING: This is a hack. It turns on extdebug and causes any argument # that matches (){code} to be replaced by a function name that if invoked # runs code. # # eg. # confirm '(){ rm "$1" }' *.txt # # In this example, confirm() could be a function that asks confirmation # # for each argument past the first and runs the anfunc in the first # # argument on each confirmed argument. # # Don't use this. It is an academic experiment and has bugs. # # Bugs: # - commands lose their exit code. # To inhibit the real command from running, we use extdebug and # a DEBUG trap that returns non-0. As a result, the actual return # code is lost. # anfunc() { case "$1" in on) shopt -s extdebug trap _anfunc_trap DEBUG ;; off) trap - DEBUG shopt -u extdebug ;; esac } _anfunc_trap() { local f w # Perform the command parsing and handling up to its word splitting. # This includes command substitution, quote handling, pathname expansion, etc. declare -a words="($BASH_COMMAND)" # Iterate the words to run in the final stage, and handle anfunc matches. for ((w=0; w<${#words[@]}; ++w)); do [[ ${words[w]} = '(){'*'}' ]] && # Declare a new function for this anfunc. eval "_f$((++f))${words[w]}" && # Replace the word by the new function's name. words[w]="_f$f" done # Run the command. eval "$(printf '%q ' "${words[@]}")" # Clean up the anfuncs. for ((; f>0; --f)); do unset -f "_f$f" done # Inhibit the real command's execution. return 1 } # ______________________________________________________________________ # |__ StackTrace ________________________________________________________| # # stackTrace # # Output the current script's function execution stack. # stackTrace() { # Some general debug information. wrn " [PID : %15s] [PPID : %8s] [Main PID : %8s]" "$BASHPID" "$PPID" "$$" wrn " [Level : %15s] [Subshells : %8s] [Runtime : %7ss]" "$SHLVL" "$BASH_SUBSHELL" "$SECONDS" wrn " [Locale : %15s] [IFS : %8s]" "${LC_ALL:-${LC_COLLATE:-${LANG:-C}}}" "$(printf %q "$IFS")" wrn " Dir Stack : %s" "${DIRSTACK[*]}" wrn " Shell : %s v%s" "$BASH" "$BASH_VERSION" wrn " Shell Opts : %s" "${SHELLOPTS//:/, }" wrn " Bash Opts : %s" "${BASHOPTS//:/, }" wrn " Functions :" # Search through the map. local arg=0 for stack in "${!FUNCNAME[@]}"; do (( stack+1 >= ${#BASH_SOURCE[@]} )) && break func=${FUNCNAME[stack]} line=${BASH_LINENO[stack]} file=${BASH_SOURCE[stack+1]} args=() for (( arg=0, s=0; s <= stack; ++s )); do for (( sarg=0; sarg < ${BASH_ARGC[s]:-0}; ++sarg, ++arg )); do (( s == stack )) && args[${BASH_ARGC[s]} - sarg]=${BASH_ARGV[arg]} done done wrn '%40s:%-3d | %s %s' "$file" "$line" "$func" "$(printf '%s ' "$(shquote "${args[@]}")")" done } # _____________________________________________________________________ # ______________________________________________________________________ # | | # | .: ENTRY POINT :. | # |______________________________________________________________________| # Make sure this file is sourced and not executed. ( return 2>/dev/null ) || { help=$(sed -n '1,/_tocHash=/{ /^#/p; }' "$BASH_SOURCE") if [[ $1 ]]; then while [[ $1 ]]; do awk "p && !/^# *[^ ]/ {exit} p || /^# $1/ {print; p=1}" <<< "$help" shift done else echo "$help" echo echo "To use bashlib, copy it into your PATH and put ''source bashlib'' at the top of your script." fi } : : .: END SOURCING :. : ______________________________________________________________________ :