NAME

OpenBSD::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 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.

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.