NAME

Commandable::Output - abstractions for printing output from commands

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 Commandable system itself.

Implementations are permitted (encouraged, even) to replace any of these methods in order to customise their behaviour.

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 format_heading and format_note methods will return results as instances of String::Tagged, suitable to pass into the main printf method.

METHODS

printf

   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.

print_heading

   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.

format_heading

   $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

format_note

   $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

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

cpanm Commandable

perl -MCPAN -e shell
install Commandable