view release on metacpan or  search on metacpan

lib/CLI/Startup.pm  view on Meta::CPAN

Prints the formatted POD contained in the calling script.
If there's no POD content in the file, then the C<--help>
usage is printed instead.

=head2 print_version

  $app->print_version;

Prints the version of the calling script, if the variable C<$VERSION> is
defined in the top-level scope.

=head2 write_rcfile

  $app->write_rcfile();      # Overwrite the rc file for this script
  $app->write_rcfile($path); # Write an rc file to a new location

Write the current settings for this script to an rcfile--by default,
the rcfile read for this script, but optionally a different file
specified by the caller. The automatic C<--write-rcfile> option
always writes to the script specified in the C<--rcfile> option.

The file format can be specified by the C<--rcfile-format> option,
and must be one of: ini, yaml, json, xml, and perl. By default this
method will attempt to use .ini file format, because it's the
simplest and most readable for most option specification needs. If
the module C<Config::INI::Writer> isn't installed, it will fall back
on perl format, which looks like the output of C<Data::Dumper>.

The prettiest formats are ini, yaml, and perl. The others will tend
to be harder to read.

The simplest format for users is ini. It's good enough, if you
don't have complicated command-line options, or additional data
hidden in your config files.

The most powerful formats are json and yaml, of which yaml is the
most readable. It will let you put pretty much any data structure
you desire in your config files.

It's a fatal error to call C<write_rcfile()> before calling C<init()>.

=head2 get_options_as_defaults

    $options = $app->get_options_as_defaults;

Returns the same hashref as C<$app->get_config> would do, except
that C<$options->{default}> is overridden with the current settings
of the app. This is a helper method if you write a function to write
config files in some format not natively supported by C<CLI::Startup>.
It lets you freeze the state of the current command line as the
default for future runs.

This sub will also strip out any of the auto-generated options, like
C<--help> and C<--rcfile>, since they don't belong in a config file.

=head1 AUTHOR

Len Budney, C<< <len.budney at gmail.com> >>

=head1 BUGS AND LIMITATIONS

C<CLI::Startup> tries reasonably to keep things consistent, but it
doesn't stop you from shooting yourself in the foot if you try at
all hard. For example: it will let you specify defaults for
nonexistent options; it will let you use a hashref as the default
value for a boolean option; etc..

For now, you should also not define aliases for default options.
If you try to define an option like 'help|?', expecting to get
C<--help> and C<--?> as synonyms, something will break. Basically,
C<CLI::Startup> isn't quite smart enough to recognize that your
help option is a suitable replacement for the builtin one.

You I<can> delete default options by supplying the primary name
of the option with a help-text value that evaluates to false.
C<CLI::Startup> will delete that option from the defaults before
merging with your options. If you try that with C<--help>, though,
C<CLI::Startup> will put that option back in. Its main use is to
disable .rc file handing.

Please report any bugs or feature requests to C<bug-cli-startup at
rt.cpan.org>, or through the web interface at
L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CLI-Startup>.  I
will be notified, and then you'll automatically be notified of
progress on your bug as I make changes.


=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc CLI::Startup

You can also look for information at:

=over 4

=item * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=CLI-Startup>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/CLI-Startup>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/CLI-Startup>

=item * Search CPAN

L<http://search.cpan.org/dist/CLI-Startup/>

=back


=head1 ACKNOWLEDGEMENTS


=head1 LICENSE AND COPYRIGHT