tabulo 2.6.0 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9ebd03570ab58159573421765c5fa7260dbaec7a7f573a28b746a2c022dd3c8
-  data.tar.gz: 85c7d4de41779701baceb6db3b0b66b47025f0c3f99a8181f9948306d5f826bb
+  metadata.gz: 632d2d2d3b7d0120410d0afd2b8f1d1b341fd1b6daa7802b15b6f791640d409e
+  data.tar.gz: f5720b528f1c4384118196619ea923b317ec3ff7d374fa87d79808361031e7cc
 SHA512:
-  metadata.gz: eabf52fe920bdbc2867184f3feee0d03e33f79d101d95b4b96095e390786d8443d22c1ab51a10e5a26645c45687f4a36f18c5dc8b35cc72d9162c90c3fb243cc
-  data.tar.gz: d991da9c53378a981623c5622be156f970f37e6f42a3dd22b02d51b11020e1302a5b5209117a4a6b9d74e36c555f73f0a2f67eb2b6ff2dafcf7b14d172eb2e00
+  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,24 @@
 # 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
+
+### v2.6.2
+
+* Ensure line break character sequences are property formatted in output, regardless
+  of whether they are "\r\n", "\r" or "\n".
+
+### v2.6.1
+
+* Update dependency versions
+* Minor documentation improvements
+
 ### v2.6.0
 
 * Add an additional, optional parameter to `styler`, `header_styler` and `title_styler`

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]
 
@@ -16,19 +16,19 @@ or “ASCII tables”). It is both highly configurable and very easy to
 _Quick API:_
 
 ```
-> puts Tabulo::Table.new(User.all, :id, :first_name, :last_name, border: :modern).pack
-┌────┬────────────┬───────────┐
-│ id │ first_name │ last_name │
-├────┼────────────┼───────────┤
-│  1 │ John       │ Citizen   │
-│  2 │ Jane       │ Doe       │
-└────┴────────────┴───────────┘
+> puts Tabulo::Table.new(User.all, :id, :first_name, :last_name).pack
++----+------------+-----------+
+| id | first_name | last_name |
++----+------------+-----------+
+|  1 | John       | Citizen   |
+|  2 | Jane       | Doe       |
++----+------------+-----------+
 ```
 
 _Full API:_
 
 ```
-table = Tabulo::Table.new(User.all, border: :modern) do |t|
+table = Tabulo::Table.new(User.all) do |t|
   t.add_column("ID", &:id)
   t.add_column("First name", &:first_name)
   t.add_column("Last name") { |user| user.last_name.upcase }
@@ -37,12 +37,12 @@ end
 
 ```
 > puts table.pack
-┌────┬────────────┬───────────┐
-│ ID │ First name │ Last name │
-├────┼────────────┼───────────┤
-│  1 │ John       │ CITIZEN   │
-│  2 │ Jane       │ DOE       │
-└────┴────────────┴───────────┘
++----+------------+-----------+
+| ID | First name | Last name |
++----+------------+-----------+
+|  1 | John       | CITIZEN   |
+|  2 | Jane       | DOE       |
++----+------------+-----------+
 ```
 
 <a name="features"></a>
@@ -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, &ldquo;ASCII&rdquo;, and smoothly
@@ -492,14 +493,14 @@ table = Tabulo::Table.new([1, 2, 5], :itself, :even?, :odd?, column_padding: 0)
 ```
 
 ```
-> puts table
-+------------+------------+------------+
-|   itself   |    even?   |    odd?    |
-+------------+------------+------------+
-|           1|    false   |    true    |
-|           2|    true    |    false   |
-|           5|    false   |    true    |
-+------------+------------+------------+
+> puts table.pack
++------+-----+-----+
+|itself|even?| odd?|
++------+-----+-----+
+|     1|false| true|
+|     2| true|false|
+|     5|false| true|
++------+-----+-----+
 ```
 
 Passing an array of _two_ integers to this option configures the left and right padding for each
