OpenBSD::State(3p) Perl Programmers Reference Guide OpenBSD::State(3p)

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)