format_output 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9c8c65f32fd95cbd19905fc587273dbea1ce18da
+  data.tar.gz: baf65ce1f265d28f1174e5ac4151852c432ced21
+SHA512:
+  metadata.gz: d42cd2b4fa43e1beaeaac9779bb389716543e89b80be942cf0d20eff34575f8e90677ffd5c55c749c9f19f77c2850aecfc4e0408bff5e9f7f1b173bce8d70078
+  data.tar.gz: 53ac409dcef76919bf95553f642e6ac3ac2ca7ede43d6d730b1200f0615b328d7bb4f7992d24de79e145633e2e02ee2ad963c40051283a87bab4bd9bc1c6fe7d

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at peter.c.camilleri@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in format_output.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 PeterCamilleri
+
+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.

data/README.md

@@ -0,0 +1,352 @@
+# FormatOutput
+
+The format_output gem is used to facilitate the creation of CLI programs in
+Ruby by formatting data as bullet points, columns, or word wrap to the console,
+strings, or arrays of strings.
+
+This gem started out life buried deep within the mysh gem where it served as
+the data formatting facility for that program. Such was the usefulness of these
+methods that the long task of splitting them away from mysh was started.
+
+Along the way, additional capabilities were added to flesh out range of
+available formatting transformations. The following  are taken from the
+format_output unit test suite and include:
+
+### Columns
+
+Neat, efficient columns of data are nice:
+
+    0 5 10 15 20 25 30 35 40 45 50 55 60 65 70 75 80 85 90 95
+    1 6 11 16 21 26 31 36 41 46 51 56 61 66 71 76 81 86 91 96
+    2 7 12 17 22 27 32 37 42 47 52 57 62 67 72 77 82 87 92 97
+    3 8 13 18 23 28 33 38 43 48 53 58 63 68 73 78 83 88 93 98
+    4 9 14 19 24 29 34 39 44 49 54 59 64 69 74 79 84 89 94 99
+
+### Bullet Points
+
+How about making some (bullet) points:
+
+    Name      Wiley Coyote
+    Education Super Genius
+    Incident  Run over by a large truck
+    Status    Flattened and accordion like
+
+### Word Wrap
+
+Well long text can be hard to (word) wrap your head around:
+
+    There are many many stars in the
+    heavens. Lots really. Like billions and
+    billions
+
+    There are many many fishies in the sea.
+    Lots really. Like billions and billions
+
+    There are many many birds in the sky.
+    Lots really. Like billions and billions
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'format_output'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install format_output
+
+## Usage
+
+### Formatting Control Parameters
+
+The formatting of output is controlled by four parameters. These are:
+
+Parameter| Description                                                       | Default
+---------|-------------------------------------------------------------------|-----------
+width    |The overall width of the output "stage".                           | 80
+left     |The size of the left margin. White space to the left of the data.  | 0
+body     |The center of the "stage" where the formatted data resides.        | 80
+right    |The size of the right margin. White space to the right of the data.| 0
+
+These relationships are illustrated below:
+
+    |<-------------------------- width --------------------------->|
+    |<left  margin>|<------------ body ------------>|<right margin>|
+                     1  4  7  10  13  16  19  22  25
+                     2  5  8  11  14  17  20  23
+                     3  6  9  12  15  18  21  24
+
+      width = 60
+      left  = 14
+      right = 14
+      body  = 32
+
+In many cases however, the programmer will not need to modify these parameters.
+That is the defaults values provided are suitable for most application.
+
+If the defaults are not suitable, there are two approaches that are available:
+
+1. The global parameters can be changed. For example:
+
+    FormatOutput.width = 132
+
+2. The parameters can be set for one call only. For example:
+
+    my_array.format_output_columns(left: 5, right: 5)
+
+
+Note: The format_output parameters are connected in that they define the same
+formatting work area. As a result, the following interactions occur:
+
+    FormatOutput.left            # Gets the left margin
+    FormatOutput.left  = value   # Sets the left margin
+    FormatOutput.right           # Gets the left margin
+    FormatOutput.right = value   # Sets the left margin
+    FormatOutput.width           # Gets the full width
+    FormatOutput.width = value   # Sets the full width
+    FormatOutput.body            # Gets width - (left + right)
+    FormatOutput.width = value   # Sets width = value + left + right
+
+As can be seen, setting the body and setting the other parameters does interact
+quite a bit. So these rules should be followed:
+
+* Always set left and right margins before setting the body. Otherwise, the
+body setting will be modified to a value other than the set value.
+* Don't set both the body and the width or unexpected results may be observed.
+
+When parameters are passed in for individual calls, they take effect at the
+same time so the ordering is not significant. Still, setting body and width
+will have unpredictable results.
+
+### API Levels
+
+Each of the three types of formatting has three levels of support. These are
+summarized as follows:
+
+Columns                   | Word Wrap                  | Bullet Points            | Returns
+--------------------------|----------------------------|--------------------------|----------------
+puts_format_output_columns|puts_format_output_word_wrap|puts_format_output_bullets| nil
+format_output_columns     |format_output_word_wrap     |format_output_bullets     | a string
+format_output_raw_columns |format_output_raw_word_wrap |format_output_raw_bullets | [strings]
+
+The puts_etc methods return nil because they directly print the results of the
+formatting using the puts method. The intermediate methods return a string,
+replete with any needed new line characters. Finally the "raw" methods return
+an array of strings in place of said new line sequences.
+
+Regardless of how output of the results is achieved, the formatting done is the
+same for all three levels. The next sections focus on that formatting.
+
+### Columns
+
+The column format is used to display data in neat columns. Yes sure, you can
+just do a puts on an array of data and it will blast it to the console, one
+item per line, but that can be a lot off lines scrolling meaninglessly off the
+screen.
+
+Column formatting tries to use as few lines of output as it can. For example:
+
+```ruby
+# Some simple number, squared, and cubed columns
+column_data = Array.new(25) { |i| "#{i}, #{i*i}, #{i*i*i}  " }
+puts "Numbers, squares, and cubes.", ""
+column_data.puts_format_output_columns(width: 72)
+```
+
+The output is:
+
+    Numbers, squares, and cubes.
+
+    0, 0, 0      7, 49, 343      14, 196, 2744   21, 441, 9261
+    1, 1, 1      8, 64, 512      15, 225, 3375   22, 484, 10648
+    2, 4, 8      9, 81, 729      16, 256, 4096   23, 529, 12167
+    3, 9, 27     10, 100, 1000   17, 289, 4913   24, 576, 13824
+    4, 16, 64    11, 121, 1331   18, 324, 5832
+    5, 25, 125   12, 144, 1728   19, 361, 6859
+    6, 36, 216   13, 169, 2197   20, 400, 8000
+
+Now this is not meant to be optimal, but to instead show how neat columns are
+created even with items of varying length.
+
+### Word Wrap
+
+The word wrap format is used to take very long lines of text and convert it
+into a number of shorter lines. The trick is to avoid splitting words and
+making the text hard to read.
+
+```ruby
+# Maybe (word) wrap your head around a little Shakespear?
+long_text = "Wherefore rejoice? What conquest brings he home? What tributaries follow him to Rome, to grace in captive bonds his chariot-wheels? You blocks, you stones, you worse than senseless things!"
+puts "", "", "Word wrapping the Great Bard!", ""
+long_text.puts_format_output_word_wrap(width: 72)
+```
+
+The output is:
+
+    Word wrapping the Great Bard!
+
+    Wherefore rejoice? What conquest brings he home? What tributaries
+    follow him to Rome, to grace in captive bonds his chariot-wheels? You
+    blocks, you stones, you worse than senseless things!
+
+Now, if the input is an array of really long strings, the word wrapper will
+convert each of those lines into a neatly word wrapped paragraph with a blank
+line between them.
+
+### Bullet Points
+
+The bullet point formatter is used to create an output consisting of one or
+more bullet points. So how is a bullet point defined? There are two essential
+components, illustrated here:
+
+    tag1 detail1
+    tag2 detail2
+    tag3 etc etc etc
+
+So what is the input? An array of bullet point data of course! That is an array
+of arrays. The following array describes the sample bullet point above:
+
+```ruby
+datum = [["tag1", "detail1"],["tag2", "detail2"],["tag3", "etc etc etc"]]
+datum.puts_format_output_bullets
+```
+
+Now, this array contained in the outer array describes the actual bullet points
+that are created. This inner array may contain zero or more elelemts.
+
+#### Zero Elements and Empty Bullets
+
+When an empty array is used, the bullet formatter skips that entry. This can be
+useful when gathering data for a report and for one item no data is found.
+There are three ways to create an empty bullet point:
+
+```ruby
+[]
+["zero", []]
+["zero", nil]
+```
+
+Note that the following, is not fully empty
+
+```ruby
+["zero", ""]
+```
+
+Yields a bullet point with a bullet of "zero" and no detail text.
+
+#### One Element
+
+When an array with one element is used, that element becomes the detail and the
+default bullet ("*") is used:
+
+```ruby
+["one with a (default) bullet."]
+```
+
+produces:
+
+    *     one with a (default) bullet.
+
+#### Two Elements
+
+When an array with two elements is used, the first is the bullet and the second
+is the detail. This is by far the most common:
+
+```ruby
+["two", 2],
+```
+
+produces:
+
+    two   2
+
+
+#### Three or more Elements
+
+When an array with three or more elements is used, the first is the bullet and
+the second is the detail. The rest of the elements are additional details for
+this bullet point. Like this:
+
+```ruby
+["three", 3, "more than two", "more than one", "more than zero"],
+```
+
+produces:
+
+    three 3
+          more than two
+          more than one
+          more than zero
+
+#### The Details
+
+Now we can turn our attention to the actual details and to a lesser extent, the
+tags. These can be:
+
+1. A String
+2. An object that responds favorably to the to_s method.
+
+In addition, the details may be an Array.
+
+So when the details are a string that string is used as the details. And yes,
+if the string is too long to fit, it gets word wrapped! Like this:
+
+```ruby
+['five', "I can see for miles and miles and more miles and yet more miles and a lot of miles and damn more miles"]
+```
+
+produces:
+
+    five  I can see for miles and miles and more miles and yet more miles
+          and a lot of miles and damn more miles
+
+Note, this courtesy does not extend to the bullet tags. They must exhibit a
+sensible level of brevity!
+
+Further, when the details are contained in there own little array, they are
+displayed in columns if they don't fit in one line. Look here:
+
+```ruby
+["four", (1..100).to_a]
+```
+
+produces:
+
+    four  1 6  11 16 21 26 31 36 41 46 51 56 61 66 71 76 81 86 91 96
+          2 7  12 17 22 27 32 37 42 47 52 57 62 67 72 77 82 87 92 97
+          3 8  13 18 23 28 33 38 43 48 53 58 63 68 73 78 83 88 93 98
+          4 9  14 19 24 29 34 39 44 49 54 59 64 69 74 79 84 89 94 99
+          5 10 15 20 25 30 35 40 45 50 55 60 65 70 75 80 85 90 95 100
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+OR...
+
+* Make a suggestion by raising an
+ [issue](https://github.com/PeterCamilleri/format_output/issues)
+. All ideas and comments are welcome.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](./LICENSE.txt).
+
+## Code of Conduct
+
+Everyone interacting in the format_output project’s codebases, issue trackers,
+chat rooms and mailing lists is expected to follow the
+[code of conduct](./CODE_OF_CONDUCT.md).

