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>