tabulo 2.6.3 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cdf2e4da09cd06510108899c38ddd3c144b04daa4b8f54f3a45593a78aee4f92
-  data.tar.gz: fb604197bd38a80a74b1282ca693903fd6a064502410e13ad4b1022b64f3adcc
+  metadata.gz: 632d2d2d3b7d0120410d0afd2b8f1d1b341fd1b6daa7802b15b6f791640d409e
+  data.tar.gz: f5720b528f1c4384118196619ea923b317ec3ff7d374fa87d79808361031e7cc
 SHA512:
-  metadata.gz: ee8a6b465a79fef67af10a08c7affc5c83a804b959aaa326202f24efe96aa189dfdd27c31650104f7e80c7eaccbf06ec04374f06f4e76fbdf381151356f438d5
-  data.tar.gz: 18b13fd6d50be85f7e18c98ef23f4d0e3ce035a89ddc494589d5419fec94a85a99d323da969c111455de4890fd4ad8f34ee091da0ceeda320e69621dfc6cef92
+  metadata.gz: 283e3ac39971cfdf9df9968fe0e40b00d049865fe7f49ef0403d71e35ea8f49a43d85579cb9f12d080e0bacafa48c943d2e57176309be99809272983cd9db2d7
+  data.tar.gz: 32256e95de32d81a65d64e49a6f1eb42c33d7ccca2c76a5d6ce5cb6d0beee8c9d5588aa6d5df2c68a59ac8805e5b5048851a0959ddf281eaf891771ee162158c

data/.github/workflows/tests.yml

@@ -0,0 +1,58 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Tests
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: [
+          '2.2.10',
+          '2.3.8',
+          '2.4.10',
+          '2.5.9',
+          '2.6.7',
+          '2.7.3',
+          '3.0.1',
+        ]
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+      uses: ruby/setup-ruby@v1 # Was: uses: ruby/setup-ruby@473e4d8fe5dd94ee328fdfca9f8c9c7afc9dae5e
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: bundle exec rspec
+
+    - name: Report to Coveralls
+      uses: coverallsapp/github-action@v1.1.2
+      with:
+        github-token: ${{ secrets.github_token }}
+        flag-name: test-${{ matrix.ruby }}-${{ matrix.gemfile }}
+        parallel: true
+
+  finish:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+
+    - name: Report completion to Coveralls
+      uses: coverallsapp/github-action@v1.1.2
+      with:
+        github-token: ${{ secrets.github_token }}
+        parallel-finished: true

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+### v2.7.0
+
+* Add `wrap_preserve` option, allowing whole words to be preserved when wrapping.
+* Internal: Use GitHub actions instead of Travis
+
 ### v2.6.3
 
 * Update dependency versions

data/README.md

@@ -2,8 +2,8 @@
 
 [![Gem Version][GV img]][Gem Version]
 [![Documentation][DC img]][Documentation]
-[![Coverage Status][CS img]][Coverage Status]
 [![Build Status][BS img]][Build Status]
+[![Coverage Status][CS img]][Coverage Status]
 [![Code Climate][CC img]][Code Climate]
 [![Awesome][AR img]][Awesome Ruby]
 
