$OpenBSD: State.pod,v 1.3 2022/02/12 09:46:19 espie Exp $ =head1 NAME OpenBSD::State - user interface framework =head1 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); =head1 DESCRIPTION C is the base class responsible for handling all user interface needs of C 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. C is designed for inheritance. It provides default behavior for options -v and -D value. Subclass C adds progressmeter behavior, along with options -m, -n and -x. Some methods can be used and overridden safely. See also C which contains most of the stateless utility code like C and friends. =over 4 =item $class->new($cmdname, @params) create a new state object of the desired class. C<$cmdname> is mandatory to options usage printing. C<@params> are passed unchanged to C. Don't override, override C instead. =item $state->init(@params); initialize C<$state> based on C<@params>. Meant to be overridden. Always call C<$state-ESUPER::init(@params)> at end. =item $state->handle_options($opt_string, @usage); handle options to relevant to this command. Takes a C C<$opt_string>, and a set of C<@usage> lines that will be printed if necessary. Option results are stored in the C<$state-E{opt}> hash. This can be primed according to C documentation for options that require code. Unless C<$state-E{no_exports}> is set, options will also be exported to calling package, for legacy commands that still use C constructs. In case of an error, usage will call C. Meant to be overridden. A subclass C will normally do all option parsing and stuff the results in the C<$state> object. =item $state->usage($extra, @args) print out usage line, as set in C, along with possible extra hints, following C conventions. =item $state->print($msg, @args); display a formatted message for the user. Any C<#n> substring will be replaced by the nth argument from C<@args>. Numbering starts at 1, C<#0> can be used to display an actual C<#>. All messages displayed by C using commands should use this framework, so that messages can be translated (eventually). Do not print directly to C as this might garble the display (especially with a progressmeter). =item $state->errprint($msg, @args); like C, but on C. =item $state->say($msg, @args); like C, with a line feed. =item $state->errsay($msg, @args); like C, with a line feed. =item $state->fatal($msg, @args); use the same conventions as C, but call C with the resulting string. =item $state->f($msg, @args); basic formatting function used by C and friends, return the formatted string. =item $state->handle_continue; callback for C, to be overridden by subclasses if some specific treatment (such as terminal redraw/reset) is needed. =item $state->sync_display hook to be overriden. 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) =item $state->system([child setup], [parent setup], @args) calls C 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 =item $state->verbose_system([child setup], [parent setup], @args) like system, except it always shows what it's running =item $state->copy_file(@names) verbose interface to C with error reporting. =item $state->unlink(@names) verbose interface to C with error reporting. =back =head1 BUGS User interface needs are not fully fleshed out and C is a work-in-progress. What's described here should hopefully no longer change too much.