$OpenBSD: OpenBSD::State.pod,v 1.2 2010/06/30 10:51:04 espie Exp $

=head1 NAME

OpenBSD::State - user interface framework

=head1 SYNOPSIS

    package MyCmd::State;
    use OpenBSD::State;
    our @ISA = qw(OpenBSD::State);

    ...
    package myCmd;

    my $state = MyCmd::State->new("cmd");
    $state->handle_options('abc', '[-abc]');

    ...
    $state->say("I'm sorry #1, I'm afraid I can't do that", $user);

=head1 DESCRIPTION

C<OpenBSD::State> is the base class responsible for handling all user
interface needs of C<pkg_*(1)> commands.

As such, it contains internal state elements relevant to the working of
various commands.  It should be used for option handling, usage printing,
asking questions, or printing out values.

C<OpenBSD::State> is designed for inheritance.

It provides default behavior for options -v and -D value.

Subclass C<OpenBSD::State::AddCreateDelete> adds progressmeter behavior, along
with options -m, -n and -x.

Some methods can be used and overriden safely.

=over 4

=item $class->new($cmdname, @params)

create a new state object of the desired class.
C<$cmdname> is mandatory to options usage printing.
C<@params> are passed unchanged to C<init>.
Don't override, override C<init> instead.

=item $state->init(@params);

initialize C<$state> based on C<@params>.
Meant to be overridden. Always call C<$state-E<gt>SUPER::init(@params)> at end.

=item $state->handle_options($opt_string, @usage);

handle options to relevant to this command. Takes a C<OpenBSD::Getopt>
C<$opt_string>, and a set of C<@usage> lines that will be printed if
necessary.

Option results are stored in the C<$state-E<gt>{opt}> hash. This can
be primed according to C<OpenBSD::Getopt> documentation for options that
require code.

Unless C<$state-E<gt>{no_exports}> is set, options will also be exported to
calling package, for legacy commands that still use C<our ($opt_x)> constructs.

In case of an error, usage will call C<die>.

Meant to be overriden.  A subclass C<handle_options> will normally do
all option parsing and stuff the results in the C<$state> object.

=item $state->usage($extra, @args)

print out usage line, as set in C<handle_options>, along with possible
extra hints, following C<errprint> conventions.

=item $state->print($msg, @args);

display a formatted message for the user.
Any C<#n> substring will be replaced by the nth argument from C<@args>.
Numbering starts at 1, C<#0> can be used to display an actual C<#>.

All messages displayed by C<OpenBSD::State> using commands should use
this framework, so that messages can be translated (eventually).

Do not print directly to C<STDOUT> as this might garble the display
(especially with a progressmeter).

=item $state->errprint($msg, @args);

like C<print>, but on C<STDERR>.

=item $state->say($msg, @args);

like C<print>, with a line feed.

=item $state->errsay($msg, @args);

like C<errprint>, with a line feed.

=item $state->fatal($msg, @args);

use the same conventions as C<errsay>, but call C<die> with the resulting
string.

=item $state->f($msg, @args);

basic formatting function used by C<print> and friends, return the formatted
string.

=back

=head1 BUGS

User interface needs are not fully fleshed out and C<OpenBSD::State> is
a work-in-progress.  What's described here should hopefully no longer
change too much.