data/exe/README.md

@@ -0,0 +1,43 @@
+# format_output_demo
+
+The format_output gem comes with the format_output_demo program. The source
+code for that program is in this folder. This file shows the output of that
+program:
+
+    A simple demo of the format_output gem in action.
+
+
+    Numbers, squares, and cubes.
+
+    0, 0, 0      7, 49, 343      14, 196, 2744   21, 441, 9261
+    1, 1, 1      8, 64, 512      15, 225, 3375   22, 484, 10648
+    2, 4, 8      9, 81, 729      16, 256, 4096   23, 529, 12167
+    3, 9, 27     10, 100, 1000   17, 289, 4913   24, 576, 13824
+    4, 16, 64    11, 121, 1331   18, 324, 5832
+    5, 25, 125   12, 144, 1728   19, 361, 6859
+    6, 36, 216   13, 169, 2197   20, 400, 8000
+
+
+    Word wrapping the Great Bard!
+
+    Wherefore rejoice? What conquest brings he home? What tributaries
+    follow him to Rome, to grace in captive bonds his chariot-wheels? You
+    blocks, you stones, you worse than senseless things!
+
+
+    And now some Bullet Points!
+
+    zero
+    *     one with a (default) bullet.
+    two   2
+    three 3
+          more than two
+          more than one
+          more than zero
+    four  1 6  11 16 21 26 31 36 41 46 51 56 61 66 71 76 81 86 91 96
+          2 7  12 17 22 27 32 37 42 47 52 57 62 67 72 77 82 87 92 97
+          3 8  13 18 23 28 33 38 43 48 53 58 63 68 73 78 83 88 93 98
+          4 9  14 19 24 29 34 39 44 49 54 59 64 69 74 79 84 89 94 99
+          5 10 15 20 25 30 35 40 45 50 55 60 65 70 75 80 85 90 95 100
+    five  I can see for miles and miles and more miles and yet more miles
+          and a lot of miles and damn more miles

