.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Commandable::Output 3pm" .TH Commandable::Output 3pm "2023-01-08" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" "Commandable::Output" \- abstractions for printing output from commands .SH "DESCRIPTION" .IX Header "DESCRIPTION" This package contains default implementations of methods for providing printed output from commands implemented using Commandable. These methods are provided for the convenience of user code, and are also used by built-in commands provided by the \f(CW\*(C`Commandable\*(C'\fR system itself. .PP Implementations are permitted (encouraged, even) to replace any of these methods in order to customise their behaviour. .ie n .SS "\s-1WITH\s0 ""String::Tagged""" .el .SS "\s-1WITH\s0 \f(CWString::Tagged\fP" .IX Subsection "WITH String::Tagged" If String::Tagged and Convert::Color are available, this module applies formatting to strings by using the String::Tagged::Formatting conventions. The \f(CW\*(C`format_heading\*(C'\fR and \f(CW\*(C`format_note\*(C'\fR methods will return results as instances of \f(CW\*(C`String::Tagged\*(C'\fR, suitable to pass into the main \f(CW\*(C`printf\*(C'\fR method. .SH "METHODS" .IX Header "METHODS" .SS "printf" .IX Subsection "printf" .Vb 1 \& Commandable::Output\->printf( $format, @args ) .Ve .PP The main output method, used to send messages for display to the user. The arguments are formatted into a single string by Perl's \f(CW\*(C`printf\*(C'\fR function. This method does not append a linefeed. To output a complete line of text, remember to include the \f(CW"\en"\fR at the end of the format string. .PP The default implementation writes output on the terminal via \s-1STDOUT.\s0 .PP In cases where the output should be sent to some other place (perhaps a \s-1GUI\s0 display widget of some kind), the application should replace this method with something that writes the display to somewhere more appropriate. Don't forget to use \f(CW\*(C`sprintf\*(C'\fR to format the arguments into a string. .PP .Vb 5 \& no warnings \*(Aqredefine\*(Aq; \& sub Commandable::Output::printf \& { \& shift; # the package name \& my ( $format, @args ) = @_; \& \& my $str = sprintf $format, @args; \& \& $gui_display_widget\->append_text( $str ); \& } .Ve .PP If String::Tagged::Terminal is available, the output will be printed using this module, by first converting the format string and arguments using \&\*(L"from_sprintf\*(R" in String::Tagged and then constructing a terminal string using \&\*(L"new_from_formatting\*(R" in String::Tagged::Terminal. This means the default implementation will be able to output formatted strings using the String::Tagged::Formatting conventions. .SS "print_heading" .IX Subsection "print_heading" .Vb 1 \& Commandable::Output\->print_heading( $text, $level ) .Ve .PP Used to send output that should be considered like a section heading. \&\fI\f(CI$level\fI\fR may be an integer used to express sub-levels; increasing values from 1 upwards indicate increasing sub-levels. .PP The default implementation formats the text string using \*(L"format_heading\*(R" then prints it using \*(L"printf\*(R" with a trailing linefeed. .SS "format_heading" .IX Subsection "format_heading" .Vb 1 \& $str = Commandable::Output\->format_heading( $text, $level ) .Ve .PP Returns a value for printing, to represent a section heading for the given text and level. .PP The default implementation applies the following formatting if \&\f(CW\*(C`String::Tagged\*(C'\fR is available: .IP "Level 1" 4 .IX Item "Level 1" Underlined .IP "Level 2" 4 .IX Item "Level 2" Underlined, cyan colour .IP "Level 3" 4 .IX Item "Level 3" Bold .SS "format_note" .IX Subsection "format_note" .Vb 1 \& $str = Commandable::Output\->format_note( $text, $level ) .Ve .PP Returns a value for printing, to somehow highlight the given text (which should be a short word or string) at the given level. .PP The default implementation applies the following formatting if \&\f(CW\*(C`String::Tagged\*(C'\fR is available: .IP "Level 0" 4 .IX Item "Level 0" Bold, yellow colour .IP "Level 1" 4 .IX Item "Level 1" Bold, cyan colour .IP "Level 2" 4 .IX Item "Level 2" Bold, magenta colour .SH "AUTHOR" .IX Header "AUTHOR" Paul Evans