Command Line Reporter

This gem provides a DSL that makes it easy to write reports of various types in Ruby. It eliminates the need to litter your source with puts statements, instead providing a more readable, expressive interface to your application. Some of the best features include:

• Formatters that automatically indicate progress
• Table syntax similar to HTML that makes it trivial to format your data in rows and columns
• Easily created headers and footers for your report
• Output suppression that makes it easy for your script to support a quiet flag
• Capture report output as a string

Tables can be rendered in Unicode or ASCII. The default is Unicode when available. Here is an example of output you can generate with "the reporter":

Installation

It is up on rubygems.org so add it to your bundle in the Gemfile:

gem 'command_line_reporter', '~> 5.0'

or do it the old fashioned way:

gem install command_line_reporter

Usage

The gem provides a mixin that can be included in your scripts.

require 'command_line_reporter'

class MyReport
  include CommandLineReporter
  ...
end

Requirements

• Ruby 3.4 or newer (see .ruby-version for the repo target).

Development

bundle install
bundle exec rspec
bundle exec rubocop
bundle exec reek

Wiki

The Wiki has all of the documentation necessary for getting you started.

API Reference

There are several methods the mixin provides that do not depend on the formatter used:

• header(hash) and footer(hash)
  • :title - The title text for the section. Default: 'Report'
  • :width - The width in characters for the section. Default: 100
  • :align - 'left'|'right'|'center' align the title text. Default: 'left'
  • :spacing - Number of vertical lines to leave as spacing after|before the header|footer. Default: 1
  • :timestamp - Include a line indicating the timestamp below|above the header|footer text. Either true|false. Default: false
  • :rule - true|false indicates whether to include a horizontal rule below|above the header|footer. Default: false
  • :color - The color to use for the terminal output i.e. 'red' or 'blue' or 'green'
  • :bold - true|false to boldface the font
• report(hash) {block}
  • The first argument is a hash that defines the options for the method. See the details in the formatter section for allowed values.
  • The second argument is a block of ruby code that you want executed within the context of the reporter. Any ruby code is allowed. See the examples that follow in the formatter sections for details.
• formatter=(string)
  • Factory method indicating the formatter you want your application to use. At present the 2 formatters are (Default: 'nested'):
  • 'progress' - Use the progress formatter
  • 'nested' - Use the nested (or documentation) formatter
• horizontal_rule(hash)
  • :char - The character used to build the rule. Default: '-'
  • :width - The width in characters of the rule. Default: 100
  • :color - The color to use for the terminal output i.e. 'red' or 'blue' or 'green'
  • :bold - true|false to boldface the font
• vertical_spacing(int)
  • Number of blank lines to output. Default: 1
• datetime(hash)
  • :align - 'left'|'center'|'right' alignment of the timestamp. Default: 'left'
  • :width - The width of the string in characters. Default: 100
  • :format - Any allowed format from #strftime#. Default: %Y-%m-%d %H:%I:%S%p

To Do

• Add a formatter that supports html output

Contributing

See AGENTS.md for contributor guidelines and CONTRIBUTING.md for how to get started.

Acknowledgements

See ACKNOWLEDGEMENTS.md for contributor credits.

License

Copyright (c) 2011-2026 Wes Bailey

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.