#!/bin/bash
APP_SVNID='$HeadURL$ $LastChangedRevision$'

. $(ade-config ade_share_prefix)/include/ade.sh || { echo "${0##*/}: INTERNAL ERROR: failed to load ade.sh" >&2; exit 3; }

WRA_DEFINED_ERRORS=(
    "KEY=WRA_ERR_MISC; FMT=\"%s\""
)

#  Other globals
MAX_VOLUME=100
WRA_SHARE_PREFIX=$(wra-config wra_share_prefix)
INIT_WRARC=$WRA_SHARE_PREFIX/wrarc
FADEIN_STEP_INTERVAL=5
HELPER_DIRS=( $HOME/.config/${ADE_APP_PROGNAME}/helpers $WRA_SHARE_PREFIX/helpers )
declare -A STATION_HASH

wra()
{
    local ERRSTACK_REF="$1"; shift
    local OPTVAL RC USERSEL_STATION 
    local -a DOLLARAT

    ###########################################################################
    #
    #  SET ADE OPTIONS
    #
    ###########################################################################

    #  Register application-specific errors
    ade_err_registerdefderrs WRA_DEFINED_ERRORS

    ###########################################################################
    #
    #  PROCESS OPTIONS
    #
    ###########################################################################

    #  Defaults for options
    OPT_MODE=normal
    #  There's no nice way to determine the .config dir. Stephen Kitt on
    #  https://unix.stackexchange.com/questions/726717 suggests to use 
    #  ${XDG_CONFIG_HOME:-$HOME/.config}.
    OPT_RC_FILE=${XDG_CONFIG_HOME:-$HOME/.config}/$ADE_APP_PROGNAME/${ADE_APP_PROGNAME}rc

    #  Register wra's options 
    ade_opt_register "$ERRSTACK_REF" -o fl --longoptions=config-file:,list-stations --callback-template="wra_opt_handler_%s" || return $?
    ade_msg_register "$ERRSTACK_REF" wra_usage wra_version wra_listpaths || return $?

    #  Process options
    ade_opt_process "$ERRSTACK_REF" NEW_DOLLAR_AT "$@" || return $?
    set -- "${NEW_DOLLAR_AT[@]}" 

    #  Process arguments
    #  (later)

    #  Sanity checks and derivations
    ade_err_resetstack "$ERRSTACK_REF" writers="_ade_msg_writer_stderr _ade_msg_writer_logfile" logfile=/tmp/wra.$$.log
    #  Create rc file if none exists.
    #  The rc file used to be a file, then it was a symlink to a package-provided
    #  rc file, but now, in order to support personal helper scripts, we need it
    #  to be a directory. All these possibilties require some careful handling.
    if [ -h ~/.wrarc ] && [[ $(readlink ~/.wrarc) =~ .*/usr/share/wra/wrarc$ ]] && [ ! -h $OPT_RC_FILE -a ! -e $OPT_RC_FILE ]; then
        #  ~/.wrarc is a symlink, points to the package provided-file, so it can be recreated in ~/.config/wra/
        rm ~/.wrarc
        mkdir -p ${OPT_RC_FILE%/*}
        ln -sr $INIT_WRARC $OPT_RC_FILE
    elif [ -h ~/.wrarc ]; then
       ade_err_error "$ERRSTACK_REF" WRA_ERR_MISC "~/.wrarc is a non-standard symlink (hint: resolve this yourself)"
       return $ADE_ERR_FAIL
    elif [ -f ~/.wrarc ] && [ ! -h $OPT_RC_FILE -a ! -e $OPT_RC_FILE ]; then
        mkdir -p ${OPT_RC_FILE%/*}
        mv ~/.wrarc $OPT_RC_FILE
    elif [ -f ~/.wrarc ]; then
       ade_err_error "$ERRSTACK_REF" WRA_ERR_MISC "~/.wrarc is a file but new location already exists (hint: resolve this yourself)"
       return $ADE_ERR_FAIL
    elif [ -e ~/.wrarc ]; then
       ade_err_error "$ERRSTACK_REF" WRA_ERR_MISC  "~/.wrarc exists but is not a file or a symlink (hint: resolve this yourself)"
       return $ADE_ERR_FAIL
    elif [ ! -h $OPT_RC_FILE -a ! -e $OPT_RC_FILE ]; then
        mkdir -p ${OPT_RC_FILE%/*}
        ln -sr $INIT_WRARC $OPT_RC_FILE
    elif [ -h $OPT_RC_FILE ] && [[ $(readlink $OPT_RC_FILE) =~ .*/usr/share/wra/wrarc$ ]]; then
        :
    else
        ade_err_warning "$ERRSTACK_REF" WRA_ERR_MISC "custom wrarc"
    fi

    #  Load configuration.
    ade_err_debug "$ERRSTACK_REF" 10 "wra: checking $OPT_RC_FILE is loadable ..."
    sh -c "station() { :; }; helper() { :; }; . $OPT_RC_FILE > /dev/null 2>&1" || { 
        ade_err_error "$ERRSTACK_REF" WRA_ERR_MISC "$OPT_RC_FILE: not loadable (hint: check quoting, ...)"
        return $ADE_ERR_FAIL
    }
    ade_err_debug "$ERRSTACK_REF" 10 "wra: loading $OPT_RC_FILE ..."
    #  See comments below in station() function regarding STATION_AGGREGATED_RC.
    STATION_AGGREGATED_RC=$ADE_ERR_OK
    . $OPT_RC_FILE
    if [ $STATION_AGGREGATED_RC != $ADE_ERR_OK ]; then
        return $STATION_AGGREGATED_RC
    fi

    #  Guts
    mode_$OPT_MODE "$@" || return $?

    return $ADE_ERR_OK
}

