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

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

#  Configuration

#  Other globals
WRA_DEFINED_ERRORS=(
    "KEY=WRA_ERR_MISC; FMT=\"%s\""
)
MAX_VOLUME=100
WRA_SHARE_PREFIX=$(wra-config wra_share_prefix)
INIT_WRARC=$WRA_SHARE_PREFIX/wrarc
FADEIN_STEP_INTERVAL=5
declare -A CONFIG_HASH

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

    #  Register application-specific errors
    ade_register_error_types WRA_DEFINED_ERRORS

    #  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}.
    ade_get_progname "$ERRSTACK_REF" PROGNAME
    OPT_RC_FILE=${XDG_CONFIG_HOME:-$HOME/.config}/$PROGNAME/${PROGNAME}rc

    #  Register wra's options 
    ade_register_options "$ERRSTACK_REF" -o fl --longoptions=config-file:,list-stations --callback-template="wra_opt_handler_%s" || return $?
    ade_set_callbacks "$ERRSTACK_REF" wra_usage_help wra_version wra_paths || return $?

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

    #  Process arguments
    #  (later)

    #  Sanity checks and derivations
    #ade_set_messaging_parameters "$ERRSTACK_REF" writers="stderr,logfile" logfile=/tmp/wra.$$.log
    HELPER_DIRS=( $HOME/.config/${PROGNAME}/helpers $WRA_SHARE_PREFIX/helpers )
    #  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_error "$ERRSTACK_REF" WRA_ERR_MISC "~/.wrarc is a non-standard symlink (hint: resolve this yourself)"
       return $ADE_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_error "$ERRSTACK_REF" WRA_ERR_MISC "~/.wrarc is a file but new location already exists (hint: resolve this yourself)"
       return $ADE_FAIL
    elif [ -e ~/.wrarc ]; then
       ade_error "$ERRSTACK_REF" WRA_ERR_MISC  "~/.wrarc exists but is not a file or a symlink (hint: resolve this yourself)"
       return $ADE_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_warning "$ERRSTACK_REF" WRA_ERR_MISC "custom wrarc"
    fi
    #  Set a default volume control command.
    write_multi_key_hash_entry "$ERRSTACK_REF" control $FACILITY command 'echo pactl set-sink-volume $(pacmd list-sinks | sed -n "s/^  \\* index: //p") %{PERCENT}%'

    #  Load configuration.
    ade_debug "$ERRSTACK_REF" 10 "wra: checking $OPT_RC_FILE is loadable ..."
    sh -c "station() { :; }; control() { :; }; helper() { :; }; . $OPT_RC_FILE > /dev/null 2>&1" || { 
        ade_error "$ERRSTACK_REF" WRA_ERR_MISC "$OPT_RC_FILE: not loadable (hint: run 'sh -c \"station() { :; }; control() { :; }; helper() { :; }; . $OPT_RC_FILE\"' to see why)"
        return $ADE_FAIL
    }
    ade_debug "$ERRSTACK_REF" 10 "wra: loading $OPT_RC_FILE ..."
    #  See comments below in station() function regarding CONFIG_FILE_AGGR_RC.
    CONFIG_FILE_AGGR_RC=$ADE_OK
    . $OPT_RC_FILE
    if [ $CONFIG_FILE_AGGR_RC != $ADE_OK ]; then
        return $CONFIG_FILE_AGGR_RC
    fi

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

    return $ADE_OK
}

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

    get_stations "$ERRSTACK_REF" STATIONS

    #  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 $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

    #  Get the number of rows and columns we'll have (though some cells may be empty
    #  because the number of stations isn't a precise multiple of the number of 
    #  columns).
    COLS=$RECORDS_PER_LINE_COUNT
    ROWS=$(( (${#STATIONS[*]}+$COLS-1) / $COLS ))
    #  We go row by row ...
    for ((ROW=0; ROW<$ROWS; ROW++)); do
        #  ... and column by column.
        for ((COL=0; COL<$COLS; COL++)); do
            #  When all columns are not entirely full, then we would shortly to 
            #  access a non-existent cell. Prevent this.
            if (($ROWS*COL+ROW >= ${#STATIONS[*]})); then
                continue
            fi
    
            #  Construct the record (without padding).
            STATION=${STATIONS[$(($ROWS*COL+ROW))]}
            read_multi_key_hash_entry "$ERRSTACK_REF" station $STATION is_default IS_DEFAULT_STATION_FLAG
            read_multi_key_hash_entry "$ERRSTACK_REF" station $STATION description DESCRIPTION
            #  The printfs below work fine except for diacriticals, which get wrongly
            #  padded (bash's printf thinks 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 the 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 "$BOLD_ON_OR_EMPTY%-$((LONGEST_STATION_LENGTH+1))s %-$((LONGEST_DESCRIPTION_LENGTH-ADJUSTMENT))s$BOLD_OFF_OR_EMPTY" "$STATION$ASTERISK_OR_NOTHING:" "$DESCRIPTION"
    
            #  If this is the last column then output without padding and with newline.
            if ((COL+1==COLS)); then
                echo "$RECORD"
            #  If the cell to the right (COL+1) would next loop we would try to access an 
            #  empty cell (were it not for the code above to prevent that) but that means 
            #  that *this* cell is the last one and should be without padding and with newline.
            elif (($ROWS*(COL+1)+ROW >= ${#STATIONS[*]})); then
                echo "$RECORD"
            #  Otherwise add 4 spaces padding and no newline.
            else
                echo -n "$RECORD    "
            fi
        done
    done

    return $ADE_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_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_show_bad_usage "$ERRSTACK_REF"
            elif [ $EXPECT = off -a $ARG = off ]; then
                EXPECT=offtime
            elif [ $EXPECT = off ]; then
                ade_show_bad_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_show_bad_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_show_bad_usage "$ERRSTACK_REF"
            fi
        done
        #  Check last argument left state engine in an acceptable state
        [ $EXPECT = onorstation -o $EXPECT = offorstation ] || ade_show_bad_usage "$ERRSTACK_REF"
    done
      
    return $ADE_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_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_OK
}

wra_usage_help() 
{
    local ERRSTACK_REF="$1"; shift
    local USAGE_TEXT_SHORT_REF="$1"; shift
    local USAGE_TEXT_LONG_REF="$1"; shift

    eval "$USAGE_TEXT_SHORT_REF=\"{ on <time> | off <time> | <station> } ...\""
    eval "$USAGE_TEXT_LONG_REF=\"\
         -f <file> | --config-file=<file>    use alternate config file
         -l        | --list-stations         list defined stations

Times:   HHMM                                HH:MM
         now                                 now\""
    return $ADE_OK
}

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

    eval "$PATHLIST_REF=\"\""

    return $ADE_OK
} 

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

    ade_extract_version "$ERRSTACK_REF" "$APP_SVNID" "$VERSION_REF"

    return $ADE_OK
} 

get_stations()
{
    local ERRSTACK_REF="$1"; shift
    local STATIONS_REF=$1
    local KEY KEYS

    get_multi_key_hash_keys "$ERRSTACK_REF" KEYS
    eval "$STATIONS_REF=()"
    for KEY in "${KEYS[@]}"; do
        #  There are multiple 'station,<station-id>,*' keys in the hash: for
        #  each station's description *and* station-is-default-default value,
        #  etc. To get just <station-id> we filter for just *one* of the
        #  later key fields (e.g. 'description') and the extract out of
        #  that <station-id>.
        [[ $KEY =~ ^station,([^,]+),description ]] || continue
        eval "$STATIONS_REF+=( \${BASH_REMATCH[1]} )"
    done

    return $ADE_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_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_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_OK
}

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

    USERSEL_STATION="$STATION"

    return $ADE_OK
}

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

    ade_debug "$ERRSTACK_REF" 10 "start_station: starting (STATION=$STATION) ..."

    #  Sanity checks and derivations
    read_multi_key_hash_entry "$ERRSTACK_REF" station $STATION helper HELPER
    ade_debug "$ERRSTACK_REF" 10 "start_station: pre-canonicalised HELPER=$HELPER"
    canonicalise_helper "$ERRSTACK_REF" "$HELPER" HELPER || return $?
    ade_debug "$ERRSTACK_REF" 10 "start_station: post-canonicalised HELPER=$HELPER"
    read_multi_key_hash_entry "$ERRSTACK_REF" station $STATION url URL
    #  We will pass on our verbosity to the helper.
    ade_get_verboselevel "$ERRSTACK_REF" VERBOSELEVEL || return $?

    #  Guts
    if ! eval "$HELPER --debug=$VERBOSELEVEL --server"; then
        ade_error "$ERRSTACK_REF" WRA_ERR_MISC "failed so start $HELPER server (hint: see messages above)"
        return $ADE_FAIL
    fi
    if ! eval "$HELPER --debug=$VERBOSELEVEL --submit \"\$URL\""; then
        ade_error "$ERRSTACK_REF" WRA_ERR_MISC "failed to submit URL to $HELPER server (hint: see messages above)"
        return $ADE_FAIL
    fi

    return $ADE_OK
}

canonicalise_helper()
{
    local HELPER_REF LOCAL_HELPER FOUND HELPER_DIR ERRSTACK_REF

    [ $# = 3 ] || ade_internal "$ERRSTACK_REF" "canonicalise_helper: $#: invalid argument count"
    ERRSTACK_REF=$1
    HELPER=$2
    CANONICALISED_HELPER_REF=$3

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

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

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

    #  Sanity checks and derivations
    ade_debug "$ERRSTACK_REF" 10 "start_station: starting (STATION=$STATION) ..."
    #  We will pass on our verbosity to the helper.
    ade_get_verboselevel "$ERRSTACK_REF" VERBOSELEVEL || return $?

    #  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_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" HELPER || return $?
            ade_debug "$ERRSTACK_REF" 10 "stop_station: calling [$HELPER --debug=$VERBOSELEVEL --stop] ..."
            if ! eval "$HELPER --debug=$VERBOSELEVEL --stop"; then
                ade_error "$ERRSTACK_REF" WRA_ERR_MISC "failed so stop $HELPER server (hint: see messages above)"
                return $ADE_FAIL
            fi
        done
    else
        ade_debug "$ERRSTACK_REF" 10 "stop_station: request is to stop only $HELPER helper"
        read_multi_key_hash_entry "$ERRSTACK_REF" station $STATION helper HELPER
        canonicalise_helper "$ERRSTACK_REF" "$HELPER" HELPER || return $?
        if ! eval "$HELPER --debug=$VERBOSELEVEL --stop"; then
            ade_error "$ERRSTACK_REF" WRA_ERR_MISC "failed so stop $HELPER server (hint: see messages above)"
            return $ADE_FAIL
        fi
    fi

    return $ADE_OK
}

validate_station()
{
    local ERRSTACK_REF STATION 
    local DESCRIPTION URL HELPER

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

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

    return $ADE_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_debug "$ERRSTACK_REF" 10 "validate_time: $TIME: invalid time"
        ade_show_bad_usage "$ERRSTACK_REF"
    fi
        
    return $ADE_OK
}
                    
set_volume()
{
    local ERRSTACK_REF="$1"; shift
    local VOL="$1"; shift
    local SETVOLUME_CMD

    #  Sanity checks and derivations
    #  Strip fractional volume.
    VOL=${VOL%.*}
    read_multi_key_hash_entry "$ERRSTACK_REF" control volume command SETVOLUME_CMD
    #  Replace %{PERCENT} with the volume percentage.
    SETVOLUME_CMD=${SETVOLUME_CMD//%\{PERCENT\}/$VOL}
    #  Run the command.
    if ! eval "$SETVOLUME_CMD"; then
        ade_error "$ERRSTACK_REF" WRA_ERR_MISC "failed to set volume (hint: see messages above)"
        return $ADE_FAIL
    fi

    return $ADE_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_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_debug "$ERRSTACK_REF" 10 "sleeptill: PERIOD=$PERIOD"
    sleep $PERIOD
    ade_info "$ERRSTACK_REF" "wake time has arrived"

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

    #  Note that ERRSTACK_REF *must* be inherited through two function
    #  calls because station() is a directive in the config file and
    #  we don't want the user to have to specify an error stack there.
    #  Also the return code needs to be cached to a variable, rather
    #  than being returned, and only after this script has loaded the
    #  config file can that variable be inspected and returned.
    [ $# = 4 ] || ade_internal "$ERRSTACK_REF" "station: $#: invalid argument count"
    STATION="$1"
    DESCRIPTION="$2"
    URL="$3"
    HELPER="$4"

    #  To avoid multiple station() calls each putting frames on the
    #  stack and that then being seen as a single error frame set,
    #  if an earlier call has already noted an error in CONFIG_FILE_AGGR_RC
    #  then we immediately return. The caller will then report the
    #  *one* error frame set on the error stack.
    if [ $CONFIG_FILE_AGGR_RC = $ADE_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.
    get_stations "$ERRSTACK_REF" STATIONS
    if [ ${#STATIONS[*]} = 0 ]; then
        IS_DEFAULT_STATION_FLAG=true
    else
        IS_DEFAULT_STATION_FLAG=false
    fi

    #  Validate the URL.
    if [ "X$URL" = X ]; then
        ade_error "$ERRSTACK_REF" WRA_ERR_MISC "$STATION: station has invalid URL (hint: check ~/.wrarc)"
	CONFIG_FILE_AGGR_RC=$ADE_FAIL
        return
      
    fi
    #  Check that the helper can be found my attempting to canonicalise it,
    #  but don't bother keep the canonicalised path.
    canonicalise_helper "$ERRSTACK_REF" "$HELPER" HELPER2
    if [ $? = $ADE_FAIL ]; then
	CONFIG_FILE_AGGR_RC=$ADE_FAIL
        return
    fi

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

    return $ADE_OK
}

control()
{
    local FACILITY COMMAND

    #  Note that ERRSTACK_REF *must* be inherited through two function
    #  calls because station() is a directive in the config file and
    #  we don't want the user to have to specify an error stack there.
    [ $# = 2 ] || ade_internal "$ERRSTACK_REF" "control: $#: invalid argument count"
    FACILITY="$1"
    COMMAND="$2"
    ade_debug "$ERRSTACK_REF" 10 "control: FACILITY=$FACILITY, COMMAND=$COMMAND"

    #  Validate the facility.
    if ! [[ $FACILITY =~ ^(volume)$ ]]; then
        ade_error "$ERRSTACK_REF" WRA_ERR_MISC "$FACILITY: invalid facility specified in control directive (hint: the only facility currently supported is 'volume')"
	CONFIG_FILE_AGGR_RC=$ADE_FAIL
        return
    fi

    #  Validate the command.
    ade_validate_command "$ERRSTACK_REF" ${COMMAND%% *}|| return $?

    #  Save it to hash.
    write_multi_key_hash_entry "$ERRSTACK_REF" control $FACILITY command "$COMMAND"

    return $ADE_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.
    CONFIG_HASH[$KEY]="$1"

    return $ADE_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=${CONFIG_HASH[$KEY]}
    eval "$1=\"\$VAL\""

    return $ADE_OK
}

get_multi_key_hash_keys()
{
    local ERRSTACK_REF="$1"; shift
    local KEYS_REF=$1

    #  Remember that printf prints its *arguments*, not stdin, but loops over them
    #  if it uses up its %-formats. I.e. it's the same as 'xargs -n 1 echo'.
    eval "$KEYS_REF=( $(printf "%s\n" ${!CONFIG_HASH[*]} | sort | paste -s -d' ') )"
    return $ADE_OK
}

get_default_station()
{
    local ERRSTACK_REF DEFAULT_STATION_REF IS_DEFAULT_STATION_FLAG STATION STATIONS

    ERRSTACK_REF="$1"
    DEFAULT_STATION_REF="$2"
    
    get_stations "$ERRSTACK_REF" STATIONS
    for STATION in "${STATIONS[@]}"; do
        read_multi_key_hash_entry "$ERRSTACK_REF" station $STATION is_default IS_DEFAULT_STATION_FLAG
        if $IS_DEFAULT_STATION_FLAG; then
            eval "$DEFAULT_STATION_REF=$STATION"
            return $ADE_OK
        fi
    done

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

ade_main wra "$@"