OpenBSD::State(3p) Perl Programmers Reference Guide OpenBSD::State(3p)NAMEOpenBSD::State - user interface framework
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);
DESCRIPTION
"OpenBSD::State" is the base class responsible for handling all user
interface needs of "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.
"OpenBSD::State" is designed for inheritance.
It provides default behavior for options -v and -D value.
Subclass "OpenBSD::State::AddCreateDelete" adds progressmeter behavior,
along with options -m, -n and -x.
Some methods can be used and overriden safely.
$class->new($cmdname, @params)
create a new state object of the desired class. $cmdname is
mandatory to options usage printing. @params are passed unchanged
to "init". Don't override, override "init" instead.
$state->init(@params);
initialize $state based on @params. Meant to be overridden. Always
call "$state->SUPER::init(@params)" at end.
$state->handle_options($opt_string, @usage);
handle options to relevant to this command. Takes a
"OpenBSD::Getopt" $opt_string, and a set of @usage lines that will
be printed if necessary.
Option results are stored in the "$state->{opt}" hash. This can be
primed according to "OpenBSD::Getopt" documentation for options
that require code.
Unless "$state->{no_exports}" is set, options will also be exported
to calling package, for legacy commands that still use "our
($opt_x)" constructs.
In case of an error, usage will call "die".
Meant to be overriden. A subclass "handle_options" will normally
do all option parsing and stuff the results in the $state object.
$state->usage($extra, @args)
print out usage line, as set in "handle_options", along with
possible extra hints, following "errprint" conventions.
$state->print($msg, @args);
display a formatted message for the user. Any "#n" substring will
be replaced by the nth argument from @args. Numbering starts at 1,
"#0" can be used to display an actual "#".
All messages displayed by "OpenBSD::State" using commands should
use this framework, so that messages can be translated
(eventually).
Do not print directly to "STDOUT" as this might garble the display
(especially with a progressmeter).
$state->errprint($msg, @args);
like "print", but on "STDERR".
$state->say($msg, @args);
like "print", with a line feed.
$state->errsay($msg, @args);
like "errprint", with a line feed.
$state->fatal($msg, @args);
use the same conventions as "errsay", but call "die" with the
resulting string.
$state->f($msg, @args);
basic formatting function used by "print" and friends, return the
formatted string.
BUGS
User interface needs are not fully fleshed out and "OpenBSD::State" is
a work-in-progress. What's described here should hopefully no longer
change too much.
perl v5.12.2 June 30, 2010
