OpenBSD::State(3p)

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.

$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.

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.