@@ -510,33 +511,35 @@ table = Tabulo::Table.new([1, 2, 5], :itself, :even?, :odd?, column_padding: [0,
 ```
 
 ```
-> puts table
-+--------------+--------------+--------------+
-|   itself     |    even?     |    odd?      |
-+--------------+--------------+--------------+
-|           1  |    false     |    true      |
-|           2  |    true      |    false     |
-|           5  |    false     |    true      |
-+--------------+--------------+--------------+
+> puts table.pack
++--------+-------+-------+
+|itself  |even?  | odd?  |
++--------+-------+-------+
+|     1  |false  | true  |
+|     2  | true  |false  |
+|     5  |false  | true  |
++--------+-------+-------+
 ```
 
+Note how the padding amount is completely unaffected by the call `pack`.
+
 Padding can also be configured on a column-by-column basis, using the `padding` option when calling
 `add_column`:
 
 ```ruby
 table = Tabulo::Table.new([1, 2, 5], :itself, :even?)
-table.add_column(:odd?, padding: 2)
+table.add_column(:odd?, padding: 3)
 ```
 
 ```
-> puts table
-+--------------+--------------+------------------+
-|    itself    |     even?    |       odd?       |
-+--------------+--------------+------------------+
-|            1 |     false    |       true       |
-|            2 |     true     |       false      |
-|            5 |     false    |       true       |
-+--------------+--------------+------------------+
+> puts table.pack
++--------+-------+-----------+
+| itself | even? |    odd?   |
++--------+-------+-----------+
+|      1 | false |    true   |
+|      2 |  true |   false   |
+|      5 | false |    true   |
++--------+-------+-----------+
 ```
 
 This column-level `padding` setting always overrides any table-level `column_padding` setting, for
@@ -594,11 +597,51 @@ 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)
 
 You can &ldquo;manually&rdquo; wrap the content of a title, header or body cell at a particular
-point, simply by placing a newline character at that point:
+point, simply by placing a newline character, at that point:
 
 ```ruby
 table = Tabulo::Table.new(1..3) do |t|
@@ -620,6 +663,11 @@ end
 +--------------+--------------+--------------+
 ```
 
+Tabulo will treat any of the character combinations `"\n"`, `"\r\n"` or `"\r"` equally, as a line break,
+regardless of the platform it&#8217;s currently being run on. This ensures things are formatted as
+expected if, for example, you are examining content that was produced on another platform from
+the one you&#8217;re running Tabulo on.
+
 <a name="formatting-cell-values"></a>
 ### Formatting cell values [&#x2191;](#contents)
 
@@ -681,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.0/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>
@@ -721,13 +769,13 @@ table.add_column(
 )
 ```
 
-The `styler` option should be passed a callable that takes either two, three or four parameters.
+The `styler` option should be passed a callable that takes either 2, 3 or 4 parameters.
 The first parameter represents the underlying value of the cell (in this case a boolean indicating whether the
 number is even). The second parameter represents the formatted string value of that cell, i.e. the cell
 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.0/Tabulo/CellData.html)
-for details.
+determining how to style it. See the
+[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
@@ -747,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.0/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>
@@ -761,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.0/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>
@@ -956,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.0/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)
@@ -1012,6 +1060,10 @@ This is done using the `border` option passed to `Table.new`. The options are as
 └──────────────┴──────────────┴──────────────┘
 ```
 
+_Note: The unicode characters used for the `:modern` border may not render properly
+when viewing this documentation on some browsers or devices. This doesn&#8217;t reflect any brokenness
+in `tabulo` itself._
+
 `:markdown`&mdash;renders a GitHub flavoured Markdown table:
 
 ```
@@ -1101,6 +1153,10 @@ generally support adding a caption (i.e. title) element to tables.
 ────────────── ────────────── ──────────────
 ```
 
+_Note: The unicode characters used for the `:reduced_modern` border may not render properly
+when viewing this documentation on some browsers or devices. This doesn&#8217;t reflect any brokenness
+in `tabulo` itself._
+
 `:classic`&mdash;reproduces the default behaviour in Tabulo v1; this is like the `:ascii` option,
 but without a bottom border:
 
@@ -1154,16 +1210,16 @@ every Nth row. For example:
 If you want a line before every row, pass `1` to `row_divider_frequency`. For example:
 
 ```
-> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :modern, row_divider_frequency: 1)
-┌──────────────┬──────────────┬──────────────┐
-│    itself    │     even?    │     odd?     │
-├──────────────┼──────────────┼──────────────┤
-│            1 │     false    │     true     │
-├──────────────┼──────────────┼──────────────┤
-│            2 │     true     │     false    │
-├──────────────┼──────────────┼──────────────┤
-│            3 │     false    │     true     │
-└──────────────┴──────────────┴──────────────┘
+> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, row_divider_frequency: 1)
++--------------+--------------+--------------+
+|    itself    |     even?    |     odd?     |
++--------------+--------------+--------------+
+|            1 |     false    |     true     |
++--------------+--------------+--------------+
+|            2 |     true     |     false    |
++--------------+--------------+--------------+
+|            3 |     false    |     true     |
++--------------+--------------+--------------+
 ```
 
 <a name="freezing-a-table"></a>
@@ -1339,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.0
-[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.0-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.0
+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($/, -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

@@ -35,17 +35,17 @@ module Tabulo
     #   be unique. Each element of the Array  will be used to create a column whose content is
     #   created by calling the corresponding method on each element of sources. Note
     #   the {#add_column} method is a much more flexible way to set up columns on the table.
-    # @param [:left, :right, :center, :auto] align_body (:auto) Determines the alignment of body cell
+    # @param [:left, :right, :center, :auto] align_body Determines the alignment of body cell
     #   (i.e. non-header) content within columns in this Table. Can be overridden for individual columns
     #   using the <tt>align_body</tt> option passed to {#add_column}. If passed <tt>:auto</tt>,
     #   alignment is determined by cell content, with numbers aligned right, booleans
     #   center-aligned, and other values left-aligned.
-    # @param [:left, :right, :center] align_header (:center) Determines the alignment of header text
+    # @param [:left, :right, :center] align_header Determines the alignment of header text
     #   for columns in this Table. Can be overridden for individual columns using the
     #   <tt>align_header</tt> option passed to {#add_column}
-    # @param [:left, :right, :center] align_header (:center) Determines the alignment of the table
+    # @param [:left, :right, :center] align_header Determines the alignment of the table
     #   title, if present.
-    # @param [:ascii, :markdown, :modern, :blank, nil] border (nil) Determines the characters used
+    # @param [:ascii, :markdown, :modern, :blank, nil] border Determines the characters used
     #   for the Table border, including both the characters around the outside of table, and the lines drawn
     #   within the table to separate columns from each other and the header row from the Table body.
     #   If <tt>nil</tt>, then the value of {DEFAULT_BORDER} will be used.
@@ -63,7 +63,7 @@ module Tabulo
     #                       borders and intersection characters consisting of whitespace only
     #   - `:classic`        Like `:ascii`, but does not have a horizontal line at the bottom of the
     #                       table. This reproduces the default behaviour in `tabulo` v1.
-    # @param [nil, #to_proc] border_styler (nil) A lambda or other callable object taking
+    # @param [nil, #to_proc] border_styler A lambda or other callable object taking
     #   a single parameter, representing a section of the table's borders (which for this purpose
     #   include any horizontal and vertical lines inside the table), and returning a string.
     #   If passed <tt>nil</tt>, then no additional styling will be applied to borders. If passed a
@@ -72,7 +72,7 @@ module Tabulo
     #   <tt>border_styler</tt> is not taken into consideration by the internal table rendering calculations
     #   Thus it can be used to apply ANSI escape codes to border characters, to colour the borders
     #   for example, without breaking the table formatting.
-    # @param [nil, Integer, Array] column_padding (1) Determines the amount of blank space with which to pad
+    # @param [nil, Integer, Array] column_padding Determines the amount of blank space with which to pad
     #   either side of each column. If passed an Integer, then the given amount of padding is
     #   applied to each side of each column. If passed a two-element Array, then the first element of the
     #   Array indicates the amount of padding to apply to the left of each column, and the second
@@ -80,26 +80,26 @@ module Tabulo
     #   individual columns using the `padding` option of {#add_column}.
     # @param [Integer, nil] column_width The default column width for columns in this
     #   table, not excluding padding. If <tt>nil</tt>, then {DEFAULT_COLUMN_WIDTH} will be used.
-    # @param [nil, #to_proc] formatter (:to_s.to_proc) The default formatter for columns in this
+    # @param [nil, #to_proc] formatter The default formatter for columns in this
     #   table. See `formatter` option of {#add_column} for details.
     # @param [:start, nil, Integer] header_frequency (:start) Controls the display of column headers.
     #   If passed <tt>:start</tt>, headers will be shown at the top of the table only. If passed <tt>nil</tt>,
     #   headers will not be shown. If passed an Integer N (> 0), headers will be shown at the top of the table,
     #   then repeated every N rows.
-    # @param [nil, #to_proc] header_styler (nil) The default header styler for columns in this
+    # @param [nil, #to_proc] header_styler The default header styler for columns in this
     #   table. See `header_styler` option of {#add_column} for details.
-    # @param [nil, Integer] row_divider_frequency (nil) Controls the display of horizontal row dividers within
+    # @param [nil, Integer] row_divider_frequency Controls the display of horizontal row dividers within
     #   the table body. If passed <tt>nil</tt>, dividers will not be shown. If passed an Integer N (> 0),
     #   dividers will be shown after every N rows. The characters used to form the dividers are
     #   determined by the `border` option, and are the same as those used to form the bottom edge of the
     #   header row.
-    # @param [nil, #to_proc] styler (nil) The default styler for columns in this table. See `styler`
+    # @param [nil, #to_proc] styler The default styler for columns in this table. See `styler`
     #   option of {#add_column} for details.
-    # @param [nil, String] title (nil) If passed a String, will arrange for a title to be shown at the top
+    # @param [nil, String] title If passed a String, will arrange for a title to be shown at the top
     #   of the table. Note: If the `border` option is set to `:markdown`, adding a title to the table
     #   will cause it to cease being valid Markdown when rendered, since Markdown engines do not generally
     #   support adding a caption element (i.e. title) to tables.
-    # @param [nil, #to_proc] title_styler (nil) A lambda or other callable object that will
+    # @param [nil, #to_proc] title_styler A lambda or other callable object that will
     #   determine the colors or other styling applied to the table title. Can be passed
     #   <tt>nil</tt>, or can be passed a callable that takes either 1 or 2 parametes:
     #   * If passed <tt>nil</tt>, then no additional styling will be applied to the title.
@@ -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
 
@@ -184,24 +195,24 @@ module Tabulo
     #   a method to be called on each item in the table sources to provide the content
     #   for this column. If a String is passed as the label, then it will be converted to
     #   a Symbol for the purpose of serving as this label.
-    # @param [:left, :center, :right, :auto, nil] align_body (nil) Specifies how the cell body contents
+    # @param [:left, :center, :right, :auto, nil] align_body Specifies how the cell body contents
     #   should be aligned. If <tt>nil</tt> is passed, then the alignment is determined
     #   by the Table-level setting passed to the <tt>align_body</tt> option on Table initialization
     #   (which itself defaults to <tt>:auto</tt>). Otherwise this option determines the alignment of
     #   this column. If <tt>:auto</tt> is passed, the alignment is determined by the type of the cell
     #   value, with numbers aligned right, booleans center-aligned, and other values left-aligned.
     #   Note header text alignment is configured separately using the :align_header param.
-    # @param [:left, :center, :right, nil] align_header (nil) Specifies how the header text
+    # @param [:left, :center, :right, nil] align_header Specifies how the header text
     #   should be aligned. If <tt>nil</tt> is passed, then the alignment is determined
     #   by the Table-level setting passed to the <tt>align_header</tt> (which itself defaults
     #   to <tt>:center</tt>). Otherwise, this option determines the alignment of the header
     #   content for this column.
-    # @param [Symbol, String, Integer, nil] before (nil) The label of the column before (i.e. to
+    # @param [Symbol, String, Integer, nil] before The label of the column before (i.e. to
     #   the left of) which the new column should inserted. If <tt>nil</tt> is passed, it will be
     #   inserted after all other columns. If there is no column with the given label, then an
     #   {InvalidColumnLabelError} will be raised. A non-Integer labelled column can be identified
     #   in either String or Symbol form for this purpose.
-    # @param [#to_proc] formatter (nil) A lambda or other callable object that
+    # @param [#to_proc] formatter A lambda or other callable object that
     #   will be passed the calculated value of each cell to determine how it should be displayed. This
     #   is distinct from the extractor and the styler (see below).
     #   For example, if the extractor for this column generates a Date, then the formatter might format
@@ -219,7 +230,7 @@ module Tabulo
     #     whether the {Cell} is an odd- or even-numbered {Row}, to arrange for different formatting
     #     to be applied to alternating rows.
     #     See the documentation for {CellData} for more.
-    # @param [nil, #to_s] header (nil) Text to be displayed in the column header. If passed nil,
+    # @param [nil, #to_s] header Text to be displayed in the column header. If passed nil,
     #   the column's label will also be used as its header text.
     # @param [nil, #to_proc] header_styler (nil) A lambda or other callable object that will
     #   determine the colors or other styling applied to the header content. Can be passed
@@ -249,14 +260,14 @@ module Tabulo
     #
     #   Note that if the header content is truncated, then any <tt>header_styler</tt> will be applied to the
     #   truncation indicator character as well as to the truncated content.
-    # @param [nil, Integer, Array] padding (nil) Determines the amount of blank space with which to
+    # @param [nil, Integer, Array] padding Determines the amount of blank space with which to
     #   pad either side of the column. If passed nil, then the `column_padding` setting of the
     #   {Table} will determine the column's padding. (See {#initialize}.) Otherwise, this option
     #   overrides, for this column, the `column_padding` that was set at the table level: if passed an Integer,
     #   then the given amount of padding is applied to either side of the column; or if passed a two-element Array,
     #   then the first element of the Array indicates the amount of padding to apply to the left of the column,
     #   and the second element indicates the amount to apply to the right.
-    # @param [nil, #to_proc] styler (nil) A lambda or other callable object that will determine
+    # @param [nil, #to_proc] styler A lambda or other callable object that will determine
     #   the colors or other styling applied to the formatted value of the cell. Can be passed
     #   <tt>nil</tt>, or can be passed a callable that takes either 2 or 3 parameters:
     #   * If passed <tt>nil</tt>, then no additional styling will be applied to the cell content
@@ -288,9 +299,14 @@ module Tabulo
     #
     #   Note that if the content of a cell is truncated, then the whatever styling is applied by the
     #   <tt>styler</tt> to the cell content will also be applied to the truncation indicator character.
-    # @param [Integer] width (nil) Specifies the width of the column, excluding padding. If
+    # @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,
       )
 
@@ -412,7 +429,7 @@ module Tabulo
     # Produce a horizontal dividing line suitable for printing at the top, bottom or middle
     # of the table.
     #
-    # @param [:top, :middle, :bottom, :title_top, :title_bottom] position (:bottom)
+    # @param [:top, :middle, :bottom, :title_top, :title_bottom] position
     #   Specifies the position for which the resulting horizontal dividing line is intended to
     #   be printed. This determines the border characters that are used to construct the line.
     #   The `:title_top` and `:title_bottom` options are used internally for adding borders
@@ -451,7 +468,7 @@ module Tabulo
     # is called. If the source Enumerable changes between that point, and the point when
     # the Table is printed, then columns will *not* be resized yet again on printing.
     #
-    # @param [nil, Numeric] max_table_width (:auto) With no args, or if passed <tt>:auto</tt>,
+    # @param [nil, Numeric] max_table_width With no args, or if passed <tt>:auto</tt>,
     #   stops the total table width (including padding and borders) from expanding beyond the
     #   bounds of the terminal screen.
     #   If passed <tt>nil</tt>, the table width will not be capped.
@@ -523,13 +540,13 @@ module Tabulo
     #   new Table, which contains the names of "fields" (corresponding to the original Table's
     #   column headings). If this is not provided, then by default this column will be made just
     #   wide enough to accommodate its contents.
-    # @option opts [String] :field_names_header ("") By default the left-most column will have a
+    # @option opts [String] :field_names_header By default the left-most column will have a
     #   blank header; but this can be overridden by passing a String to this option.
-    # @option opts [:left, :center, :right] :field_names_header_alignment (:right) Specifies how the
+    # @option opts [:left, :center, :right] :field_names_header_alignment Specifies how the
     #   header text of the left-most column (if it has header text) should be aligned.
-    # @option opts [:left, :center, :right] :field_names_body_alignment (:right) Specifies how the
+    # @option opts [:left, :center, :right] :field_names_body_alignment Specifies how the
     #   body text of the left-most column should be aligned.
-    # @option opts [#to_proc] :headers (:to_s.to_proc) A lambda or other callable object that
+    # @option opts [#to_proc] :headers A lambda or other callable object that
     #   will be passed in turn each of the elements of the current Table's <tt>sources</tt>
     #   Enumerable, to determine the text to be displayed in the header of each column of the
     #   new Table (other than the left-most column's header, which is determined as described
@@ -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/util.rb

@@ -3,6 +3,8 @@ module Tabulo
   # @!visibility private
   module Util
 
+    NEWLINE = /\r\n|\n|\r/
+
     # @!visibility private
     def self.condense_lines(lines)
       join_lines(lines.reject(&:empty?))
@@ -34,7 +36,7 @@ module Tabulo
     # @return [Integer] the length of the longest segment of str when split by newlines
     def self.wrapped_width(str)
       return 0 if str.empty?
-      segments = str.split($/)
+      segments = str.split(NEWLINE)
       segments.inject(1) do |longest_length_so_far, segment|
         Util.max(longest_length_so_far, Unicode::DisplayWidth.of(segment))
       end

data/lib/tabulo/version.rb

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

data/tabulo.gemspec

@@ -28,14 +28,14 @@ Gem::Specification.new do |spec|
     "changelog_uri"   => "https://raw.githubusercontent.com/matt-harvey/tabulo/master/CHANGELOG.md"
   }
 
-  spec.add_runtime_dependency "tty-screen", "0.7.1"
-  spec.add_runtime_dependency "unicode-display_width", "1.7.0"
+  spec.add_runtime_dependency "tty-screen", "0.8.1"
+  spec.add_runtime_dependency "unicode-display_width", "2.0.0"
 
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "rake", "~> 12.3.3"
-  spec.add_development_dependency "rspec", "~> 3.0"
+  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.0
+  version: 2.7.0
 platform: ruby
 authors:
 - Matthew Harvey
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-05-17 00:00:00.000000000 Z
+date: 2021-07-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tty-screen
@@ -16,28 +16,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.7.1
+        version: 0.8.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.7.1
+        version: 0.8.1
 - !ruby/object:Gem::Dependency
   name: unicode-display_width
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.7.0
+        version: 2.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.7.0
+        version: 2.0.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -72,14 +72,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.9'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -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
@@ -205,7 +206,7 @@ licenses:
 metadata:
   source_code_uri: https://github.com/matt-harvey/tabulo
   changelog_uri: https://raw.githubusercontent.com/matt-harvey/tabulo/master/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -221,7 +222,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.1.2
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Terminal table generator
 test_files: []

data/.travis.yml

@@ -1,10 +0,0 @@
-sudo: false
-language: ruby
-rvm:
-  - 2.1.10
-  - 2.2.10
-  - 2.3.8
-  - 2.4.9
-  - 2.5.8
-  - 2.6.6
-  - 2.7.1