data/exe/format_output_demo

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+#
+# A demo of the format_output gem.
+#
+
+require_relative '..\lib\format_output'
+
+puts "A simple demo of the format_output gem in action."
+
+# Some simple number, squared, and cubed columns
+column_data = Array.new(25) { |i| "#{i}, #{i*i}, #{i*i*i}  " }
+puts "", "", "Numbers, squares, and cubes.", ""
+column_data.puts_format_output_columns(width: 72)
+
+# Maybe (word) wrap your head around a little Shakespear?
+long_text = "Wherefore rejoice? What conquest brings he home? What tributaries follow him to Rome, to grace in captive bonds his chariot-wheels? You blocks, you stones, you worse than senseless things!"
+puts "", "", "Word wrapping the Great Bard!", ""
+long_text.puts_format_output_word_wrap(width: 72)
+
+# And now to dodge a bullet (point) or twelve!
+
+demo = [
+         [],
+         ["zero", []],
+         ["zero", nil],
+         ["zero", ""],
+         ["one with a (default) bullet."],
+         ["two", 2],
+         ["three", 3, "more than two", "more than one", "more than zero"],
+         ["four", (1..100).to_a],
+         ['five', "I can see for miles and miles and more miles and yet more miles and a lot of miles and damn more miles"],
+       ]
+
+puts "", "", "And now some Bullet Points!", ""
+
+demo.puts_format_output_bullets(width: 72)