@@ -63,6 +63,7 @@ end
 * The header row can be [repeated](#repeating-headers) at arbitrary intervals
 * Newlines within cell content are correctly handled
 * Multibyte Unicode characters are correctly handled
+* Option to [preserve whole words](#preserve-words) when wrapping content
 * Apply [colours](#colours-and-styling) and other styling to table content and borders, without breaking the table
 * Easily [transpose](#transposition) the table, so that rows are swapped with columns
 * Choose from multiple [border configurations](#borders), including Markdown, “ASCII”, and smoothly
@@ -596,6 +597,46 @@ table = Tabulo::Table.new(
 The character used to indicate truncation, which defaults to `~`, can be configured using the
 `truncation_indicator` option passed to `Table.new`.
 
+<a name="preserve-words"></a>
+#### Wrapping at word boundaries [&#x2191;](#contents)
+
+By passing `:word` to the `wrap_preserve` option on either table initialization (for all columns),
+or when calling `add_column` (for an individual column), whole words can be preserved when wrapping:
+
+```ruby
+sentences = [
+  "Words are preserved.",
+  "Excessively long words may still be split to fit into the configured column width.",
+]
+table = Tabulo::Table.new(sentences, :itself, :length, column_width: 10, wrap_preserve: :word)
+```
+
+```
+> puts table
++------------+------------+
+|   itself   |   length   |
++------------+------------+
+| Words are  |         20 |
+| preserved. |            |
+| Excessivel |         82 |
+| y long     |            |
+| words may  |            |
+| still be   |            |
+| split to   |            |
+| fit into   |            |
+| the        |            |
+| configured |            |
+| column     |            |
+| width.     |            |
++------------+------------+
+```
+
+When wrapping cell content, Tabulo will never insert hyphens itself, although it will recognize existing
+hyphens, m-dashes and n-dashes as word boundaries.
+
+The `wrap_preserve` option defaults to the value `:rune`, meaning by default it will _not_ respect word
+boundaries when wrapping (although it will always preserve whole multibyte Unicode characters).
+
 <a name="manual-wrapping"></a>
 #### Manual cell wrapping [&#x2191;](#contents)
 
@@ -688,7 +729,7 @@ the table.
 The `formatter` callback also has an alternative, 2-parameter version. If `formatter` is passed
 a 2-parameter callable, the second parameter will be given a `CellData` instance,
 containing additional information about the cell that may be useful in determining how to format
-it&mdash;see the [documentation](https://www.rubydoc.info/gems/tabulo/2.6.3/Tabulo/CellData.html)
+it&mdash;see the [documentation](https://www.rubydoc.info/gems/tabulo/2.7.0/Tabulo/CellData.html)
 for details.
 
 <a name="colours-and-styling"></a>
@@ -734,7 +775,7 @@ number is even). The second parameter represents the formatted string value of t
 content after any processing by the [formatter](#formatting-cell-values). The third and fourth
 parameters are optional, and contain further information about the cell and its contents that may be useful in
 determining how to style it. See the
-[documentation](https://www.rubydoc.info/gems/tabulo/2.6.3/Tabulo/Table#add_column-instance_method) for details.
+[documentation](https://www.rubydoc.info/gems/tabulo/2.7.0/Tabulo/Table#add_column-instance_method) for details.
 
 If the content of a cell is wrapped over multiple lines, then the `styler` will be called once
 per line, so that each line of the cell will have the escape sequence applied to it separately
@@ -754,7 +795,7 @@ table.add_column(:even?, header_styler: -> (s) { "\033[32m#{s}\033[0m" })
 ```
 
 The `header_styler` option accepts a 1-, 2- or 3-parameter callable. See the
-[documentation](https://www.rubydoc.info/gems/tabulo/2.6.3/Tabulo/Table#add_column-instance_method)
+[documentation](https://www.rubydoc.info/gems/tabulo/2.7.0/Tabulo/Table#add_column-instance_method)
 for details.
 
 <a name="styling-title"></a>
@@ -768,7 +809,7 @@ table = Tabulo::Table.new(1..5, :itself, :even?, :odd?, title: "Numbers", title_
 ```
 
 The `title_styler` option accepts a 1- or 2-parameter callable. See the
-[documentation](https://www.rubydoc.info/gems/tabulo/2.6.3/Tabulo/Table#initialize-instance_method)
+[documentation](https://www.rubydoc.info/gems/tabulo/2.7.0/Tabulo/Table#initialize-instance_method)
 for details.
 
 <a name="styling-borders"></a>
@@ -963,7 +1004,7 @@ a new table in which the rows and columns are swapped:
 By default, a header row is added to the new table, showing the string value of the element
 represented in that column. This can be configured, however, along with other aspects of
 `transpose`&#8217;s behaviour. For details, see the
-[documentation](https://www.rubydoc.info/gems/tabulo/2.6.3/Tabulo/Table#transpose-instance_method).
+[documentation](https://www.rubydoc.info/gems/tabulo/2.7.0/Tabulo/Table#transpose-instance_method).
 
 <a name="borders"></a>
 ### Configuring borders [&#x2191;](#contents)
@@ -1354,15 +1395,15 @@ The gem is available as open source under the terms of the [MIT
 License](http://opensource.org/licenses/MIT).
 
 [Gem Version]: https://rubygems.org/gems/tabulo
-[Documentation]: http://www.rubydoc.info/gems/tabulo/2.6.3
-[Build Status]: https://travis-ci.org/matt-harvey/tabulo
-[Coverage Status]: https://coveralls.io/r/matt-harvey/tabulo
+[Documentation]: http://www.rubydoc.info/gems/tabulo/2.7.0
+[Build Status]: https://github.com/matt-harvey/tabulo/actions/workflows/tests.yml
+[Coverage Status]: https://coveralls.io/github/matt-harvey/tabulo
 [Code Climate]: https://codeclimate.com/github/matt-harvey/tabulo
 [Awesome Ruby]: https://github.com/markets/awesome-ruby#cli-utilities
 
 [GV img]: https://img.shields.io/gem/v/tabulo.svg
-[DC img]: https://img.shields.io/badge/documentation-v2.6.3-blue.svg
-[BS img]: https://img.shields.io/travis/matt-harvey/tabulo.svg
+[DC img]: https://img.shields.io/badge/documentation-v2.7.0-blue.svg
+[BS img]: https://github.com/matt-harvey/tabulo/actions/workflows/tests.yml/badge.svg
 [CS img]: https://img.shields.io/coveralls/matt-harvey/tabulo.svg
 [CC img]: https://codeclimate.com/github/matt-harvey/tabulo/badges/gpa.svg
 [AR img]: https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg

data/VERSION

@@ -1 +1 @@
-2.6.3
+2.7.0

data/lib/tabulo/cell.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 require "unicode/display_width"
 
 module Tabulo
@@ -19,6 +21,7 @@ module Tabulo
       styler:,
       truncation_indicator:,
       value:,
+      wrap_preserve:,
       width:)
 
       @alignment = alignment
@@ -30,6 +33,7 @@ module Tabulo
       @styler = styler
       @truncation_indicator = truncation_indicator
       @value = value
+      @wrap_preserve = wrap_preserve
       @width = width
     end
 
@@ -100,30 +104,86 @@ module Tabulo
     end
 
     def calculate_subcells
-      line_index = 0
-      formatted_content.split(Util::NEWLINE, -1).flat_map do |substr|
-        subsubcells, subsubcell, subsubcell_width = [], String.new(""), 0
-
-        substr.scan(/\X/).each do |grapheme_cluster|
-          grapheme_cluster_width = Unicode::DisplayWidth.of(grapheme_cluster)
-          if subsubcell_width + grapheme_cluster_width > @width
-            subsubcells << style_and_align_cell_content(subsubcell, line_index)
-            subsubcell_width = 0
-            subsubcell.clear
-            line_index += 1
+      case @wrap_preserve
+      when :rune
+        line_index = 0
+        formatted_content.split(Util::NEWLINE, -1).flat_map do |substr|
+          subsubcells, subsubcell, subsubcell_width = [], String.new(""), 0
+
+          substr.scan(/\X/).each do |rune|
+            rune_width = Unicode::DisplayWidth.of(rune)
+            if subsubcell_width + rune_width > @width
+              subsubcells << style_and_align_cell_content(subsubcell, line_index)
+              subsubcell_width = 0
+              subsubcell.clear
+              line_index += 1
+            end
+
+            subsubcell << rune
+            subsubcell_width += rune_width
           end
 
-          subsubcell << grapheme_cluster
-          subsubcell_width += grapheme_cluster_width
+          subsubcells << style_and_align_cell_content(subsubcell, line_index)
+          line_index += 1
+          subsubcells
         end
+      when :word
+        line_index = 0
+        formatted_content.split(Util::NEWLINE, -1).flat_map do |substr|
+          subsubcells, subsubcell, subsubcell_width = [], String.new(""), 0
+
+          substr.split(/(?<= |\-|\—|\–⁠)\b/).each do |word|
+            # Each word looks like "this " or like "this-".
+            word_width = Unicode::DisplayWidth.of(word)
+            combined_width = subsubcell_width + word_width
+            if combined_width - 1 == @width && word[-1] == " "
+              # do nothing, as we're on the final word of the line and
+              # the space at the end will be chopped off.
+            elsif combined_width > @width
+              content = style_and_align_cell_content(subsubcell, line_index)
+              if content.strip.length != 0
+                subsubcells << content
+                subsubcell_width = 0
+                subsubcell.clear
+                line_index += 1
+              end
+            end
+
+            if word_width >= @width
+              word.scan(/\X/).each do |rune|
+                rune_width = Unicode::DisplayWidth.of(rune)
+                if subsubcell_width + rune_width > @width
+                  if rune != " "
+                    content = style_and_align_cell_content(subsubcell, line_index)
+                    subsubcells << content
+                    subsubcell_width = 0
+                    subsubcell.clear
+                    line_index += 1
+                  end
+                end
+
+                subsubcell << rune
+                subsubcell_width += rune_width
+              end
+            else
+              subsubcell << word
+              subsubcell_width += word_width
+            end
+          end
 
-        subsubcells << style_and_align_cell_content(subsubcell, line_index)
-        line_index += 1
-        subsubcells
+          content = style_and_align_cell_content(subsubcell, line_index)
+          subsubcells << content
+          line_index += 1
+          subsubcells
+        end
       end
     end
 
     def style_and_align_cell_content(content, line_index)
+      if @wrap_preserve == :word
+        content.strip!
+      end
+
       padding = Util.max(@width - Unicode::DisplayWidth.of(content), 0)
       left_padding, right_padding =
         case real_alignment

data/lib/tabulo/column.rb

@@ -22,6 +22,7 @@ module Tabulo
       right_padding:,
       styler:,
       truncation_indicator:,
+      wrap_preserve:,
       width:)
 
       @align_body = align_body
@@ -50,6 +51,7 @@ module Tabulo
       @padding_character = padding_character
       @styler = styler || -> (_, s) { s }
       @truncation_indicator = truncation_indicator
+      @wrap_preserve = wrap_preserve
       @width = width
     end
 
@@ -67,6 +69,7 @@ module Tabulo
         styler: @header_styler,
         truncation_indicator: @truncation_indicator,
         value: @header,
+        wrap_preserve: @wrap_preserve,
         width: @width,
       )
     end
@@ -85,6 +88,7 @@ module Tabulo
         styler: @styler,
         truncation_indicator: @truncation_indicator,
         value: body_cell_value(source, row_index: row_index, column_index: column_index),
+        wrap_preserve: @wrap_preserve,
         width: @width,
       )
     end

data/lib/tabulo/table.rb

@@ -124,6 +124,16 @@ module Tabulo
     #   cell's content has been truncated. If omitted or passed <tt>nil</tt>,
     #   defaults to {DEFAULT_TRUNCATION_INDICATOR}. If passed something other than <tt>nil</tt> or
     #   a single-character String, raises {InvalidTruncationIndicatorError}.
+    # @param [Symbol] wrap_preserve Specifies what unit of text the wrapping mechanism will try to
+    #     preserve intact when wrapping column content when the column width is reached.
+    #   * If passed `:rune` (the default), then it will wrap at the "character" level (approximately
+    #     speaking, the Unicode grapheme cluster level). This means the maximum number of what
+    #     readers usually think of as "characters" will be fit on each line, within the column's allocated
+    #     width, before contininuing to a new line, even if it means splitting a word in the middle.
+    #   * If passed `:word`, then it will wrap in such a way as to avoid splitting words, where
+    #     "words" are defined as units of text separated by spaces or dashes (hyphens, m-dashes and
+    #     n-dashes). Whitespace will be used to pad lines as required. Already-hyphenated may will be split
+    #     at the hyphen, however hyphens will not be inserted in non-hyphenated words.
     # @param [nil, Integer] wrap_body_cells_to Controls wrapping behaviour for table cells (excluding
     #   headers), if their content is longer than the column's fixed width. If passed <tt>nil</tt>, content will
     #   be wrapped for as many rows as required to accommodate it. If passed an Integer N (> 0), content will be
@@ -141,7 +151,7 @@ module Tabulo
     def initialize(sources, *columns, align_body: :auto, align_header: :center, align_title: :center,
       border: nil, border_styler: nil, column_padding: nil, column_width: nil, formatter: :to_s.to_proc,
       header_frequency: :start, header_styler: nil, row_divider_frequency: nil, styler: nil,
-      title: nil, title_styler: nil, truncation_indicator: nil, wrap_body_cells_to: nil,
+      title: nil, title_styler: nil, truncation_indicator: nil, wrap_preserve: :rune, wrap_body_cells_to: nil,
       wrap_header_cells_to: nil)
 
       @sources = sources
@@ -167,6 +177,7 @@ module Tabulo
       @title_styler = title_styler
       @truncation_indicator = validate_character(truncation_indicator,
         DEFAULT_TRUNCATION_INDICATOR, InvalidTruncationIndicatorError, "truncation indicator")
+      @wrap_preserve = wrap_preserve
       @wrap_body_cells_to = wrap_body_cells_to
       @wrap_header_cells_to = wrap_header_cells_to
 
@@ -291,6 +302,11 @@ module Tabulo
     # @param [Integer] width Specifies the width of the column, excluding padding. If
     #   nil, then the column will take the width provided by the `column_width` param
     #   with which the Table was initialized.
+    # @param [Symbol] wrap_preserve Specifies how to wrap column content when the column width is reached.
+    #   * If passed `nil`, or not provided, then the value passed to the `wrap_preserve` param of
+    #     {#initialize} will be used.
+    #   * If passed `rune` or word, then the option passed to {#initialize} will be overridden for
+    #     this column. See the documentation under {#initialize} for the behaviour of each option.
     # @param [#to_proc] extractor A block or other callable that will be passed each of the {Table}
     #   sources to determine the value in each cell of this column.
     #   * If this is not provided, then the column label will be treated as a method to be called on
@@ -305,7 +321,7 @@ module Tabulo
     #   Table. (This is case-sensitive, but is insensitive to whether a String or Symbol is passed
     #   to the label parameter.)
     def add_column(label, align_body: nil, align_header: nil, before: nil, formatter: nil,
-      header: nil, header_styler: nil, padding: nil, styler: nil, width: nil, &extractor)
+      header: nil, header_styler: nil, padding: nil, styler: nil, width: nil, wrap_preserve: nil, &extractor)
 
       column_label = normalize_column_label(label)
 
@@ -333,6 +349,7 @@ module Tabulo
         right_padding: right_padding,
         styler: styler || @styler,
         truncation_indicator: @truncation_indicator,
+        wrap_preserve: wrap_preserve || @wrap_preserve,
         width: width || @column_width,
       )
 
@@ -651,7 +668,8 @@ module Tabulo
         styler: styler,
         truncation_indicator: @truncation_indicator,
         value: @title,
-        width: title_cell_width
+        width: title_cell_width,
+        wrap_preserve: @wrap_preserve,
       )
       cells = [title_cell]
       max_cell_height = cells.map(&:height).max

data/lib/tabulo/version.rb

@@ -1,3 +1,3 @@
 module Tabulo
-  VERSION = "2.6.3"
+  VERSION = "2.7.0"
 end

data/tabulo.gemspec

@@ -35,7 +35,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake", "~> 12.3.3"
   spec.add_development_dependency "rspec", "~> 3.9"
   spec.add_development_dependency "simplecov"
-  spec.add_development_dependency "coveralls"
+  spec.add_development_dependency "simplecov-lcov"
   spec.add_development_dependency "yard"
   spec.add_development_dependency "redcarpet"
   spec.add_development_dependency "github-markup"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tabulo
 version: !ruby/object:Gem::Version
-  version: 2.6.3
+  version: 2.7.0
 platform: ruby
 authors:
 - Matthew Harvey
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-05-30 00:00:00.000000000 Z
+date: 2021-07-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tty-screen
@@ -95,7 +95,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: coveralls
+  name: simplecov-lcov
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -172,10 +172,11 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".ackrc"
+- ".github/workflows/tests.yml"
 - ".gitignore"
 - ".rdoc_options"
 - ".rspec"
-- ".travis.yml"
+- ".simplecov"
 - ".yardopts"
 - CHANGELOG.md
 - Gemfile

data/.travis.yml

@@ -1,11 +0,0 @@
-sudo: false
-language: ruby
-rvm:
-  - 2.1.10
-  - 2.2.10
-  - 2.3.8
-  - 2.4.10
-  - 2.5.9
-  - 2.6.7
-  - 2.7.3
-  - 3.0.1