OpenBSD::State(3p) Perl Programmers Reference Guide OpenBSD::State(3p) #
OpenBSD::State(3p) Perl Programmers Reference Guide OpenBSD::State(3p)
NNAAMMEE #
OpenBSD::State - user interface framework
SSYYNNOOPPSSIISS #
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);
DDEESSCCRRIIPPTTIIOONN #
"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 overridden safely.
See also "OpenBSD::BaseState" which contains most of the stateless
utility code like "say" and friends.
$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 overridden. 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.
$state->handle_continue;
callback for "SIGCONT", to be overridden by subclasses if some
specific treatment (such as terminal redraw/reset) is needed.
$state->sync_display
hook to be overridden. Called by all the print functions prior to
displaying anything. To be used to write things out cleanly (e.g.,
wipe out a progressmeter line prior to writing an error message, for
instance)
$state->system([child setup], [parent setup], @args)
calls "exec" without an extra shell, with optional code to be run on
the child, and optional code to be run on the father, then wait for
the child and write possible errors
$state->verbose_system([child setup], [parent setup], @args)
like system, except it always shows what it's running
$state->copy_file(@names)
verbose interface to "File::Copy" with error reporting.
$state->unlink(@names)
verbose interface to "unlink" with error reporting.
BBUUGGSS #
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.36.3 2022-12-30 OpenBSD::State(3p)