data/format_output.gemspec

@@ -0,0 +1,32 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "format_output/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "format_output"
+  spec.version       = FormatOutput::VERSION
+  spec.authors       = ["PeterCamilleri"]
+  spec.email         = ["peter.c.camilleri@gmail.com"]
+
+  spec.summary       = %q{Formatted output to the console or strings.}
+  spec.description   = %q{Formatted bullet points, columns, or word wrap to the console or strings.}
+  spec.homepage      = "https://github.com/PeterCamilleri/format_output"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+                          f.match(%r{^(test|docs)/})
+                        end
+  spec.bindir        = "exe"
+  spec.executables   = spec
+                         .files
+                         .reject { |f| f.downcase == 'exe/readme.md'}
+                         .grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.17"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency 'minitest_visible', "~> 0.1"
+  spec.add_development_dependency 'reek', "~> 5.0.2"
+
+end

data/lib/format_output/builders/bullet_builder.rb

@@ -0,0 +1,61 @@
+# coding: utf-8
+
+# Print out bullet points.
+module FormatOutput
+
+  # A class to build bullet points for display.
+  class BulletPointBuilder
+
+    # Prepare a blank slate.
+    def initialize(options)
+      @body        = ::FormatOutput.width(options)
+      @pad         = ::FormatOutput.pad(options)
+      @bullet_data = []
+      @key_length  = nil
+    end
+
+    # Add items to these bullet points.
+    def add(bullet, *items)
+      items.each do |item|
+        @bullet_data << [bullet.to_s, item]
+        bullet = ""
+      end
+    end
+
+    # Render the bullet points as an array of strings.
+    def render
+      @key_length, results = get_key_length, []
+
+      @bullet_data.each do |key, item|
+        results.concat(render_bullet(key, item))
+      end
+
+      @bullet_data = []
+      results
+    end
+
+    private
+
+    # Allowing for a trailing space, how large is the largest bullet?
+    def get_key_length
+      (@bullet_data.max_by {|line| line[0].length})[0].length + 1
+    end
+
+    # Render one bullet point.
+    # Returns: An array of strings, formatted as:     bullet  details
+    #                                                         more details
+    #                                                         more etc
+    def render_bullet(key, item)
+      result = []
+
+      item.format_output_bullet_detail(width: @body - @key_length - 1, left: 0).each do |desc_line|
+        result << @pad + key.ljust(@key_length) + desc_line
+        key = ""
+      end
+
+      result
+    end
+
+  end
+
+end

