Formatters

Formatters are used to indicate progress in a report. There are a couple built in formatters for common tasks and serve as examples to build other formatters.

Progress Formatter

Example

require 'command_line_reporter'

class Example
  include CommandLineReporter

  def initialize
    self.formatter = 'progress'
  end

  def run
    x = 0
    report do
      10.times do
        x += 1
        progress
      end
    end
  end
end

Example.new.run

This simply produces 10 dots (.) in succession indicating you have made ten additions to variable x:

Indicator

The indicator is the string that is displayed in the command line interface that indicates progress. The default is the dot (.) but any string is allowed. In fact one can use the erase character to get crafty with displaying percent complete in place.

Instance Methods

• format(hash) - Hash that allows definition of the following properties:
  • :indicator - The string to use to indicate progress
  • :color - The color to use for the terminal output i.e. 'red' or 'blue' or 'green'
  • :bold - true|false to boldface the font

This method will rarely be called in your code directly because it is the interface the formatter adheres to in the report block.

• indicator(string) - This overrides the default value of the dot (.) being used for all calls to the report method.

formatter.indicator('*')

• progress(string) - Call this method to invoke the output to the command line interface. The string overrides the indicator for this call only.

formatter.progress
formatter.progress("^H^H^H10%")

• color=(string) - String that represents the color to output the text in

formatter.color = 'red'

• bold=(boolean) - true|false indicates whether to use boldface font

formatter.bold = true

Nested Formatter

The nested formatter concept is inspired by the documentation formatter in RSpec. The idea is to be able to create nested grouping levels of output that are very readable as the code is being executed.

Example

require 'command_line_reporter'

class Example
  include CommandLineReporter

  def initialize
    self.formatter = 'nested'
  end

  def run
    x,y,z = 0,0,0

    report(message: 'calculating first expression') do
      x = 2 + 2
      2.times do
        report(message: 'calculating second expression') do
          y = 10 - x
          10.times do |i|
            report(message: 'pixelizing', type: 'inline', complete: "#{i*10+10}%") do
              z = x + y
            end
          end
        end
      end
    end
  end
end

Example.new.run

This produces the more complex output:

Instance Methods

• format(hash) - Hash that allows definition of the following properties:
  • :message - The string to display at the start of the nested block output
  • :type - Use 'inline' to indicate the nesting is to occur on the same line
  • :complete - The string to display when the nested report block is finished
  • :indent_size - The number of spaces to use for indenting the block. Two (2) characters is the default
  • :color - The color to use for the terminal output i.e. 'red' or 'blue' or 'green'
  • :bold - true|false to boldface the font

This method will rarely be called in your code directly because it is the interface the formatter adheres to in the report block.

• message_string(string) - This defines the string that is displayed as the first part of the message to the user. The default value is "working".

formatter.message_string('working')

• complete_string(string) - This defines the string that completes the message to the user for the report. The default value is "complete".

formatter.complete_string('done')

• indent_size(int) - The number of spaces to indent for a single indentation level. The default value is 2 spaces.

formatter.indent_size(4)

• color=(string) - String that represents the color to output the text in

formatter.color = 'red'

• bold=(boolean) - true|false indicates whether to use boldface font

formatter.bold = true