mode_list()
{
    local ERRSTACK_REF="$1"; shift
    local STATION DEFAULT DESCRIPTION IS_DEFAULT_STATION_FLAG STATIONS

    #  'sort -u' is because there are multiple entries in the hash for each station,
    #  namely each of the second keys ('description', 'is_default', etc).
    STATIONS=( $(echo ${!STATION_HASH[*]} | xargs -n 1 echo | sed 's/,[^ ]*//' | sort -u) )
    #  Get longest station name
    LONGEST_STATION_LENGTH=0
    for STATION in ${STATIONS[*]}; do
        if [ ${#STATION} -gt $LONGEST_STATION_LENGTH ]; then
            LONGEST_STATION_LENGTH=${#STATION}
        fi
    done
    #  Get longest station description
    LONGEST_DESCRIPTION_LENGTH=0
    for STATION in ${STATIONS[*]}; do
        read_multi_key_hash_entry "$ERRSTACK_REF" $STATION description DESCRIPTION
        if [ ${#DESCRIPTION} -gt $LONGEST_DESCRIPTION_LENGTH ]; then
            LONGEST_DESCRIPTION_LENGTH=${#DESCRIPTION}
        fi
    done
    if [ -t 1 ]; then
        # Get screen width
        eval `resize -u`
        #  How many chars to display each station? Add '2' for ': ' and '4' is inter-column spacing
        RECORD_LENGTH=$(( LONGEST_STATION_LENGTH + LONGEST_DESCRIPTION_LENGTH + 2 + 4))
        #  To calculate the number of columns we can display *and the number of inter-column
        #  4-spaces is much eased if we add 4 to the width of the screen and then divide
        #  by the record length.
        RECORDS_PER_LINE_COUNT=$(( (COLUMNS+4) / RECORD_LENGTH ))
    else
        RECORDS_PER_LINE_COUNT=1
    fi
    I=0
    for STATION in ${STATIONS[*]}; do
        read_multi_key_hash_entry "$ERRSTACK_REF" $STATION is_default IS_DEFAULT_STATION_FLAG
        read_multi_key_hash_entry "$ERRSTACK_REF" $STATION description DESCRIPTION
        #  The printfs below work fine except for diacriticals, which are get wrongly
        #  padded (bash's print things that 'á' is 2 chars long, so adds extra spaces
        #  than after 'a' for example). Accordingly, we need to add an adjustment to
        #  the padding. Most of time time this adjustment is zero, because most of
        #  the time there are no diacriticals. The adjustment is the difference between
        #  'wc -c' and 'wc -m'. See https://unix.stackexchange.com/questions/609125/padding-unicode-strings-with-bashs-printf.
        ADJUSTMENT=$(( $(wc -m <<<"$DESCRIPTION") - $(wc -c <<<"$DESCRIPTION") ))
        if $IS_DEFAULT_STATION_FLAG; then
            BOLD_ON_OR_EMPTY=$(tput smso)
            BOLD_OFF_OR_EMPTY=$(tput rmso)
        else
            BOLD_ON_OR_EMPTY=
            BOLD_OFF_OR_EMPTY=
        fi
        #  +1 is because the ':' is displayed as part of station name to avoid mis-padding.
        printf -v RECORD "%-$((LONGEST_STATION_LENGTH+1))s %-$((LONGEST_DESCRIPTION_LENGTH-ADJUSTMENT))s" "$STATION$ASTERISK_OR_NOTHING:" "$DESCRIPTION"
        #  If we're displaying the last record on the line then don't add inter-column spacing but do add newline.
        if ((I % RECORDS_PER_LINE_COUNT == RECORDS_PER_LINE_COUNT - 1)); then
            echo "$BOLD_ON_OR_EMPTY$RECORD$BOLD_OFF_OR_EMPTY"
        #  If we're (not displaying the last record on the line and) we're displaying the final record add newline.
        elif ((I == ${#STATIONS[*]} - 1)); then
            echo "$BOLD_ON_OR_EMPTY$RECORD$BOLD_OFF_OR_EMPTY"
        #  If we're (not displaying the last record on the line and it's not the final record and) we're displaying 
        #  non-last-record-on-line then do add inter-column padding but don't add newline.
        else
            echo -n "$BOLD_ON_OR_EMPTY$RECORD$BOLD_OFF_OR_EMPTY    "
        fi
        ((I++))
    done

    return $ADE_ERR_OK
}

mode_normal()
{
    local CHECK EXPECT

    #  Process arguments twice. Once as a check and once for real.
    for CHECK in true false; do
        #  STOP_ALL_HELPERS_FLAG is only used if CHECK is false. It is used
        #  to tell start_station() or stop_station() that they don't know
        #  which helpers (if any) are active, so they should stop all helpers
        #  before starting a station of stopping a helper.
        STOP_ALL_HELPERS_FLAG=true
        EXPECT=onorofforstation
        for ARG in "$@"; do
            ade_err_debug "$ERRSTACK_REF" 10 "wra: CHECK=$CHECK, EXPECT=$EXPECT, ARG=$ARG"
            if [ $EXPECT = on -a $ARG = on ]; then
                EXPECT=ontime
            elif [ $EXPECT = on ]; then
                ade_msg_usage "$ERRSTACK_REF"
            elif [ $EXPECT = off -a $ARG = off ]; then
                EXPECT=offtime
            elif [ $EXPECT = off ]; then
                ade_msg_usage "$ERRSTACK_REF"
            elif [ $EXPECT = onoroff -a $ARG = on ]; then
                EXPECT=ontime
            elif [ $EXPECT = onoroff -a $ARG = off ]; then
                EXPECT=offtime
            elif [ $EXPECT = onoroff ]; then
                ade_msg_usage "$ERRSTACK_REF"
            elif [ $EXPECT = onorofforstation -a $ARG = on ]; then
                EXPECT=ontime
            elif [ $EXPECT = onorofforstation -a $ARG = off ]; then
                EXPECT=offtime
            elif [ $EXPECT = onorofforstation ]; then
                validate_station "$ERRSTACK_REF" "$ARG" || return $?
                $CHECK || process_station "$ERRSTACK_REF" $ARG || return $?
                EXPECT=onoroff
            elif [ $EXPECT = onorstation -a $ARG = on ]; then
                EXPECT=ontime
            elif [ $EXPECT = onorstation ]; then
                validate_station "$ERRSTACK_REF" "$ARG" || return $?
                $CHECK || process_station "$ERRSTACK_REF" $ARG || return $?
                EXPECT=on
            elif [ $EXPECT = offorstation -a $ARG = off ]; then
                EXPECT=offtime
            elif [ $EXPECT = offorstation ]; then
                validate_station "$ERRSTACK_REF" "$ARG" || return $?
                $CHECK || process_station "$ERRSTACK_REF" $ARG || return $?
                EXPECT=off
            elif [ $EXPECT = ontime ]; then
                validate_time "$ERRSTACK_REF" "$ARG" || return $?
                $CHECK || process_ontime "$ERRSTACK_REF" $ARG || return $?
                EXPECT=offorstation
            elif [ $EXPECT = offtime ]; then
                validate_time "$ERRSTACK_REF" "$ARG" || return $?
                $CHECK || process_offtime "$ERRSTACK_REF" $ARG || return $?
                EXPECT=onorstation
            else
                ade_msg_usage "$ERRSTACK_REF"
            fi
        done
        #  Check last argument left state engine in an acceptable state
        [ $EXPECT = onorstation -o $EXPECT = offorstation ] || ade_msg_usage "$ERRSTACK_REF"
    done
      
    return $ADE_ERR_OK
}

wra_opt_handler_l()
{
    wra_opt_handler_list_stations "$@"
}

wra_opt_handler_list_stations()
{
    local ERRSTACK_REF="$1"; shift
   
    OPT_MODE=list

    return $ADE_ERR_OK
}

wra_opt_handler_f()
{
    wra_opt_handler_config_file "$@"
}

wra_opt_handler_config_file()
{
    local ERRSTACK_REF="$1"; shift

    OPT_RC_FILE="$1"

    return $ADE_ERR_OK
}

wra_usage() 
{
    local ERRSTACK_REF="$1"; shift
    local USAGETEXT_REF="$1"; shift
    local PASSNO=$1; shift

    if [ $PASSNO = 1 ]; then
        eval "$USAGETEXT_REF=\"{ on <time> | off <time> | <station> } ...\""
    elif [ $PASSNO = 2 ]; then
        eval "$USAGETEXT_REF=\"\
         -f <file> | --config-file=<file>    use alternate config file
         -l        | --list-stations         list defined stations

Times:   HHMM                                HH:MM
         now                                 now\""
    fi

    return $ADE_ERR_OK
}

wra_listpaths() 
{
    local ERRSTACK_REF="$1"; shift
    local PATHLIST_REF=$1; shift

    eval "$PATHLIST_REF=\"\""

    return $ADE_ERR_OK
} 

wra_version() 
{
    local ERRSTACK_REF="$1"; shift
    local VERSION_REF=$1; shift

    ade_smf_extractversionfromsvnstring "$ERRSTACK_REF" "$APP_SVNID" "$VERSION_REF"

    return $ADE_ERR_OK
} 

process_ontime()
{
    local ERRSTACK_REF="$1"; shift
    local ONTIME="$1"; shift

    #  Wait until prescribed time.
    if [ $ONTIME != now ]; then
       sleeptill "$ERRSTACK_REF" $ONTIME || return $?
       set_volume "$ERRSTACK_REF" 0      || return $?
    fi

    #  If nothing started yet then anything might be playing so turn all off.
    if $STOP_ALL_HELPERS_FLAG; then
        ade_err_debug "$ERRSTACK_REF" 10 "process_ontime: first time on, so turning EVERYTHING off first ..."
        stop_station "$ERRSTACK_REF" stop_all_helpers_cos_currently_active_station_unknown || return $?
        STOP_ALL_HELPERS_FLAG=false
    fi

    #  If no station selected yet select the default.
    [ "X$USERSEL_STATION" != X ] || get_default_station "$ERRSTACK_REF" USERSEL_STATION
 
    #  Start playing (at zero volume).
    start_station "$ERRSTACK_REF" "$USERSEL_STATION" || return $?

    #  Turn volume up.
    if [ $ONTIME = now ]; then
       set_volume_max_gradually "$ERRSTACK_REF" 0   || return $?
    else
       set_volume_max_gradually "$ERRSTACK_REF" 300 || return $?
    fi

    return $ADE_ERR_OK
}

process_offtime()
{
    local ERRSTACK_REF="$1"; shift
    local OFFTIME="$1"; shift

    #  Wait until prescribed time.
    if [ $OFFTIME != now ]; then
        sleeptill "$ERRSTACK_REF" $OFFTIME || return $?
    fi

    #  If nothing started yet then anything might be playing so turn all off.
    if $STOP_ALL_HELPERS_FLAG; then
        stop_station "$ERRSTACK_REF" stop_all_helpers_cos_currently_active_station_unknown || return $?
        STOP_ALL_HELPERS_FLAG=false

    #  Otherwise the user has selected something so we can turn that off.
    else 
        stop_station "$ERRSTACK_REF" "$USERSEL_STATION" || return $?
    fi

    return $ADE_ERR_OK
}

process_station()
{
    local ERRSTACK_REF="$1"; shift
    local STATION="$1"; shift

    USERSEL_STATION="$STATION"

    return $ADE_ERR_OK
}

start_station()
{
    local ERRSTACK_REF="$1"; shift
    local STATION="$1"; shift
    local URL HELPER

    ade_err_debug "$ERRSTACK_REF" 10 "start_station: starting (STATION=$STATION) ..."
    read_multi_key_hash_entry "$ERRSTACK_REF" $STATION helper HELPER
    canonicalise_helper "$ERRSTACK_REF" HELPER || return $?
    read_multi_key_hash_entry "$ERRSTACK_REF" $STATION url URL
    if ! eval "$HELPER --debug=$ADE_MSG_VERBOSELEVEL --server"; then
        ade_err_error "$ERRSTACK_REF" WRA_ERR_MISC "failed so start $HELPER server (hint: see messages above)"
        return $ADE_ERR_FAIL
    fi
    if ! eval "$HELPER --debug=$ADE_MSG_VERBOSELEVEL --submit \"\$URL\""; then
        ade_err_error "$ERRSTACK_REF" WRA_ERR_MISC "failed to submit URL to $HELPER server (hint: see messages above)"
        return $ADE_ERR_FAIL
    fi

    return $ADE_ERR_OK
}

canonicalise_helper()
{
    local HELPER_REF LOCAL_HELPER FOUND HELPER_DIR ERRSTACK_REF

    [ $# = 2 ] || ade_err_internal "$ERRSTACK_REF" "canonicalise_helper: $#: invalid argument count"
    ERRSTACK_REF=$1
    HELPER_REF=$2

    FOUND=false
    for HELPER_DIR in "${HELPER_DIRS[@]}"; do
        if eval "[ -x \"$HELPER_DIR/\$$HELPER_REF\" ]"; then
            FOUND=true
            break
        fi
    done
    if ! $FOUND; then
        ade_err_error "$ERRSTACK_REF" WRA_ERR_MISC "$HELPER: helper not found"
        return $ADE_ERR_FAIL
    fi
    eval "$HELPER_REF=\"$HELPER_DIR/\$$HELPER_REF\""
    return $ADE_ERR_OK
}

stop_station()
{
    local ERRSTACK_REF="$1"; shift
    local STATION="$1"; shift
    local HELPER 

    ade_err_debug "$ERRSTACK_REF" 10 "stop_station: stopping (STATION=$STATION) ..."

    #  If no station decided yet then we don't know which helpers to stop so stop all of them.
    if [ $STATION = stop_all_helpers_cos_currently_active_station_unknown ]; then
        ade_err_debug "$ERRSTACK_REF" 10 "stop_station: request is to stop all helpers"
        #  'ls A/ B/' results in output being divided into sections with section headers, so
        #  not easily parsable. 'ls A/; ls B/' is better formatted but requires a loop as the
        #  number of directories to list may grow. Instead we use 'find'. We discard find's
        #  stderr as the personal helper dir may not exist.
        for HELPER in $(find "${HELPER_DIRS[@]}" -mindepth 1 -maxdepth 1 -executable -printf "%f\n" 2>/dev/null | sort -u); do
            canonicalise_helper "$ERRSTACK_REF" HELPER || return $?
            if ! eval "$HELPER --debug=$ADE_MSG_VERBOSELEVEL --stop"; then
                ade_err_error "$ERRSTACK_REF" WRA_ERR_MISC "failed so stop $HELPER server (hint: see messages above)"
                return $ADE_ERR_FAIL
            fi
        done
    else
        ade_err_debug "$ERRSTACK_REF" 10 "stop_station: request is to stop only $HELPER helper"
        read_multi_key_hash_entry "$ERRSTACK_REF" $STATION helper HELPER
        canonicalise_helper "$ERRSTACK_REF" HELPER || return $?
        if ! eval "$HELPER --debug=$ADE_MSG_VERBOSELEVEL --stop"; then
            ade_err_error "$ERRSTACK_REF" WRA_ERR_MISC "failed so stop $HELPER server (hint: see messages above)"
            return $ADE_ERR_FAIL
        fi
    fi

    return $ADE_ERR_OK
}

validate_station()
{
    local ERRSTACK_REF STATION 
    local DESCRIPTION URL HELPER

    ERRSTACK_REF="$1"
    STATION="$2"

    read_multi_key_hash_entry "$ERRSTACK_REF" $STATION description DESCRIPTION
    read_multi_key_hash_entry "$ERRSTACK_REF" $STATION url         URL
    read_multi_key_hash_entry "$ERRSTACK_REF" $STATION helper      HELPER
    ade_err_debug "$ERRSTACK_REF" 100 "validate_station: STATION=$STATION, DESCRIPTION=\"$DESCRIPTION\", URL=\"$URL\", HELPER=$HELPER"

    return $ADE_ERR_OK
}

validate_time()
{
    local ERRSTACK_REF="$1"; shift
    local TIME="$1"; shift

    #  Fri Dec 26 10:19:58 CET 2008 - Alexis Huxley
    #  Previously we validated times using the following code:
    #
    #      expr "$TIME" : '\([0-9][0-9][0-9][0-9]\|now\)$' >/dev/null
    #
    #  But expr exits non-zero when the string evaluates to numerical zero,
    #  as the valid time '0000' does, so we can't use it. (This behaviour
    #  is described in the section of the expr man page dealing with exit
    #  codes.)
    if ! [[ $TIME =~ ^([0-2][0-9][0-5][0-9]|now)$ ]]; then
        ade_err_debug "$ERRSTACK_REF" 10 "validate_time: $TIME: invalid time"
        ade_msg_usage "$ERRSTACK_REF"
    fi
        
    return $ADE_ERR_OK
}
                    
set_volume()
{
    local ERRSTACK_REF="$1"; shift
    local VOL="$1"; shift
    local MIXER_CMDLINE DFLT_SINK_INDEX

    DFLT_SINK_INDEX=$(pacmd list-sinks | sed -n 's/^  \* index: //p')
    MIXER_CMDLINE="pactl set-sink-volume $DFLT_SINK_INDEX ${VOL%.*}%"
    ade_err_debug "$ERRSTACK_REF" 5 "set_volume: setting volume to $VOL by calling [$MIXER_CMDLINE] ..."
    if ! eval "$MIXER_CMDLINE"; then
        ade_err_error "$ERRSTACK_REF" WRA_ERR_MISC "failed to set volume (hint: see messages above)"
        return $ADE_ERR_FAIL
    fi

    return $ADE_ERR_OK
}

set_volume_max_gradually()
{
    local ERRSTACK_REF="$1"; shift
    local PERIOD="$1"; shift
    local VOLUME PASSED_PERIOD

    PASSED_PERIOD=0
    while [ $PASSED_PERIOD -lt $PERIOD ]; do
        VOLUME=$((PASSED_PERIOD*100/PERIOD))
        set_volume "$ERRSTACK_REF" $VOLUME
        sleep $FADEIN_STEP_INTERVAL
        PASSED_PERIOD=$((PASSED_PERIOD+FADEIN_STEP_INTERVAL))
    done
    set_volume "$ERRSTACK_REF" 100

    return $ADE_ERR_OK
}

sleeptill()
{
    local ERRSTACK_REF TIME PERIOD
    ERRSTACK_REF="$1"
    TIME="$2"

    #  This is wake-time minus now-time, with allowance for the date command assuming
    #  today's wake-time  even if that is in the past, rather than the *next* wake-time.
    #  E.g. if it's 12:00 now and you say to wake at 04:00 then date will assume *today's*
    #  04:00 rather than then next 04:00. To fix this, we add one day and then modulo one
    #  day.
    PERIOD=$((($(date -d "$TIME" +%s)-$(date +%s)+86400)%86400))
    ade_err_debug "$ERRSTACK_REF" 10 "sleeptill: PERIOD=$PERIOD"
    sleep $PERIOD
    ade_err_info "$ERRSTACK_REF" "wake time has arrived"

    return $ADE_ERR_OK
}
    
station()
{
    local STATION DESCRIPTION URL HELPER IS_DEFAULT_STATION_FLAG 

    [ $# = 4 ] || internal "station: $#: invalid argument count"
    STATION="$1"
    DESCRIPTION="$2"
    URL="$3"
    HELPER="$4"

    #  station() is actually called several times when ~/.wrarc 
    #  is sourced. Since we're *not* running in a 'set -e' environment,
    #  an individual station() call that fails, will not cause the
    #  wrapper (namely the sourcing of ~/.wrarc) to detect the failure
    #  and it itself fail. The only option is that the caller of 
    #  caller of station check whether station() reports any failures
    #  by examining a fail-count variable, which must start at zero.
    #  Anyway, back to this function. Were this function to put an
    #  error frame on the error stack *for each error that occurs in
    #  each call*, then they would be seen as a single stack of errors,
    #  which might possibly only have its top frame displayed. So 
    #  instead:
    #  - at the top of the function we return if there is already
    #    an error frame logged
    #  - else, in the event of an error, we add one error frame
    #    and set the a variable to note that there is an error.
    #  It's up to the caller's caller to initialise this variable
    #  and to return ADE_ERR_FAIL if it seems the flag set.
    if [ $STATION_AGGREGATED_RC = $ADE_ERR_FAIL ]; then
        return
    fi
    
    #  If station has has no attributes yet, then this is the first
    #  station to be registered and, as such, defines the default
    #  station.
    if [ ${#STATION_HASH[*]} = 0 ]; then
        IS_DEFAULT_STATION_FLAG=true
    else
        IS_DEFAULT_STATION_FLAG=false
    fi

    #  Validate the URL.
    if [ "X$URL" = X ]; then
        ade_err_error "$ERRSTACK_REF" WRA_ERR_MISC "$STATION: station has invalid URL (hint: check ~/.wrarc)"
	STATION_AGGREGATED_RC=$ADE_ERR_FAIL
        return
      
    fi
    #  Note we do this in subshell as the original (not-cananicalised) HELPER
    #  gets passed to write_multi_key_hash_entry() after this call.
    ( canonicalise_helper "$ERRSTACK_REF" HELPER ) || return $?

    #  Store station attributes hash.
    write_multi_key_hash_entry "$ERRSTACK_REF" $STATION description "$DESCRIPTION"   
    write_multi_key_hash_entry "$ERRSTACK_REF" $STATION url "$URL"   
    write_multi_key_hash_entry "$ERRSTACK_REF" $STATION helper "$HELPER"
    write_multi_key_hash_entry "$ERRSTACK_REF" $STATION is_default $IS_DEFAULT_STATION_FLAG

    return $ADE_ERR_OK
}

write_multi_key_hash_entry()
{
    local ERRSTACK_REF="$1"; shift
    local KEY

    #  The last parameter is the value, all the rest are keys.
    KEY=
    while [ $# -ge 2 ]; do
        KEY="$KEY${KEY:+,}$1"
        shift
    done
  
    #  Insert the value ($1) into the one and only hash.
    STATION_HASH[$KEY]="$1"

    return $ADE_ERR_OK
}

read_multi_key_hash_entry()
{
    local ERRSTACK_REF="$1"; shift
    local KEY

    #  The last parameter is the variable into which the value should
    #  be written, all the rest are keys.
    KEY=
    while [ $# -ge 2 ]; do
        KEY="$KEY${KEY:+,}$1"
        shift
    done

    #  Retrieve the value from the hash and put it in the passed variable ($1)
    VAL=${STATION_HASH[$KEY]}
    eval "$1=\"\$VAL\""

    return $ADE_ERR_OK
}

get_default_station()
{
    local ERRSTACK_REF DEFAULT_STATION_REF IS_DEFAULT_STATION_FLAG STATION

    ERRSTACK_REF="$1"
    DEFAULT_STATION_REF="$2"

    for STATION in $(echo ${!STATION_HASH[*]} | xargs -n 1 echo | sed 's/,.*//' | sort -u | xargs echo); do
        read_multi_key_hash_entry "$ERRSTACK_REF" $STATION is_default IS_DEFAULT_STATION_FLAG
        if $IS_DEFAULT_STATION_FLAG; then
            eval "$DEFAULT_STATION_REF=$STATION"
            return $ADE_ERR_OK
        fi
    done

    ade_err_error "$ERRSTACK_REF" WRA_ERR_MISC "$OPT_RC_FILE is empty? (hint: run 'rm $OPT_RC_FILE')"
    return $ADE_ERR_FAIL
}

ade_gep_main wra "$@"