data/lib/format_output/builders/column_builder.rb

@@ -0,0 +1,116 @@
+# coding: utf-8
+
+# Print out data in neat columns.
+module FormatOutput
+
+  # A class to build columns for display.
+  class ColumnBuilder
+
+    # Prepare a blank page.
+    def initialize(options)
+      @body        = ::FormatOutput.body(options)
+      @pad         = ::FormatOutput.pad(options)
+      @page_data   = []
+    end
+
+    # Add an item to this page.
+    # Returns: The number of items that did not fit in the page.
+    def add(raw_item)
+      item = raw_item.to_s
+      fail "Item too large to fit." unless item.length < @body
+
+      if (column = find_next_column)
+        @page_data[column] << item
+      else
+        @page_data << [item]
+      end
+
+      adjust_configuration
+    end
+
+    # Render the page as an array of strings.
+    def render
+      results, column_widths = [], get_column_widths
+
+      rows.times { |row_index| results << render_row(row_index, column_widths)}
+
+      @page_data.clear
+      results
+    end
+
+    private
+
+    # Get the widths of all columns
+    def get_column_widths
+      @page_data.map {|column| column.format_output_greatest_width}
+    end
+
+    # Render a single row of data.
+    # Returns: A string.
+    def render_row(row_index, widths)
+      @pad + @page_data.each_with_index.map do |column, index|
+        column[row_index].to_s.ljust(widths[index])
+      end.join(" ")
+    end
+
+    # Make sure the page fits within its boundaries.
+    def adjust_configuration
+      while total_width >= @body
+        add_a_row
+      end
+    end
+
+    # Add a row to the page, moving items as needed.
+    def add_a_row
+      new_rows = rows + 1
+      pool, @page_data = @page_data.flatten, []
+
+      until pool.empty?
+        @page_data << pool.shift(new_rows)
+      end
+    end
+
+    # Compute the total width of all of the columns.
+    # Returns: The sum of the widths of the widest items of each column plus
+    #          a space between each of those columns.
+    def total_width
+      if empty?
+        0
+      else
+        #The starting point, @page_data.length-1, represents the spaces needed
+        #between the columns. So N columns means N-1 spaces.
+        @page_data.inject(@page_data.length-1) do |sum, column|
+          sum + column.format_output_greatest_width
+        end
+      end
+    end
+
+    # Does the data fit on the page?
+    def fits?
+      total_width < @body
+    end
+
+    # How many rows are currently in this page?
+    def rows
+      empty? ? 0 : @page_data[0].length
+    end
+
+    # Is this page empty?
+    def empty?
+      @page_data.empty?
+    end
+
+    # Which column will receive the next item?
+    # Returns: The index of the first non-filled column or nil if none found.
+    def find_next_column
+      (1...(@page_data.length)).each do |index|
+        if @page_data[index].length < @page_data[index-1].length
+          return index
+        end
+      end
+
+      nil
+    end
+  end
+
+end

data/lib/format_output/bullets.rb

