shtk_config_override.3

.\" Copyright 2014 Google Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are
.\" met:
.\"
.\" * Redistributions of source code must retain the above copyright
.\"   notice, this list of conditions and the following disclaimer.
.\" * Redistributions in binary form must reproduce the above copyright
.\"   notice, this list of conditions and the following disclaimer in the
.\"   documentation and/or other materials provided with the distribution.
.\" * Neither the name of Google Inc. nor the names of its contributors
.\"   may be used to endorse or promote products derived from this software
.\"   without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
.\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.Dd November 6, 2014
.Dt SHTK_CONFIG_OVERRIDE 3
.Os
.Sh NAME
.Nm shtk_config_override
.Nd Records an override to be applied to the configuration
.Sh LIBRARY
shtk_import config
.Sh SYNOPSIS
.Nm
.Ar override
.Sh DESCRIPTION
The
.Nm
function records the override given in
.Ar override ,
which must have the form
.Sq variable=value .
.Pp
Overrides are values given to configuration variables that can be set
.Em before
the configuration file is loaded with
.Xr shtk_config_load 3 .
This feature is useful to support parsing all command line flags before
attempting to load the configuration file, as the script should first
validate all user input before performing any action.
.Sh EXAMPLES
This code snippet illustrates a program with a configuration file that
supports a
.Va VERBOSE
variable and that, for convenience reasons, can be overriden via the
command line using the
.Fl v
flag:
.Bd -literal -offset indent
shtk_config_init VERBOSE

local OPTIND
while getopts ':v' arg "${@}"; do
    case "${arg}" in
        v)  # Enable verbose mode.
            shtk_config_override VERBOSE=yes
            ;;
        \\?)
            shtk_cli_usage_error "Unknown option -${OPTARG}"
            ;;
    esac
done
shift $((${OPTIND} - 1))

shtk_config_set VERBOSE no  # Set the default value.
shtk_config_load "/etc/my_program.conf"
.Ed
.Sh SEE ALSO
.Xr shtk 3 ,
.Xr shtk_config 3
.Sh HISTORY
.Nm
first appeared in
.Nm shtk
1.0.