scripts/core/functions.sh

   1 #!/bin/bash
   2
   3 # This defines some general, useful functions.
   4
   5 #hmmm: starting to get a bit beefy in here.  perhaps there is a good way to refactor the functions into more specific folders, if they aren't really totally general purpose?
   6
   7 ##############
   8
   9 # test whether we've been here before or not.
  10 skip_all=
  11 type function_sentinel &>/dev/null
  12 if [ $? -eq 0 ]; then
  13   # there was no error, so we can skip the inits.
  14   if [ ! -z "$DEBUG_FEISTY_MEOW" ]; then
  15     echo "skipping function definitions, because already defined."
  16   fi
  17   skip_all=yes
  18 else
  19   skip_all=
  20 fi
  21
  22 if [ -z "$skip_all" ]; then
  23
  24   if [ ! -z "$DEBUG_FEISTY_MEOW" ]; then
  25     echo "feisty meow function definitions beginning now..."
  26   fi
  27
  28   # a handy little method that can be used for date strings.  it was getting
  29   # really tiresome how many different ways the script did the date formatting.
  30   function date_stringer() {
  31     local sep="$1"; shift
  32     if [ -z "$sep" ]; then sep='_'; fi
  33     date +"%Y$sep%m$sep%d$sep%H%M$sep%S" | tr -d '/\n/'
  34   }
  35
  36   # a wrapper for the which command that finds items on the path.  some OSes
  37   # do not provide which, so we want to not be spewing errors when that
  38   # happens.
  39   function whichable()
  40   {
  41     to_find="$1"; shift
  42     local WHICHER="$(\which which 2>/dev/null)"
  43     if [ $? -ne 0 ]; then
  44       # there is no which command here.  we produce nothing due to this.
  45       echo
  46     fi
  47     echo $($WHICHER $to_find 2>/dev/null)
  48   }
  49
  50   # makes a directory of the name specified and then tries to change the
  51   # current directory to that directory.
  52   function mcd() {
  53     if [ ! -d "$1" ]; then mkdir -p "$1"; fi
  54     cd "$1"
  55   }
  56
  57   # returns true if the variable is an array.
  58   function is_array() {
  59     [[ "$(declare -p $1)" =~ "declare -a" ]]
  60   }
  61
  62   # returns true if the name provided is a defined alias.
  63   function is_alias() {
  64     alias $1 &>/dev/null
  65     return $?
  66   }
  67
  68   # makes the status of pipe number N (passed as first parameter) into the
  69   # main return value (i.e., the value for $?).  this is super handy to avoid
  70   # repeating the awkward looking code below in multiple places.
  71   function promote_pipe_return()
  72   {
  73     ( exit ${PIPESTATUS[$1]} )
  74   }
  75
  76   ##############
  77
  78   function fm_username()
  79   {
  80     # see if we can get the user name from the login name.  oddly this sometimes doesn't work.
  81     local custom_user="$(logname 2>/dev/null)"
  82     if [ -z "$custom_user" ]; then
  83       # try the normal unix user variable.
  84       custom_user="$USER"
  85     fi
  86     if [ -z "$custom_user" ]; then
  87       # try the windows user variable.
  88       custom_user="$USERNAME"
  89     fi
  90     echo "$custom_user"
  91   }
  92
  93   ##############
  94
  95   # displays the value of a variable in bash friendly format.
  96   function var() {
  97     HOLDIFS="$IFS"
  98     IFS=""
  99     while true; do
 100       local varname="$1"; shift
 101       if [ -z "$varname" ]; then
 102         break
 103       fi
 104
 105       if is_alias "$varname"; then
 106 #echo found $varname is alias
 107         local tmpfile="$(mktemp $TMP/aliasout.XXXXXX)"
 108         alias $varname | sed -e 's/.*=//' >$tmpfile
 109         echo "alias $varname=$(cat $tmpfile)"
 110         \rm $tmpfile
 111       elif [ -z "${!varname}" ]; then
 112         echo "$varname undefined"
 113       else
 114         if is_array "$varname"; then
 115 #echo found $varname is array var
 116           local temparray
 117           eval temparray="(\${$varname[@]})"
 118           echo "$varname=(${temparray[@]})"
 119 #hmmm: would be nice to print above with elements enclosed in quotes, so that we can properly
 120 # see ones that have spaces in them.
 121         else
 122 #echo found $varname is simple
 123           echo "$varname=${!varname}"
 124         fi
 125       fi
 126     done | sort
 127     IFS="$HOLDIFS"
 128   }
 129
 130   ##############
 131
 132   # when passed a list of things, this will return the unique items from that list as an echo.
 133   function uniquify()
 134   {
 135     # do the uniquification: split the space separated items into separate lines, then
 136     # sort the list, then run the uniq tool on the list.  results will be packed back onto
 137     # one line when invoked like: local fredlist="$(uniquify a b c e d a e f a e d b)"
 138     echo $* | tr ' ' '\n' | sort | uniq
 139   }
 140
 141   # sets the variable in parameter 1 to the value in parameter 2, but only if
 142   # that variable was undefined.
 143   function set_var_if_undefined()
 144   {
 145     local var_name="$1"; shift
 146     local var_value="$1"; shift
 147     if [ -z "${!var_name}" ]; then
 148       eval export $var_name="$var_value"
 149     fi
 150   }
 151
 152   ##############
 153
 154   function success_sound()
 155   {
 156     if [ ! -z "$CLAM_FINISH_SOUND" ]; then
 157       bash $FEISTY_MEOW_SCRIPTS/multimedia/sound_play.sh "$CLAM_FINISH_SOUND"
 158     fi
 159   }
 160
 161   function error_sound()
 162   {
 163     if [ ! -z "$CLAM_ERROR_SOUND" ]; then
 164       bash $FEISTY_MEOW_SCRIPTS/multimedia/sound_play.sh "$CLAM_ERROR_SOUND"
 165     fi
 166   }
 167
 168   ##############
 169
 170   # echoes the maximum number of columns that the terminal supports.  usually
 171   # anything you print to the terminal with length less than (but not equal to)
 172   # maxcols will never wrap.
 173   function get_maxcols()
 174   {
 175     # calculate the number of columsn in the terminal.
 176     local cols=$(stty size | awk '{print $2}')
 177     echo $cols
 178   }
 179
 180   ##############
 181
 182   # checks the result of the last command that was run, and if that failed,
 183   # then this complains and exits from bash.  the function parameters are
 184   # used as the message to print as a complaint.
 185   function exit_on_error()
 186   {
 187     if [ $? -ne 0 ]; then
 188       echo -e "\n\nan important action failed and this script will stop:\n\n$*\n\n*** Exiting script..."
 189       error_sound
 190       exit 1
 191     fi
 192   }
 193
 194   # like exit_on_error, but will keep going after complaining.
 195   function continue_on_error()
 196   {
 197     if [ $? -ne 0 ]; then
 198       echo -e "\n\na problem occurred, but we can continue:\n\n$*\n\n=> Continuing script..."
 199       error_sound
 200     fi
 201   }
 202
 203   ##############
 204
 205   # accepts any number of arguments and outputs them to the feisty meow event log.
 206   function log_feisty_meow_event()
 207   {
 208     echo -e "$(date_stringer) -- ${USER}@$(hostname): $*" >> "$FEISTY_MEOW_EVENT_LOG"
 209   }
 210
 211   ##############
 212
 213   # wraps secure shell with some parameters we like, most importantly to enable X forwarding.
 214   function ssh()
 215   {
 216     local args=($@)
 217     # we remember the old terminal title, then force the TERM variable to a more generic
 218     # version for the other side (just 'linux'); we don't want the remote side still
 219     # thinking it's running xterm.
 220     save_terminal_title
 221
 222 #hmmm: why were we doing this?  it scorches the user's logged in session, leaving it without proper terminal handling.
 223 #    # we save the value of TERM; we don't want to leave the user's terminal
 224 #    # brain dead once we come back from this function.
 225 #    local oldterm="$TERM"
 226 #    export TERM=linux
 227
 228     /usr/bin/ssh -Y -C "${args[@]}"
 229
 230 #    # restore the terminal variable also.
 231 #    TERM="$oldterm"
 232
 233     restore_terminal_title
 234     if [ ! -z "$DEBUG_FEISTY_MEOW" ]; then
 235       echo TERM title restored to prior value
 236     fi
 237   }
 238
 239   ##############
 240
 241   # locates a process given a search pattern to match in the process list.
 242   # supports a single command line flag style parameter of "-u USERNAME";
 243   # if the -u flag is found, a username is expected afterwards, and only the
 244   # processes of that user are considered.
 245   function psfind() {
 246     local -a patterns=("${@}")
 247 #echo ====
 248 #echo patterns list is: "${patterns[@]}"
 249 #echo ====
 250
 251     local user_flag
 252     if [ "${patterns[0]}" == "-u" ]; then
 253       user_flag="-u ${patterns[1]}"
 254 #echo "found a -u parm and user=${patterns[1]}"
 255       # void the two elements with that user flag so we don't use them as patterns.
 256       unset patterns[0] patterns[1]=
 257     else
 258       # select all users.
 259       user_flag="-e"
 260     fi
 261
 262     local PID_DUMP="$(mktemp "$TMP/zz_pidlist.XXXXXX")"
 263     local -a PIDS_SOUGHT
 264
 265     if [ "$OS" == "Windows_NT" ]; then
 266       # gets cygwin's (god awful) ps to show windoze processes also.
 267       local EXTRA_DOZER_FLAGS="-W"
 268       # pattern to use for peeling off the process numbers.
 269       local pid_finder_pattern='s/ *\([0-9][0-9]*\) *.*$/\1/p'
 270
 271     else
 272       # flags which clean up the process listing output on unixes.
 273       # apparently cygwin doesn't count as a type of unix, because their
 274       # crummy specialized ps command doesn't support normal ps flags.
 275       local EXTRA_UNIX_FLAGS="-o pid,args"
 276       # pattern to use for peeling off the process numbers.
 277       local pid_finder_pattern='s/^[[:space:]]*\([0-9][0-9]*\).*$/\1/p'
 278     fi
 279
 280     /bin/ps $EXTRA_DOZER_FLAGS $EXTRA_UNIX_FLAGS $user_flag | tail -n +2 >$PID_DUMP
 281 #echo ====
 282 #echo got all this stuff in the pid dump file:
 283 #cat $PID_DUMP
 284 #echo ====
 285
 286     # search for the pattern the user wants to find, and just pluck the process
 287     # ids out of the results.
 288     local i
 289     for i in "${patterns[@]}"; do
 290       PIDS_SOUGHT+=($(cat $PID_DUMP \
 291         | grep -i "$i" \
 292         | sed -n -e "$pid_finder_pattern"))
 293     done
 294 #echo ====
 295 #echo pids sought list became:
 296 #echo "${PIDS_SOUGHT[@]}"
 297 #echo ====
 298
 299     if [ ${#PIDS_SOUGHT[*]} -ne 0 ]; then
 300       local PIDS_SOUGHT2=$(printf -- '%s\n' ${PIDS_SOUGHT[@]} | sort | uniq)
 301       PIDS_SOUGHT=()
 302       PIDS_SOUGHT=${PIDS_SOUGHT2[*]}
 303       echo ${PIDS_SOUGHT[*]}
 304     fi
 305     /bin/rm $PID_DUMP
 306   }
 307
 308   # finds all processes matching the pattern specified and shows their full
 309   # process listing (whereas psfind just lists process ids).
 310   function psa() {
 311     if [ -z "$1" ]; then
 312       echo "psa finds processes by pattern, but there was no pattern on the command line."
 313       return 1
 314     fi
 315     local -a patterns=("${@}")
 316     p=$(psfind "${patterns[@]}")
 317     if [ -z "$p" ]; then
 318       # no matches.
 319       return 0
 320     fi
 321
 322     if [ "${patterns[0]}" == "-u" ]; then
 323       # void the two elements with that user flag so we don't use them as patterns.
 324       unset patterns[0] patterns[1]=
 325     fi
 326
 327     echo ""
 328     echo "Processes matching ${patterns[@]}..."
 329     echo ""
 330     if [ -n "$IS_DARWIN" ]; then
 331       unset fuzil_sentinel
 332       for i in $p; do
 333         # only print the header the first time.
 334         if [ -z "$fuzil_sentinel" ]; then
 335           ps $i -w -u
 336         else
 337           ps $i -w -u | sed -e '1d'
 338         fi
 339         fuzil_sentinel=true
 340       done
 341     else
 342       # cases besides mac os x's darwin.
 343       if [ "$OS" == "Windows_NT" ]; then
 344         # special case for windows.
 345         ps | head -1
 346         for curr in $p; do
 347           ps -W -p $curr | tail -n +2
 348         done
 349       else
 350         # normal OSes can handle a nice simple query.
 351         ps wu $p
 352       fi
 353     fi
 354   }
 355
 356   ##############
 357
 358 #hmmm: holy crowbars, this is an old one.  do we ever still have any need of it?
 359   # an unfortunately similarly named function to the above 'ps' as in process
 360   # methods, but this 'ps' stands for postscript.  this takes a postscript file
 361   # and converts it into pcl3 printer language and then ships it to the printer.
 362   # this mostly makes sense for an environment where one's default printer is
 363   # pcl.  if the input postscript causes ghostscript to bomb out, there has been
 364   # some good success running ps2ps on the input file and using the cleaned
 365   # postscript file for printing.
 366   function ps2pcl2lpr() {
 367     for $i in $*; do
 368       gs -sDEVICE=pcl3 -sOutputFile=- -sPAPERSIZE=letter "$i" | lpr -l
 369     done
 370   }
 371
 372   function screen() {
 373     save_terminal_title
 374 #hmmm: ugly absolute path here.
 375     /usr/bin/screen $*
 376     restore_terminal_title
 377   }
 378
 379   # switches from a /X/path form to an X:/ form.  this also processes cygwin paths.
 380   function unix_to_dos_path() {
 381     # we usually remove dos slashes in favor of forward slashes.
 382     local DOSSYHOME
 383     if [[ ! "$OS" =~ ^[Ww][iI][nN] ]]; then
 384       # fake this value for non-windows (non-cygwin) platforms.
 385       DOSSYHOME="$HOME"
 386     else
 387       # for cygwin, we must replace the /home/X path with an absolute one, since cygwin
 388       # insists on the /home form instead of /c/cygwin/home being possible.  this is
 389       # super frustrating and nightmarish.
 390       DOSSYHOME="$(cygpath -am "$HOME")"
 391     fi
 392
 393     if [ ! -z "$SERIOUS_SLASH_TREATMENT" ]; then
 394       # unless this flag is set, in which case we force dos slashes.
 395       echo "$1" | sed -e "s?^$HOME?$DOSSYHOME?g" | sed -e 's/\\/\//g' | sed -e 's/\/cygdrive//' | sed -e 's/\/\([a-zA-Z]\)\/\(.*\)/\1:\/\2/' | sed -e 's/\//\\/g'
 396     else
 397       echo "$1" | sed -e "s?^$HOME?$DOSSYHOME?g" | sed -e 's/\\/\//g' | sed -e 's/\/cygdrive//' | sed -e 's/\/\([a-zA-Z]\)\/\(.*\)/\1:\/\2/'
 398     fi
 399   }
 400
 401 #  # switches from an X:/ form to a /cygdrive/X/path form.  this is only useful
 402 #  # for the cygwin environment currently.
 403 #  function dos_to_unix_path() {
 404 #    # we always remove dos slashes in favor of forward slashes.
 405 ##old:    echo "$1" | sed -e 's/\\/\//g' | sed -e 's/\([a-zA-Z]\):\/\(.*\)/\/\1\/\2/'
 406 #         echo "$1" | sed -e 's/\\/\//g' | sed -e 's/\([a-zA-Z]\):\/\(.*\)/\/cygdrive\/\1\/\2/'
 407 #  }
 408
 409   # returns a successful value (0) if this system is debian or ubuntu.
 410   function debian_like() {
 411     # decide if we think this is debian or ubuntu or a variant.
 412     DEBIAN_LIKE=$(if [ ! -z "$(grep -i debian /etc/issue)" \
 413         -o ! -z "$(grep -i ubuntu /etc/issue)" ]; then echo 1; else echo 0; fi)
 414     if [ $DEBIAN_LIKE -eq 1 ]; then
 415       # success; this is debianish.
 416       return 0
 417     else
 418       # this seems like some other OS.
 419       return 1
 420     fi
 421   }
 422
 423   # this function wraps the normal sudo by ensuring we replace the terminal
 424   # label before we launch what they're passing to sudo.  we also preserve
 425   # specific variables that enable the main user's ssh credentials to still
 426   # be relied on for ssh forwarding, even if the '-i' flag is passed to cause
 427   # a fresh shell (which normally doesn't get the launching user's environment
 428   # variables).
 429   function sudo() {
 430     save_terminal_title
 431
 432     # hoist our X authorization info in case environment is passed along;
 433     # this can allow root to use our display to show X.org windows.
 434     if [ -z "$IMPORTED_XAUTH" -a ! -z "$DISPLAY" ]; then
 435       export IMPORTED_XAUTH="$(xauth list $DISPLAY | head -n 1 | awk '{print $3}')"
 436       local REMOVE_IMP_XAUTH=true
 437     fi
 438
 439     # launch sudo with just the variables we want to reach the other side.
 440     # we take an extra step to null out the PATH, since MacOS seems to want
 441     # to pass that even for a login shell (-i) somehow.
 442     local varmods="PATH= "
 443     if [ ! -z "$IMPORTED_XAUTH" ]; then varmods+="IMPORTED_XAUTH=$IMPORTED_XAUTH "; fi
 444     if [ ! -z "$SSH_AUTH_SOCK" ]; then varmods+="SSH_AUTH_SOCK=$SSH_AUTH_SOCK"; fi
 445     /usr/bin/sudo $varmods "$@"
 446     retval=$?
 447
 448     # take the xauth info away again if it wasn't set already.
 449     if [ ! -z "$REMOVE_IMP_XAUTH" ]; then
 450       unset IMPORTED_XAUTH
 451     fi
 452     restore_terminal_title
 453     return $retval
 454   }
 455
 456   # trashes the .#blah files that cvs and subversion leave behind when finding conflicts.
 457   # this kind of assumes you've already checked them for any salient facts.
 458   function clean_cvs_junk() {
 459     for i in $*; do
 460       find $i -follow -type f -iname ".#*" -exec perl $FEISTY_MEOW_SCRIPTS/files/safedel.pl {} ";"
 461     done
 462   }
 463
 464   # overlay for nechung binary so that we can complain less grossly about it when it's missing.
 465   function nechung() {
 466     local wheres_nechung=$(whichable nechung)
 467     if [ -z "$wheres_nechung" ]; then
 468       echo "The nechung oracle program cannot be found.  You may want to consider"
 469       echo "rebuilding the feisty meow applications with this command:"
 470       echo "bash $FEISTY_MEOW_SCRIPTS/generator/produce_feisty_meow.sh"
 471       echo
 472     else
 473       $wheres_nechung
 474     fi
 475   }
 476
 477   # recreates all the generated files that the feisty meow scripts use.
 478   function regenerate() {
 479     # do the bootstrapping process again.
 480     save_terminal_title
 481     echo "regenerating feisty meow script environment."
 482     bash $FEISTY_MEOW_SCRIPTS/core/reconfigure_feisty_meow.sh
 483     echo
 484     # force a full reload by turning off sentinel variables and methods.
 485     unset -v CORE_VARIABLES_LOADED FEISTY_MEOW_LOADING_DOCK USER_CUSTOMIZATIONS_LOADED
 486     unalias CORE_ALIASES_LOADED &>/dev/null
 487     unset -f function_sentinel
 488     # reload feisty meow environment in current shell.
 489     log_feisty_meow_event "reloading the feisty meow scripts for $USER in current shell."
 490     source "$FEISTY_MEOW_SCRIPTS/core/launch_feisty_meow.sh"
 491     # run nechung oracle to give user a new fortune.
 492     nechung
 493     restore_terminal_title
 494   }
 495
 496   # merges a set of custom scripts into the feisty meow environment.  can be
 497   # passed a name to use as the custom scripts source folder (found on path
 498   # $FEISTY_MEOW_SCRIPTS/customize/{name}), or it will try to guess the name
 499   # by using the login name.
 500   function recustomize()
 501   {
 502     local custom_user="$1"; shift
 503     if [ -z "$custom_user" ]; then
 504       # default to login name if there was no name provided.
 505       custom_user="$(fm_username)"
 506         # we do intend to use the login name here to get the login name and to ignore
 507         # if the user has sudo root access; we don't want to provide a custom
 508         # profile for root.
 509     fi
 510     # chop off any email address style formatting to leave just the name.
 511     custom_user="$(echo "$custom_user" | cut -f1 -d'@')"
 512
 513     save_terminal_title
 514
 515     if [ ! -d "$FEISTY_MEOW_SCRIPTS/customize/$custom_user" ]; then
 516       echo -e "the customization folder for '$custom_user' is missing:
 517
 518     $FEISTY_MEOW_SCRIPTS/customize/$custom_user
 519
 520 we will skip recustomization, but these other customizations are available:
 521 "
 522       # a little tr and sed magic to fix the carriage returns into commas.
 523       local line="$(find $FEISTY_MEOW_SCRIPTS/customize -mindepth 1 -maxdepth 1 -type d -exec basename {} ';' | tr '\n' '&' | sed 's/&/, /g' | sed -e 's/, $//')"
 524         # make the line feeds and carriage returns manageable with tr.
 525         # convert the ampersand, our weird replacement for EOL, with a comma + space in sed.
 526         # last touch with sed removes the last comma.
 527       echo "    $line"
 528       return 1
 529     fi
 530
 531     # recreate the feisty meow loading dock.
 532     regenerate >/dev/null
 533
 534     # jump into the loading dock and make our custom link.
 535     pushd "$FEISTY_MEOW_LOADING_DOCK" &>/dev/null
 536     if [ -h custom ]; then
 537       # there's an existing link, so remove it.
 538       \rm custom
 539     fi
 540     # make sure we cleaned up the area before we re-link.
 541     if [ -h custom -o -d custom -o -f custom ]; then
 542       echo "
 543 Due to an over-abundance of caution, we are not going to remove an unexpected
 544 'custom' object found in the file system.  This object is located in the
 545 feisty meow loading dock here: $(pwd)
 546 And here is a description of the rogue 'custom' object:
 547 "
 548       ls -al custom
 549       echo "
 550 If you are pretty sure that this is just a remnant of an older approach in
 551 feisty meow, where we copied the custom directory rather than linking it
 552 (and it most likely is just such a bit of cruft of that nature), then please
 553 remove that old remnant 'custom' item, for example by saying:
 554   /bin/rm -rf \"custom\" ; popd
 555 Sorry for the interruption, but we want to make sure this removal wasn't
 556 automatic if there is even a small amount of doubt about the issue."
 557       return 1
 558     fi
 559
 560     # create the custom folder as a link to the customizations.
 561     ln -s "$FEISTY_MEOW_SCRIPTS/customize/$custom_user" custom
 562
 563     popd &>/dev/null
 564
 565     # now take into account all the customizations by regenerating the feisty meow environment.
 566     regenerate
 567
 568     restore_terminal_title
 569   }
 570
 571   # generates a random password where the first parameter is the number of characters
 572   # in the password (default 20) and the second parameter specifies whether to use
 573   # special characters (1) or not (0).
 574   # found function at http://legroom.net/2010/05/06/bash-random-password-generator
 575   function random_password()
 576   {
 577     [ "$2" == "0" ] && CHAR="[:alnum:]" || CHAR="[:graph:]"
 578     cat /dev/urandom | tr -cd "$CHAR" | head -c ${1:-32}
 579     echo
 580   }
 581
 582   function add_cygwin_drive_mounts() {
 583     for i in c d e f g h q z ; do
 584 #hmmm: improve this by not adding the link if already there, or if the drive is not valid.
 585       ln -s /cygdrive/$i $i
 586     done
 587   }
 588
 589   ############################
 590
 591   # takes a file to modify, and then it will replace any occurrences of the
 592   # pattern provided as the second parameter with the text in the third
 593   # parameter.
 594   function replace_pattern_in_file()
 595   {
 596     local file="$1"; shift
 597     local pattern="$1"; shift
 598     local replacement="$1"; shift
 599     if [ -z "$file" -o -z "$pattern" -o -z "$replacement" ]; then
 600       echo "replace_pattern_in_file: needs a filename, a pattern to replace, and the"
 601       echo "text to replace that pattern with."
 602       return 1
 603     fi
 604     sed -i -e "s%$pattern%$replacement%g" "$file"
 605   }
 606
 607   # similar to replace_pattern_in_file, but also will add the new value
 608   # when the old one did not already exist in the file.
 609   function replace_if_exists_or_add()
 610   {
 611     local file="$1"; shift
 612     local phrase="$1"; shift
 613     local replacement="$1"; shift
 614     if [ -z "$file" -o ! -f "$file" -o -z "$phrase" -o -z "$replacement" ]; then
 615       echo "replace_if_exists_or_add: needs a filename, a phrase to replace, and the"
 616       echo "text to replace that phrase with."
 617       return 1
 618     fi
 619     grep "$phrase" "$file" >/dev/null
 620     # replace if the phrase is there, otherwise add it.
 621     if [ $? -eq 0 ]; then
 622       replace_pattern_in_file "$file" "$phrase" "$replacement"
 623     else
 624       # this had better be the complete line.
 625       echo "$replacement" >>"$file"
 626     fi
 627   }
 628
 629   ############################
 630
 631   # finds a variable (first parameter) in a particular property file
 632   # (second parameter).  the expected format for the file is:
 633   # varX=valueX
 634   function seek_variable()
 635   {
 636     local find_var="$1"; shift
 637     local file="$1"; shift
 638     if [ -z "$find_var" -o -z "$file" -o ! -f "$file" ]; then
 639       echo -e "seek_variable: needs two parameters, firstly a variable name, and\nsecondly a file where the variable's value will be sought." 1>&2
 640       return 1
 641     fi
 642
 643     while read line; do
 644       if [ ${#line} -eq 0 ]; then continue; fi
 645       # split the line into the variable name and value.
 646       IFS='=' read -a assignment <<< "$line"
 647       local var="${assignment[0]}"
 648       local value="${assignment[1]}"
 649       if [ "${value:0:1}" == '"' ]; then
 650         # assume the entry was in quotes and remove them.
 651         value="${value:1:$((${#value} - 2))}"
 652       fi
 653       if [ "$find_var" == "$var" ]; then
 654         echo "$value"
 655       fi
 656     done < "$file"
 657   }
 658
 659   # finds a variable (first parameter) in a particular XML format file
 660   # (second parameter).  the expected format for the file is:
 661   # ... name="varX" value="valueX" ...
 662   function seek_variable_in_xml()
 663   {
 664     local find_var="$1"; shift
 665     local file="$1"; shift
 666     if [ -z "$find_var" -o -z "$file" -o ! -f "$file" ]; then
 667       echo "seek_variable_in_xml: needs two parameters, firstly a variable name, and"
 668       echo "secondly an XML file where the variable's value will be sought."
 669       return 1
 670     fi
 671
 672     while read line; do
 673       if [ ${#line} -eq 0 ]; then continue; fi
 674       # process the line to make it more conventional looking.
 675       line="$(echo "$line" | sed -e 's/.*name="\([^"]*\)" value="\([^"]*\)"/\1=\2/')"
 676       # split the line into the variable name and value.
 677       IFS='=' read -a assignment <<< "$line"
 678       local var="${assignment[0]}"
 679       local value="${assignment[1]}"
 680       if [ "${value:0:1}" == '"' ]; then
 681         # assume the entry was in quotes and remove them.
 682         value="${value:1:$((${#value} - 2))}"
 683       fi
 684       if [ "$find_var" == "$var" ]; then
 685         echo "$value"
 686       fi
 687     done < "$file"
 688   }
 689
 690   ############################
 691
 692   # goes to a particular directory passed as parameter 1, and then removes all
 693   # the parameters after that from that directory.
 694   function push_whack_pop()
 695   {
 696     local dir="$1"; shift
 697     pushd "$dir" &>/dev/null
 698     if [ $? -ne 0 ]; then echo failed to enter dir--quitting.; fi
 699     rm -rf $* &>/dev/null
 700     if [ $? -ne 0 ]; then echo received a failure code when removing.; fi
 701     popd &>/dev/null
 702   }
 703
 704   ##############
 705
 706 # new breed of definer functions goes here.  still in progress.
 707
 708   # defines an alias and remembers that this is a new or modified definition.
 709   # if the feisty meow codebase is unloaded, then so are all the aliases that
 710   # were defined.
 711   function define_yeti_alias()
 712   {
 713 # if alias exists already, save old value for restore,
 714 # otherwise save null value for restore,
 715 # have to handle unaliasing if there was no prior value of one
 716 # we newly defined.
 717 # add alias name to a list of feisty defined aliases.
 718
 719 #hmmm: first implem, just do the alias and get that working...
 720 alias "${@}"
 721
 722
 723 return 0
 724   }
 725
 726   ##############
 727
 728 #hmmm: this points to an extended functions file being needed; not all of these are core.
 729
 730   # displays documentation in "md" formatted files.
 731   function show_md()
 732   {
 733     local file="$1"; shift
 734     pandoc "$file" | lynx -stdin
 735   }
 736
 737   ##############
 738
 739   # just shows a separator line for an 80 column console, or uses the first
 740   # parameter as the number of columns to expect.
 741   function separator()
 742   {
 743     count=$1; shift
 744     if [ -z "$count" ]; then
 745       count=79
 746     fi
 747     echo
 748     local i
 749     for ((i=0; i < $count - 1; i++)); do
 750       echo -n "="
 751     done
 752     echo
 753     echo
 754   }
 755   # alias for separator.
 756   function sep()
 757   {
 758     separator $*
 759   }
 760
 761   ##############
 762
 763   # count the number of sub-directories in a directory and echo the result.
 764   function count_directories()
 765   {
 766     local subbydir="$1"; shift
 767     numdirs="$(find "$subbydir" -mindepth 1 -maxdepth 1 -type d | wc -l)"
 768     echo $numdirs
 769   }
 770
 771   # takes a string and capitalizes just the first character.  any capital letters in the remainder of
 772   # the string are made lower case.  the processed string is returned by an echo.
 773   function capitalize_first_char()
 774   {
 775     local to_dromedary="$1"; shift
 776     to_dromedary="$(tr '[:lower:]' '[:upper:]' <<< ${to_dromedary:0:1})$(tr '[:upper:]' '[:lower:]' <<< ${to_dromedary:1})"
 777     echo "$to_dromedary"
 778   }
 779
 780   # given a source path and a target path, this will make a symbolic link from
 781   # the source to the destination, but only if the source actually exists.
 782   function make_safe_link()
 783   {
 784     local src="$1"; shift
 785     local target="$1"; shift
 786
 787     if [ -d "$src" ]; then
 788       ln -s "$src" "$target"
 789       exit_on_error "Creating symlink from '$src' to '$target'"
 790     fi
 791     echo "Created symlink from '$src' to '$target'."
 792   }
 793
 794   # pretty prints the json files provided as parameters.
 795   function clean_json()
 796   {
 797     if [ -z "$*" ]; then return; fi
 798     local show_list=()
 799     while true; do
 800       local file="$1"; shift
 801       if [ -z "$file" ]; then break; fi
 802       if [ ! -f "$file" ]; then "echo File '$file' does not exist."; continue; fi
 803       temp_out="$TMP/$file.view"
 804       cat "$file" | python -m json.tool > "$temp_out"
 805       show_list+=($temp_out)
 806       continue_on_error "pretty printing '$file'"
 807     done
 808     filedump "${show_list[@]}"
 809     rm "${show_list[@]}"
 810   }
 811
 812   function json_text()
 813   {
 814     # only print our special headers or text fields.
 815     local CR=$'\r'
 816     local LF=$'\n'
 817     clean_json $* |
 818         grep -i "\"text\":\|^=.*" |
 819         sed -e "s/\\\\r/$CR/g" -e "s/\\\\n/\\$LF/g"
 820   }
 821
 822   ##############
 823
 824   # echoes the machine's hostname.  can be used like so:
 825   #   local my_host=$(get_hostname)
 826   function get_hostname()
 827   {
 828     # there used to be more variation in how to do this, but adopting mingw
 829     # and cygwin tools really helped out.
 830     local this_host=unknown
 831     if [ "$OS" == "Windows_NT" ]; then
 832       this_host=$(hostname)
 833     elif [ ! -z "$(echo $MACHTYPE | grep apple)" ]; then
 834       this_host=$(hostname)
 835     elif [ ! -z "$(echo $MACHTYPE | grep suse)" ]; then
 836       this_host=$(hostname --long)
 837     elif [ -x "$(whichable hostname)" ]; then
 838       this_host=$(hostname)
 839     fi
 840     echo "$this_host"
 841   }
 842
 843   # makes sure that the provided "folder" is a directory and is writable.
 844   function test_writeable()
 845   {
 846     local folder="$1"; shift
 847     if [ ! -d "$folder" -o ! -w "$folder" ]; then return 1; fi
 848     return 0
 849   }
 850
 851   ##############
 852
 853   # given a filename and a string to seek and a number of lines, then this
 854   # function will remove the first occurrence of a line in the file that
 855   # matches the string, and it will also axe the next N lines as specified.
 856   function create_chomped_copy_of_file()
 857   {
 858     local filename="$1"; shift
 859     local seeker="$1"; shift
 860     local numlines=$1; shift
 861
 862 #echo into create_chomped_copy...
 863 #var filename seeker numlines
 864
 865     # make a backup first, oy.
 866     \cp -f "$filename" "/tmp/$(basename ${filename}).bkup-${RANDOM}"
 867     exit_on_error "backing up file: $filename"
 868
 869     # make a temp file to write to before we move file into place in bind.
 870     local new_version="/tmp/$(basename ${filename}).bkup-${RANDOM}"
 871     \rm -f "$new_version"
 872     exit_on_error "cleaning out new version of file from: $new_version"
 873
 874     local line
 875     local skip_count=0
 876     local found_any=
 877     while read line; do
 878       # don't bother looking at the lines if we're already in skip mode.
 879       if [[ $skip_count == 0 ]]; then
 880         # find the string they're seeking.
 881         if [[ ! "$line" =~ .*${seeker}.* ]]; then
 882           # no match.
 883           echo "$line" >> "$new_version"
 884         else
 885           # a match!  start skipping.  we will delete this line and the next N lines.
 886           ((skip_count++))
 887 #echo first skip count is now $skip_count
 888           found_any=yes
 889         fi
 890       else
 891         # we're already skipping.  let's keep going until we hit the limit.
 892         ((skip_count++))
 893 #echo ongoing skip count is now $skip_count
 894         if (( $skip_count > $numlines )); then
 895           echo "Done skipping, and back to writing output file."
 896           skip_count=0
 897         fi
 898       fi
 899     done < "$filename"
 900
 901 #echo file we created looks like this:
 902 #cat "$new_version"
 903
 904     if [ ! -z "$found_any" ]; then
 905       # put the file back into place under the original name.
 906       \mv "$new_version" "$filename"
 907       exit_on_error "moving the new version into place in: $filename"
 908     else
 909       # cannot always be considered an error, but we can at least gripe.
 910       echo "Did not find any matches for seeker '$seeker' in file: $filename"
 911     fi
 912   }
 913
 914   ##############
 915
 916   # space 'em all: fixes naming for all of the files of the appropriate types
 917   # in the directories specified.
 918   function spacemall() {
 919     local -a dirs=("${@}")
 920     if [ ${#dirs[@]} -eq 0 ]; then
 921       dirs=(.)
 922     fi
 923
 924     local charnfile="$(mktemp $TMP/zz_charn.XXXXXX)"
 925     find "${dirs[@]}" -follow -maxdepth 1 -mindepth 1 -type f | \
 926         grep -i \
 927 "doc\|docx\|eml\|html\|jpeg\|jpg\|m4a\|mov\|mp3\|ods\|odt\|pdf\|png\|ppt\|pptx\|txt\|vsd\|vsdx\|xls\|xlsx\|zip" | \
 928         sed -e 's/^/"/' | sed -e 's/$/"/' | \
 929         xargs bash "$FEISTY_MEOW_SCRIPTS/files/spacem.sh"
 930     # drop the temp file now that we're done.
 931     rm "$charnfile"
 932   }
 933
 934   ##############
 935
 936   # site avenger aliases
 937   function switchto()
 938   {
 939     THISDIR="$FEISTY_MEOW_SCRIPTS/site_avenger"
 940     source "$FEISTY_MEOW_SCRIPTS/site_avenger/shared_site_mgr.sh"
 941     switch_to "$1"
 942   }
 943
 944   ##############
 945
 946   # you have hit the borderline functional zone...
 947
 948 #hmmm: not really doing anything yet; ubuntu seems to have changed from pulseaudio in 17.04?
 949   # restarts the sound driver.
 950   function fix_sound_driver() {
 951     # stop bash complaining about blank function body.
 952     local nothing=
 953 #if alsa something
 954 #    sudo service alsasound restart
 955 #elif pulse something
 956 #    sudo pulseaudio -k
 957 #    sudo pulseaudio -D
 958 #else
 959 #    something else...?
 960 #fi
 961
 962   }
 963
 964   # ...and here's the end of the borderline functional zone.
 965
 966   ##############
 967
 968   # NOTE: no more function definitions are allowed after this point.
 969
 970   function function_sentinel()
 971   {
 972     return 0;
 973   }
 974
 975   if [ ! -z "$DEBUG_FEISTY_MEOW" ]; then echo "feisty meow function definitions done."; fi
 976
 977   ##############
 978
 979   # test code for set_var_if_undefined.
 980   run_test=0
 981   if [ $run_test != 0 ]; then
 982     echo running tests on set_var_if_undefined.
 983     flagrant=petunia
 984     set_var_if_undefined flagrant forknordle
 985     exit_on_error "testing if defined variable would be whacked"
 986     if [ $flagrant != petunia ]; then
 987       echo set_var_if_undefined failed to leave the test variable alone
 988       exit 1
 989     fi
 990     unset bobblehead_stomper
 991     set_var_if_undefined bobblehead_stomper endurance
 992     if [ $bobblehead_stomper != endurance ]; then
 993       echo set_var_if_undefined failed to set a variable that was not defined yet
 994       exit 1
 995     fi
 996   fi
 997
 998 fi
 999