@@ -0,0 +1,134 @@
+# coding: utf-8
+
+# Support for displaying an array formatted neatly.
+# Output as bullet points starts with an array as input.
+class Array
+
+  # Print out the array as bullet points.
+  def puts_format_output_bullets(options = {})
+    puts format_output_bullets(options)
+  end
+
+  # Convert the array to a string with bullet points.
+  # Returns: A string.
+  def format_output_bullets(options = {})
+    format_output_raw_bullets(options).join("\n")
+  end
+
+  # Convert the array to strings with bullet points.
+  # Returns: An array of strings.
+  def format_output_raw_bullets(options = {})
+    return [""] if empty?
+
+    builder = FormatOutput::BulletPointBuilder.new(options)
+
+    each {|pair| builder.add(*pair.format_output_prepare_bullet_detail)}
+
+    builder.render
+  end
+
+  # Helper methods for the BulletPointBuilder
+
+  # This method is a duplicate of a column method with a new name.
+  alias :format_output_bullet_detail :format_output_raw_columns
+
+  # Get data ready for being in a bullet point.
+  def format_output_prepare_bullet_detail
+    if length < 2
+      ["*", self[0]]
+    else
+      self
+    end
+  end
+
+end
+
+# Support for displaying data formatted neatly.
+class Object
+
+  # Create a bullet point description from this object.
+  # Returns: An array of strings.
+  def format_output_bullet_detail(options = {})
+    self.to_s.format_output_bullet_detail(options)
+  end
+
+  # Get data ready for being in a bullet point.
+  def format_output_prepare_bullet_detail
+    ["*", self]
+  end
+
+end
+
+# Support for displaying nothing formatted neatly.
+class NilClass
+
+  # Create a bullet point description from nothing.
+  # Returns: An array of nothing.
+  def format_output_bullet_detail(_options = nil)
+    []
+  end
+
+end
+
+# Support for displaying string data formatted in bullet points.
+class String
+
+  # Create a bullet point description from this string.
+  # Returns: An array of strings.
+  def format_output_bullet_detail(options = {})
+    body = ::FormatOutput.width(options)
+    pad  = ::FormatOutput.pad(options)
+
+    do_format_output_bullet_detail(split(' ').each, body, pad)
+  end
+
+  # Do the formatting legwork.
+  # Returns: An array of strings.
+  def do_format_output_bullet_detail(input, body, pad)
+    buffer, build, empty = [], "", false
+
+    # Grab "words" of input, splitting off lines as needed.
+    # Note: This loop exits when input.next runs out of data.
+    loop do
+      build = build.format_output_split_if_over(buffer, body, pad, input.next)
+                   .format_output_split_if_huge(buffer, body, pad)
+
+      empty = build.empty?
+    end
+
+    unless empty
+      buffer << pad + build
+    end
+
+    buffer
+  end
+
+  # Split if adding a word goes over a little.
+  # Note: self is the build string from do_format_output_bullet_detail.
+  # Returns: A string.
+  def format_output_split_if_over(buffer, body, pad, word)
+    word.prepend(" ") unless empty? #Add a space except for the first word.
+
+    word_len = word.length
+
+    if (length + word_len) >= body && word_len < body
+      buffer << pad + self    # Line done, add to buffer.
+      word.lstrip             # Start of a new line, remove the leading space.
+    else
+      self + word
+    end
+  end
+
+  # Split up a overlong blob of text.
+  # Note: self is the result string from format_output_split_if_over.
+  # Returns: A string.
+  def format_output_split_if_huge(buffer, body, pad)
+
+    # Slice away any excess text into lines in the buffer.
+    while length >= body
+      buffer << pad + slice!(0, body)
+    end
+
+    self
+  end
+end

data/lib/format_output/columns.rb

@@ -0,0 +1,37 @@
+# coding: utf-8
+
+# Support for displaying an array formatted neatly.
+# Output as columns starts with an array as input.
+class Array
+
+  # Print out the array with efficient columns.
+  def puts_format_output_columns(options = {})
+    puts format_output_columns(options)
+  end
+
+  # Convert the array to a string with efficient columns.
+  # Returns: A string.
+  # Endemic Code Smells reek:FeatureEnvy -- false positive.
+  def format_output_columns(options = {})
+    format_output_raw_columns(options).join("\n")
+  end
+
+  # Convert the array to strings with efficient columns.
+  # Returns: An array of strings.
+  def format_output_raw_columns(options = {})
+    builder = FormatOutput::ColumnBuilder.new(options)
+
+    each {|item| builder.add(item)}
+
+    builder.render
+  end
+
+  # Helper methods for the ColumnBuilder
+
+  # Get the widest element of an array.
+  # Returns: The width of the widest string in the array.
+  def format_output_greatest_width
+    max_by {|item| item.length}.length
+  end
+
+end

data/lib/format_output/version.rb

