tabulo 2.6.1 → 2.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bf2b89914117264e5f213553c792d1456d4f5d99ae8afac565ff1dbc069400b
-  data.tar.gz: 6220df7007ae352c400291101f6308f99ad063fe98c5820820da599f674d4a43
+  metadata.gz: 63054578d0f667075a8e2888d3fc0a2572ec9b8a93e3f74468f058613a7c2f19
+  data.tar.gz: 3d0b8bad1b9ad7fa2949037ec6de683f7b43c7ecc73ca02c53bbb14f926139fe
 SHA512:
-  metadata.gz: 13228bb55890713cb9483f18d55339dcf7393aff65a7f91383eb9a5d7dce03acd968e09e883ae3f72088e4d543d1bdc962cb38a0c9444cdd1a93482c55f9c354
-  data.tar.gz: e865337603240b4b8456f5b2b7bbb64f660b18acfc4caf0318ef9869f58070801da24bbdd7de740133a6ef386d5c6c02ee198098605fb7a13acd60547bbdb04e
+  metadata.gz: d8626993288417bdd75b581819ea4ef9ef79bfcdfb5d18e7469ac2699e303096405f6155b690a289f5bbc27a8235cc80fb4cb0ad8e62146c664f198fefce9a7e
+  data.tar.gz: 9a306fb542677778f3e6998ee83352f87802bf6d07b422846b61d1fe42acdd8b40a914daa87a10e5abe2f84e6d4b8cd5ddc5711e49d9b5d066113b167b4cf4a9

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.8',
+          '2.7.4',
+          '3.0.2',
+        ]
+    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/.gitignore

@@ -10,3 +10,4 @@
 **/.*.swp
 coverage
 gh-md-toc
+.ruby-version

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+### v2.7.1
+
+* Dependency version upgrades
+* Minor documentation improvements and tweaks
+
+### 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

data/README.md

@@ -2,9 +2,8 @@
 
 [![Gem Version][GV img]][Gem Version]
 [![Documentation][DC img]][Documentation]
-[![Coverage Status][CS img]][Coverage Status]
 [![Build Status][BS img]][Build Status]
