"Commandable::Output" - abstractions for printing output from commands
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 "Commandable" system itself.
Implementations are permitted (encouraged, even) to replace any of these methods
in order to customise their behaviour.
If String::Tagged and Convert::Color are available, this module applies
formatting to strings by using the String::Tagged::Formatting conventions. The
"format_heading" and "format_note" methods will return
results as instances of "String::Tagged", suitable to pass into the
main "printf" method.
Commandable::Output->printf( $format, @args )
The main output method, used to send messages for display to the user. The
arguments are formatted into a single string by Perl's "printf"
function. This method does not append a linefeed. To output a complete line of
text, remember to include the "\n" at the end of the format string.
The default implementation writes output on the terminal via STDOUT.
In cases where the output should be sent to some other place (perhaps a GUI
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 "sprintf" to format the arguments into a string.
no warnings 'redefine';
sub Commandable::Output::printf
{
shift; # the package name
my ( $format, @args ) = @_;
my $str = sprintf $format, @args;
$gui_display_widget->append_text( $str );
}
If String::Tagged::Terminal is available, the output will be printed using this
module, by first converting the format string and arguments using
"from_sprintf" in String::Tagged and then constructing a terminal
string using "new_from_formatting" in String::Tagged::Terminal. This
means the default implementation will be able to output formatted strings
using the String::Tagged::Formatting conventions.
Commandable::Output->print_heading( $text, $level )
Used to send output that should be considered like a section heading.
$level may be an integer used to express sub-levels;
increasing values from 1 upwards indicate increasing sub-levels.
The default implementation formats the text string using
"format_heading" then prints it using "printf" with a
trailing linefeed.
$str = Commandable::Output->format_heading( $text, $level )
Returns a value for printing, to represent a section heading for the given text
and level.
The default implementation applies the following formatting if
"String::Tagged" is available:
- Level 1
- Underlined
- Level 2
- Underlined, cyan colour
- Level 3
- Bold
$str = Commandable::Output->format_note( $text, $level )
Returns a value for printing, to somehow highlight the given text (which should
be a short word or string) at the given level.
The default implementation applies the following formatting if
"String::Tagged" is available:
- Level 0
- Bold, yellow colour
- Level 1
- Bold, cyan colour
- Level 2
- Bold, magenta colour
Paul Evans <
[email protected]>