@@ -0,0 +1,7 @@
+# coding: utf-8
+
+module FormatOutput
+  VERSION = "0.1.0".freeze
+
+  DESCRIPTION = "Formatted output to the console or strings.".freeze
+end

data/lib/format_output/word_wrap.rb

@@ -0,0 +1,51 @@
+# coding: utf-8
+
+# Support for displaying an array of strings formatted with word wrap.
+class Array
+
+  # Print out the array with word wrap.
+  def puts_format_output_word_wrap(options = {})
+    puts format_output_word_wrap(options).join("\n")
+  end
+
+  # Convert the array to a string with bullet points.
+  # Returns: A string.
+  def format_output_word_wrap(options = {})
+    format_output_raw_word_wrap(options).join("\n")
+  end
+
+  # Returns: An array of strings.
+  # This method is a duplicate of a bullet point method with a new name.
+  def format_output_raw_word_wrap(options = {})
+    result = []
+
+    each do |item|
+      result.concat(item.to_s.format_output_raw_word_wrap(options))
+      result << ""
+    end
+
+    result
+  end
+
+end
+
+# Support for displaying string data formatted with word wrap.
+class String
+
+  # Print out the string with word wrap.
+  def puts_format_output_word_wrap(options = {})
+    puts format_output_word_wrap(options)
+  end
+
+  # Convert the string to a string with bullet points.
+  # Returns: A string.
+  def format_output_word_wrap(options = {})
+    format_output_raw_word_wrap(options).join("\n")
+  end
+
+  # Convert the string to an array of strings with word wrap.
+  # Returns: An array of strings.
+  # This method is a duplicate of a bullet point method with a new name.
+  alias :format_output_raw_word_wrap :format_output_bullet_detail
+
+end

data/lib/format_output.rb

@@ -0,0 +1,70 @@
+# coding: utf-8
+
+require_relative "format_output/columns"
+require_relative "format_output/bullets"
+require_relative "format_output/word_wrap"
+
+require_relative "format_output/builders/bullet_builder"
+require_relative "format_output/builders/column_builder"
+
+require_relative "format_output/version"
+
+# The format output facility. Neat columns and bullet points for all!
+module FormatOutput
+
+  # Some property variables.
+  @width = 80
+  @left  = 0
+  @right = 0
+
+  class << self
+
+    # Get the full page width.
+    def width(options = {})
+      (options[:width] || @width).to_i
+    end
+
+    # Set the full page width.
+    def width=(value)
+      @width = value.to_i
+    end
+
+    # Get the working page width.
+    def body(options = {})
+      width(options) - (left(options) + right(options))
+    end
+
+    # Set the working page width.
+    # Note always set after left and right are set.
+    def body=(value)
+      @width = value.to_i + @left + @right
+    end
+
+    # Get the left margin
+    def left(options = {})
+      (options[:left] || @left).to_i
+    end
+
+    # Set the left margin
+    def left=(value)
+      @left = value.to_i
+    end
+
+    # Get the left margin
+    def right(options = {})
+      (options[:right] || @right).to_i
+    end
+
+    # Set the right margin
+    def right=(value)
+      @right = value.to_i
+    end
+
+    # The left margin pad string.
+    def pad(options = {})
+      " " * left(options)
+    end
+
+  end
+
+end

data/rakefile.rb

@@ -0,0 +1,16 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :default => :test
+
+desc "What version of format_output is this?"
+task :vers do |t|
+  puts
+  puts "format_output version = #{::FormatOutput::VERSION}"
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: format_output
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- PeterCamilleri
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-12-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: minitest_visible
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: reek
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.0.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.0.2
+description: Formatted bullet points, columns, or word wrap to the console or strings.
+email:
+- peter.c.camilleri@gmail.com
+executables:
+- format_output_demo
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- exe/README.md
+- exe/format_output_demo
+- format_output.gemspec
+- lib/format_output.rb
+- lib/format_output/builders/bullet_builder.rb
+- lib/format_output/builders/column_builder.rb
+- lib/format_output/bullets.rb
+- lib/format_output/columns.rb
+- lib/format_output/version.rb
+- lib/format_output/word_wrap.rb
+- rakefile.rb
+homepage: https://github.com/PeterCamilleri/format_output
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2
+signing_key: 
+specification_version: 4
+summary: Formatted output to the console or strings.
+test_files: []