-[![Code Climate][CC img]][Code Climate]
+[![Coverage Status][CS img]][Coverage Status]
 [![Awesome][AR img]][Awesome Ruby]
 
 Tabulo is a Ruby library for generating plain text tables (also known as “terminal tables”
@@ -16,19 +15,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 +36,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 +62,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
@@ -84,6 +84,7 @@ Tabulo has also been ported to Crystal (with some modifications): see [Tablo](ht
         * [Full API](#quick-api)
         * [Column labels _vs_ headers](#labels-headers)
         * [Positioning columns](#column-positioning)
+        * [Extracting column content from a hash or array](#from-arrays-hashes)
      * [Removing columns](#removing-columns)
      * [Adding a title](#title)
      * [Cell alignment](#cell-alignment)
@@ -92,6 +93,7 @@ Tabulo has also been ported to Crystal (with some modifications): see [Tablo](ht
         * [Automating column widths](#automating-column-widths)
         * [Configuring padding](#configuring-padding)
         * [Overflow handling](#overflow-handling)
+        * [Wrapping at word boundaries](#preserve-words)
         * [Manual cell wrapping](#manual-wrapping)
      * [Formatting cell values](#formatting-cell-values)
      * [Colours and other styling](#colours-and-styling)
@@ -280,6 +282,69 @@ table.add_column(:even?, before: :odd?)
 +--------------+--------------+--------------+
 ```
 
+<a name="from-arrays-hashes"></a>
+#### Extracting column content from a hash or array [&#x2191;](#contents)
+
+Sometimes the data source for the table may be a collection of hashes or arrays. For example:
+
+```ruby
+data = [
+  { english: "hello", portuguese: "bom dia" },
+  { english: "goodbye", portuguese: "adeus" },
+]
+```
+
+or
+
+```ruby
+data = [
+  ["hello", "bom dia"],
+  ["goodbye", "adeus"],
+]
+```
+
+To tabulate such a collection, simply use the same mechanism as described above, passing a block to
+the `add_column` method to tell Tabulo how to extract the data for each column from a row. For
+example, to tabulate the first example above, you could do something like this:
+
+```ruby
+table = Tabulo::Table.new(data) do |t|
+  t.add_column("English") { |h| h[:english] }
+  t.add_column("Portuguese") { |h| h[:portuguese] }
+end
+
+puts table
+```
+
+For the second example, you could do the following:
+
+```ruby
+table = Tabulo::Table.new(data) do |t|
+  t.add_column("English") { |a| a[0] }
+  t.add_column("Portuguese") { |a| a[1] }
+end
+
+puts table
+```
+
+In both cases, the output will be as follows:
+
+```
++--------------+--------------+
+|    English   |  Portuguese  |
++--------------+--------------+
+| hello        | bom dia      |
+| goodbye      | adeus        |
++--------------+--------------+
+```
+
+If you have previously used other terminal tabulation libraries, you may be accustomed to being _required_
+to place your data into an array of hashes or arrays before you can tabulate them. Tabulo, however,
+offers an API that is more general and flexible than this; your data source can be _any_
+enumerable collection (not just an array), and each item in that collection can be _any_ object (not
+necessarily an array or a hash). However, as shown above, it is still straightforward to tabulate an
+array of hashes or arrays, if your data source happens to take that form.
+
 <a name="removing-columns"></a>
 ### Removing columns [&#x2191;](#contents)
 
@@ -596,11 +661,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|
@@ -622,6 +727,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)
 
@@ -683,7 +793,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.1/Tabulo/CellData.html)
+it&mdash;see the [documentation](https://www.rubydoc.info/gems/tabulo/2.7.1/Tabulo/CellData.html)
 for details.
 
 <a name="colours-and-styling"></a>
@@ -729,7 +839,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.1/Tabulo/Table#add_column-instance_method) for details.
+[documentation](https://www.rubydoc.info/gems/tabulo/2.7.1/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
@@ -749,7 +859,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.1/Tabulo/Table#add_column-instance_method)
+[documentation](https://www.rubydoc.info/gems/tabulo/2.7.1/Tabulo/Table#add_column-instance_method)
 for details.
 
 <a name="styling-title"></a>
@@ -763,7 +873,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.1/Tabulo/Table#initialize-instance_method)
+[documentation](https://www.rubydoc.info/gems/tabulo/2.7.1/Tabulo/Table#initialize-instance_method)
 for details.
 
 <a name="styling-borders"></a>
@@ -958,7 +1068,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.1/Tabulo/Table#transpose-instance_method).
+[documentation](https://www.rubydoc.info/gems/tabulo/2.7.1/Tabulo/Table#transpose-instance_method).
 
 <a name="borders"></a>
 ### Configuring borders [&#x2191;](#contents)
@@ -1014,6 +1124,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:
 
 ```
@@ -1103,6 +1217,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:
 
@@ -1156,16 +1274,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>
@@ -1341,15 +1459,13 @@ 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.1
-[Build Status]: https://travis-ci.org/matt-harvey/tabulo
-[Coverage Status]: https://coveralls.io/r/matt-harvey/tabulo
-[Code Climate]: https://codeclimate.com/github/matt-harvey/tabulo
+[Documentation]: http://www.rubydoc.info/gems/tabulo/2.7.1
+[Build Status]: https://github.com/matt-harvey/tabulo/actions/workflows/tests.yml
+[Coverage Status]: https://coveralls.io/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.1-blue.svg
-[BS img]: https://img.shields.io/travis/matt-harvey/tabulo.svg
+[DC img]: https://img.shields.io/badge/documentation-v2.7.1-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.1
+2.7.1

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.1"
+  VERSION = "2.7.1"
 end

data/tabulo.gemspec

@@ -29,13 +29,13 @@ Gem::Specification.new do |spec|
   }
 
   spec.add_runtime_dependency "tty-screen", "0.8.1"
-  spec.add_runtime_dependency "unicode-display_width", "1.7.0"
+  spec.add_runtime_dependency "unicode-display_width", "2.1.0"
 
   spec.add_development_dependency "bundler"
   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.1
+  version: 2.7.1
 platform: ruby
 authors:
 - Matthew Harvey
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-07-24 00:00:00.000000000 Z
+date: 2021-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tty-screen
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.7.0
+        version: 2.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.7.0
+        version: 2.1.0
 - !ruby/object:Gem::Dependency
   name: bundler
   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
@@ -220,7 +221,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.2.29
 signing_key: 
 specification_version: 4
 summary: Terminal table generator

data/.travis.yml

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