1$OpenBSD: State.pod,v 1.4 2022/12/28 21:30:18 jmc Exp $ 2 3=head1 NAME 4 5OpenBSD::State - user interface framework 6 7=head1 SYNOPSIS 8 9 package MyCmd::State; 10 use OpenBSD::State; 11 our @ISA = qw(OpenBSD::State); 12 13 ... 14 package myCmd; 15 16 my $state = MyCmd::State->new("cmd"); 17 $state->handle_options('abc', '[-abc]'); 18 19 ... 20 $state->say("I'm sorry #1, I'm afraid I can't do that", $user); 21 22=head1 DESCRIPTION 23 24C<OpenBSD::State> is the base class responsible for handling all user 25interface needs of C<pkg_*(1)> commands. 26 27As such, it contains internal state elements relevant to the working of 28various commands. It should be used for option handling, usage printing, 29asking questions, or printing out values. 30 31C<OpenBSD::State> is designed for inheritance. 32 33It provides default behavior for options -v and -D value. 34 35Subclass C<OpenBSD::State::AddCreateDelete> adds progressmeter behavior, along 36with options -m, -n and -x. 37 38Some methods can be used and overridden safely. 39 40See also C<OpenBSD::BaseState> which contains most of the stateless utility 41code like C<say> and friends. 42 43=over 4 44 45=item $class->new($cmdname, @params) 46 47create a new state object of the desired class. 48C<$cmdname> is mandatory to options usage printing. 49C<@params> are passed unchanged to C<init>. 50Don't override, override C<init> instead. 51 52=item $state->init(@params); 53 54initialize C<$state> based on C<@params>. 55Meant to be overridden. Always call C<$state-E<gt>SUPER::init(@params)> at end. 56 57=item $state->handle_options($opt_string, @usage); 58 59handle options to relevant to this command. Takes a C<OpenBSD::Getopt> 60C<$opt_string>, and a set of C<@usage> lines that will be printed if 61necessary. 62 63Option results are stored in the C<$state-E<gt>{opt}> hash. This can 64be primed according to C<OpenBSD::Getopt> documentation for options that 65require code. 66 67Unless C<$state-E<gt>{no_exports}> is set, options will also be exported to 68calling package, for legacy commands that still use C<our ($opt_x)> constructs. 69 70In case of an error, usage will call C<die>. 71 72Meant to be overridden. A subclass C<handle_options> will normally do 73all option parsing and stuff the results in the C<$state> object. 74 75=item $state->usage($extra, @args) 76 77print out usage line, as set in C<handle_options>, along with possible 78extra hints, following C<errprint> conventions. 79 80=item $state->print($msg, @args); 81 82display a formatted message for the user. 83Any C<#n> substring will be replaced by the nth argument from C<@args>. 84Numbering starts at 1, C<#0> can be used to display an actual C<#>. 85 86All messages displayed by C<OpenBSD::State> using commands should use 87this framework, so that messages can be translated (eventually). 88 89Do not print directly to C<STDOUT> as this might garble the display 90(especially with a progressmeter). 91 92=item $state->errprint($msg, @args); 93 94like C<print>, but on C<STDERR>. 95 96=item $state->say($msg, @args); 97 98like C<print>, with a line feed. 99 100=item $state->errsay($msg, @args); 101 102like C<errprint>, with a line feed. 103 104=item $state->fatal($msg, @args); 105 106use the same conventions as C<errsay>, but call C<die> with the resulting 107string. 108 109=item $state->f($msg, @args); 110 111basic formatting function used by C<print> and friends, return the formatted 112string. 113 114=item $state->handle_continue; 115 116callback for C<SIGCONT>, to be overridden by subclasses if some specific 117treatment (such as terminal redraw/reset) is needed. 118 119=item $state->sync_display 120 121hook to be overridden. Called by all the print functions prior to displaying 122anything. To be used to write things out cleanly (e.g., wipe out a 123progressmeter line prior to writing an error message, for instance) 124 125=item $state->system([child setup], [parent setup], @args) 126 127calls C<exec> without an extra shell, with optional code to be run on the 128child, and optional code to be run on the father, then wait for the child 129and write possible errors 130 131=item $state->verbose_system([child setup], [parent setup], @args) 132 133like system, except it always shows what it's running 134 135=item $state->copy_file(@names) 136 137verbose interface to C<File::Copy> with error reporting. 138 139=item $state->unlink(@names) 140 141verbose interface to C<unlink> with error reporting. 142 143=back 144 145=head1 BUGS 146 147User interface needs are not fully fleshed out and C<OpenBSD::State> is 148a work-in-progress. What's described here should hopefully no longer 149change too much. 150