.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "AppConfig::Std 3pm"
.TH AppConfig::Std 3pm "2015-10-26" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
AppConfig::Std \- subclass of AppConfig that provides standard options
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use AppConfig::Std;
\&
\&    $config = AppConfig::Std\->new();
\&
\&    # all AppConfig methods supported
\&    $config\->define(\*(Aqfoo\*(Aq);            # define variable foo
\&    $config\->set(\*(Aqfoo\*(Aq, 25);           # setting a variable
\&    $val = $config\->get(\*(Aqfoo\*(Aq);        # getting variable
\&    $val = $config\->foo();             # shorthand for getting
\&
\&    $config\->args(\e@ARGV);             # parse command\-line
\&    $config\->file(".myconfigrc")       # read config file
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBAppConfig::Std\fR is a Perl module that provides a set of
standard configuration variables and command-line switches.
It is implemented as a subclass of AppConfig; AppConfig provides
a general mechanism for handling global configuration variables.
.PP
The features provided by AppConfig::Std are:
.IP "\(bu" 4
Standard command-line arguments: \-help, \-doc, \-version,
\&\-verbose, and \-debug. AppConfig::Std handles the \-help, \-doc,
and \-version switches for you, so you don't need to duplicate
that code in all of your scripts.
These are described below.
.IP "\(bu" 4
The \s-1ARGCOUNT\s0 default is set to 1. This means that by default
all switches are expected to take a value. To change this,
set the \s-1ARGCOUNT\s0 parameter when defining the variable:
.Sp
.Vb 1
\&    $config\->define(\*(Aqverbose\*(Aq, { ARGCOUNT => 0 } );
.Ve
.PP
Please read the copious documentation for AppConfig to
find out what else you can do with this module.
.SH "STANDARD OPTIONS"
.IX Header "STANDARD OPTIONS"
The module adds five standard configuration variables
and command-line switches. You can define additional
variables as you would with AppConfig.
.SS "\s-1HELP\s0"
.IX Subsection "HELP"
The \fB\-help\fR switch will result in a short help message.
This is generated using Pod::Usage, which displays the \fB\s-1OPTIONS\s0\fR
section of your pod. The script will exit with an exit value of 0.
.SS "\s-1DOC\s0"
.IX Subsection "DOC"
The \fB\-doc\fR switch will result in the entire documentation
being formatted to the screen.
This is also done with Pod::Usage.
The script will exit with an exit value of 0.
.SS "\s-1VERSION\s0"
.IX Subsection "VERSION"
The \fB\-version\fR switch will display the version of the invoking script.
This assumes that you have defined \f(CW$VERSION\fR in your script
with something like the following:
.PP
.Vb 2
\&    use vars qw( $VERSION );
\&    $VERSION = sprintf("%d.%02d", q$Revision: 1.7 $ =~ /(\ed+)\e.(\ed+)/);
.Ve
.PP
The script will exit with an exit value of 0.
.SS "\s-1DEBUG\s0"
.IX Subsection "DEBUG"
The \fB\-debug\fR switch just sets the \fBdebug\fR variable.
This is useful for displaying information in debug mode:
.PP
.Vb 1
\&    $foobar\->dump() if $config\->debug;
.Ve
.SS "\s-1VERBOSE\s0"
.IX Subsection "VERBOSE"
The \fB\-verbose\fR switch just sets the \fBverbose\fR variable.
This is useful for displaying verbose information as
a script runs:
.PP
.Vb 1
\&    print STDERR "Running foobar\en" if $config\->verbose;
.Ve
.SH "TODO"
.IX Header "TODO"
Please let me know if you have ideas for additional switches,
or other modifications. Things currently being mulled:
.IP "\(bu" 4
Support brief switches, such as \fB\-h\fR as well as \fB\-help\fR.
This could be a config option for the constructor.
.IP "\(bu" 4
Include a sample script called \fBmkscript\fR, which would create
a template script along with Makefile.PL, \s-1MANIFEST,\s0 etc.
Kinda of a h2xs for scripts.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
The following is the outline of a simple script that illustrates
use of the AppConfig::Std module:
.PP
.Vb 3
\&    #!/usr/bin/perl \-w
\&    use strict;
\&    use AppConfig::Std;
\&
\&    use vars qw( $VERSION );
\&    $VERSION = \*(Aq1.0\*(Aq;
\&
\&    my $config = AppConfig::Std\->new();
\&
\&    # parse command\-line and handle std switches
\&    $config\->args(\e@ARGV);
\&
\&    exit 0;
\&
\&    _\|_END_\|_
\&
\&    =head1 NAME
\&
\&    standard pod format documentation
.Ve
.PP
The pod documentation is expected to have the \s-1NAME, SYNOPSIS,
DESCRIPTION,\s0 and \s-1OPTIONS\s0 sections. See the documentation
for \f(CW\*(C`pod2man\*(C'\fR for more details.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
AppConfig \-
Andy Wardley's module for unifying command-line switches and
cofiguration files into the notion of configuration variables.
AppConfig::Std requires version 1.52+ of the module,
which is available from \s-1CPAN.\s0
.PP
Pod::Usage \-
Brad Appleton's module for extracting usage information out
of a file's pod. This is used for the \fB\-doc\fR and \fB\-help\fR switches.
Available from \s-1CPAN\s0 as part of the PodParser distribution.
.PP
perlpod <https://metacpan.org/pod/distribution/perl/pod/perlpod.pod> \-
documentation from the perl distribution that describes
the pod format.
.PP
pod2man <https://metacpan.org/pod/distribution/podlators/scripts/pod2man> \-
particularly the \s-1NOTES\s0 section in the documentation
which describes the sections you should include in your documentation.
AppConfig::Std uses Pod::Usage, which assumes well-formed pod.
.SH "REPOSITORY"
.IX Header "REPOSITORY"
<https://github.com/neilb/AppConfig\-Std>
.SH "AUTHOR"
.IX Header "AUTHOR"
Neil Bowers <neil@bowers.com>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2002\-2013 Neil Bowers.
.PP
Copyright (c) 1998\-2001 Canon Research Centre Europe. All rights reserved.
.PP
This script is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.