tabulo 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 758e3d9a0c11ce15ef23bcfc38c6e1e5dcf1e818
-  data.tar.gz: 5ffb67d92e38efec2b4eec90beea8ea1a047fb3c
+  metadata.gz: 9b63d694608052e887a021c0c0e0eb4c9e77512a
+  data.tar.gz: e2781dc44f766676c25fa2148a867e14cf49795f
 SHA512:
-  metadata.gz: e6ea3bb9c620c39e784949174afe15d028892af72a148159a6cfc1282f07aaf858c265d70fa41ee516c04f55fe1b34e3b21f23b684196adcb488dcf02a6f4335
-  data.tar.gz: f68ca83f4647a7d8f21976ef838248bbbcbd6b4aba21ec6c81087c521e07dc3b8d9f0c4aee59c45c5935107ff4740d72c6c3f70287e94d27d57c3ecb94008305
+  metadata.gz: 33b5af849750ab1ba36c4212b835193d50592f524f7055c3236043f81dcce5b1bffb56c0770651fd9ca5e6c89df935073e4018cbe3029ac1215f7efd6e805e4f
+  data.tar.gz: f9563b27c2a150ea1544e3705c5fbac6c77163e2f23d9187f50310c71ac66a13b2066d04223907707cef698fa3d024112a981edc25245e6f372d2dfc29ab8c2f

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v0.3.0
+
+* Rename Table#header_row to Table#formatted_header
+* Improve documentation, and use Yardoc instead of Tomdoc
+* Remove Tabulo::Column from the publicly documented API.
+
 ## v0.2.2
 
 * Write documentation

data/TODO.md

@@ -1,13 +1,8 @@
 # TODO
 
-* Finish Tomdoc documentation. Link to it at rubydocs from the README. In particular,
-  make it clear which methods are part of the public API and which are internal.
-* Allow the option of a horizontal rule between each row?
 * Consider incorporating a linter / static analysis tool into the build.
 * Raise an ArgumentError for disallowed arguments and options (this is
   a library!)
 * Document :formatter option in README.
 * Allow default column width to be configured at level of Table.
-* Rename Table#header_row to Table#header to avoid confusion as it does not
-  return a Row.
 * Column#initialize should have the same signature as Table#add_column.

data/lib/tabulo/column.rb

@@ -1,48 +1,11 @@
 module Tabulo
 
+  # @!visibility private
   class Column
 
     attr_reader :label, :width
 
-    # Public: Initializes and returns a new Column.
-    #
-    # options - A Hash of options:
-    #
-    #          :label - A Symbol or String being a unique identifier for this Column.
-    #                   If the :extractor option is not also provided, then the :label option
-    #                   should correspond to a method to be called on each item in the table sources
-    #                   to provide the content for this column.
-    #
-    #          :header       - The text to be displayed in the header for this Column.
-    #
-    #          :align_header - Specifies the alignment of the header text. Possible values are
-    #                          <tt>:left</tt>, <tt>:center</tt> (the default) and <tt>right</tt>
-    #
-    #          :align_body   - Specifies how the cell body contents will be aligned. Possible
-    #                          values are <tt>:left</tt>, <tt>:center</tt>, <tt>:right</tt>
-    #                          and <tt>nil</tt>. If <tt>nil</tt> is passed (the default), then
-    #                          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 option.
-    #
-    #          :extractor    - A callable, e.g. a block or lambda, 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 each source item to determine each cell's
-    #                          value.
-    #
-    #          :formatter    - A callable (e.g. a lambda) that will be passed the calculated
-    #                          value of each cell to determine how it should be displayed. This
-    #                          is distinct from the extractor (see below). For
-    #                          example, if the extractor for this column generates a Date, then
-    #                          the formatter might format that Date in a particular way.
-    #                          If no formatter is provided, then <tt>.to_s</tt> will be called on
-    #                          the extracted value of each cell to determine its displayed
-    #                          content.
-    #
-    #          :width        - Specifies the width of the column, not including the single character
-    #                          of padding. The default is given by Table::DEFAULT_COLUMN_WIDTH.
+    # @!visibility private
     def initialize(options)
       @label, @header = options[:label], options[:header]
       @align_header = options[:align_header] || :center
@@ -52,17 +15,17 @@ module Tabulo
       @width = options[:width] || Table::DEFAULT_COLUMN_WIDTH
     end
 
-    # Internal
+    # @!visibility private
     def header_cell
       align_cell_content(@header, @align_header)
     end
 
-    # Internal
+    # @!visibility private
     def horizontal_rule
       Table::HORIZONTAL_RULE_CHARACTER * @width
     end
 
-    # Internal
+    # @!visibility private
     def body_cell(source)
       cell_datum = body_cell_value(source)
       formatted_cell_content = @formatter.call(cell_datum)
@@ -70,14 +33,14 @@ module Tabulo
       align_cell_content(formatted_cell_content, real_alignment)
     end
 
-    # Internal
+    # @!visibility private
     def body_cell_value(source)
       @extractor.call(source)
     end
 
     private
 
-    # Internal
+    # @!visibility private
     def align_cell_content(content, real_alignment)
       padding = [@width - content.length, 0].max
       left_padding, right_padding =
@@ -94,7 +57,7 @@ module Tabulo
       "#{' ' * left_padding}#{content}#{' ' * right_padding}"
     end
 
-    # Internal
+    # @!visibility private
     def infer_alignment(cell_datum)
       case cell_datum
       when Numeric

data/lib/tabulo/row.rb

@@ -3,19 +3,18 @@ module Tabulo
   class Row
     include Enumerable
 
-    # Internal
+    # @!visibility private
     def initialize(table, source, options = { with_header: true })
       @table = table
       @source = source
       @with_header = options[:with_header]
     end
 
-    # Public: Calls the given block once for each cell in the Row, passing that cell as parameter.
-    # Each "cell" is just the calculated value for its column (pre-formatting) for this Row's
+    # Calls the given block once for each cell in the {Row}, passing that cell as parameter.
+    # Each "cell" is just the calculated value for its column (pre-formatting) for this {Row}'s
     # source item.
     #
-    # Examples
-    #
+    # @example
     #   table = Tabulo::Table.new([1, 10], columns: %i(itself even?))
     #   row = table.first
     #   row.each do |cell|
@@ -28,21 +27,20 @@ module Tabulo
       end
     end
 
-    # Public: Returns a String being an "ASCII" graphical representation of the Row, including
-    # any column headers that appear just above it in the Table (depending on where this Row is
-    # in the Table and how the Table was configured with respect to header frequency).
+    # @return a String being an "ASCII" graphical representation of the {Row}, including
+    #   any column headers that appear just above it in the {Table} (depending on where this Row is
+    #   in the {Table} and how the {Table} was configured with respect to header frequency).
     def to_s
       @table.formatted_body_row(@source, with_header: @with_header)
     end
 
-    # Public: Returns a Hash representation of the Row, with Column labels acting
-    # as keys and the calculated cell values (before formatting) providing the values.
-    #
-    # Examples
+    # @return a Hash representation of the {Row}, with column labels acting
+    #   as keys and the calculated cell values (before formatting) providing the values.
     #
+    # @example
     #   table = Tabulo::Table.new([1, 10], columns: %i(itself even?))
     #   row = table.first
-    #   row.to_h  # -> { :itself => 1, :even? => false }
+    #   row.to_h  # => { :itself => 1, :even? => false }
     #
     def to_h
       @table.columns.map(&:label).zip(to_a).to_h

data/lib/tabulo/table.rb

@@ -2,7 +2,7 @@ module Tabulo
 
   # Represents a table primarily intended for "pretty-printing" in a fixed-width font.
   #
-  # A Table is also an Enumerable, of which each element is a Tabulo::Row.
+  # A Table is also an Enumerable, of which each element is a {Row}.
   class Table
     include Enumerable
 
@@ -11,45 +11,29 @@ module Tabulo
     HORIZONTAL_RULE_CHARACTER = "-"
     CORNER_CHARACTER = "+"
 
+    # @!visibility private
     attr_reader :columns
 
-    # Public: Initializes and returns a new Table.
-    #
-    # sources - the underlying Enumerable from which the table will derive its data
-    # options - a Hash of options providing for customization of the Table:
-    #
-    #           :columns  - An Array (default: []) specifying the initial columns (note more can be
-    #                       added later using #add_column). Each element of the Array
-    #                       should be either a Symbol or a Column. If it's a Symbol,
-    #                       it will be used to initialize a Column whose content is
-    #                       created by calling the corresponding method on each
-    #                       element of sources.
-    #
-    #           :header_frequency - Controls the display of Column headers. Possible values:
-    #
-    #                               <tt>:start</tt> (default) - show column headers at top of table only
-    #
-    #                               <tt>nil</tt>              - do not show column headers.
-    #
-    #                               N (a Fixnum > 0)   - show column headers at start, then repeated
-    #                                                    every N rows.
-    #
-    #           :wrap_header_cells_to - Controls wrapping behaviour for header cells if the content
-    #                                   thereof is longer than the Column's fixed width. Possible
-    #                                   values:
-    #
-    #                                   <tt>nil</tt>      - wrap content for as many rows as necessary
-    #
-    #                                   N (a Fixnum > 0) - wrap content for up to N rows and
-    #                                                      truncate thereafter
-    #
-    #           :wrap_body_cells_to   - Controls wrapping behaviour for table cells (excluding
-    #                                   headers). Possible values:
-    #
-    #                                   <tt>nil</tt>       - wrap content for as many rows as necessary
-    #
-    #                                   N (a `Fixnum` > 0) - wrap content for up to N rows and
-    #                                                      truncate thereafter
+    # @param [Enumerable] sources the underlying Enumerable from which the table will derive its data
+    # @param [Hash] options
+    # @option options [Array[Symbol]] :columns ([]) Specifies the initial columns.
+    #   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.
+    # @option options [:start, nil, Fixnum] :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 a Fixnum N (> 0), headers will be shown at the top of the table,
+    #   then repeated every N rows.
+    # @option options [nil, Fixnum] :wrap_header_cells_to (nil) Controls wrapping behaviour for header
+    #   cells if the content thereof is longer than the column's fixed width. If passed <tt>nil</tt> (default),
+    #   content will be wrapped for as many rows as required to accommodate it. If passed a Fixnum N (> 0),
+    #   content will be wrapped up to N rows and then truncated thereafter.
+    # @option options [nil, Fixnum] :wrap_body_cells_to (nil) 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 a Fixnum N (> 0), content will be
+    #   wrapped up to N rows and then truncated thereafter.
+    #
+    # @return [Table] a new Table
     def initialize(sources, options = { })
       opts = {
         columns: [],
@@ -73,62 +57,50 @@ module Tabulo
       yield self if block_given?
     end
 
-    # Public: Initializes a Column and adds it to the Table.
-    #
-    # label   - A Symbol or String being a unique identifier for this column, which by default will
-    #           also be used as the column header text (see also the header option). If the
-    #           extractor argument is not also provided, then the label argument should correspond to
-    #           a method to be called on each item in the table sources to provide the content
-    #           for this column.
-    #
-    # options - A Hash of options providing for customization of the column:
-    #
-    #           :header       - Text to be displayed in the column header. By default the column
-    #                           label will also be used as its header text.
-    #
-    #           :align_header - Specifies how the header text should be aligned. Possible values
-    #                           are <tt>:left</tt>, <tt>:center</tt> and <tt>:right</tt>.
-    #
-    #           :align_body   - Specifies how the cell body contents will be aligned. Possible
-    #                           values are <tt>:left</tt>, <tt>:center</tt>, <tt>:right</tt>
-    #                           and <tt>nil</tt>. If <tt>nil</tt> is passed (the default), then
-    #                           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 option.
-    #
-    #           :width        - Specifies the width of the column, not including the single
-    #                           character of padding. The default is given by
-    #                           Table::DEFAULT_COLUMN_WIDTH.
-    #
-    #           :formatter    - A callable (e.g. a lambda) that will be passed the calculated
-    #                           value of each cell to determine how it should be displayed. This
-    #                           is distinct from the extractor (see below). For
-    #                           example, if the extractor for this column generates a Date, then
-    #                           the formatter might format that Date in a particular way.
-    #                           If no formatter is provided, then <tt>.to_s</tt> will be called on
-    #                           the extracted value of each cell to determine its displayed
-    #                           content.
-    #
-    # extractor - A callable, e.g. a block or lambda, 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 each
-    #             source item to determine each cell's value.
+    # Adds a column to the Table.
+    #
+    # @param [Symbol, String] label A unique identifier for this column, which by default will
+    #   also be used as the column header text (see also the header option). If the
+    #   extractor argument is not also provided, then the label argument should correspond to
+    #   a method to be called on each item in the table sources to provide the content
+    #   for this column.
+    #
+    # @param [Hash] options
+    # @option options [String] :header Text to be displayed in the column header. By default the column
+    #   label will also be used as its header text.
+    # @option options [:left, :center, :right] :align_header (:center) Specifies how the header text
+    #   should be aligned.
+    # @option options [:left, :center, :right, nil] :align_body (nil) Specifies how the cell body contents
+    #   should be aligned. Possible If <tt>nil</tt> is passed, then 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 option.
+    # @option options [Fixnum] :width (8) Specifies the width of the
+    #   column, excluding padding.
+    # @option options [#to_proc] :formatter (:to_s.to_proc) 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 (see below). For example, if the extractor for this column
+    #   generates a Date, then the formatter might format that Date in a particular way.
+    #   If no formatter is provided, then <tt>.to_s</tt> will be called on
+    #   the extracted value of each cell to determine its displayed content.
+    # @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 each source item to determine each cell's value.
     #
     def add_column(label, options = { }, &extractor)
       @columns << make_column(label, extractor: extractor)
     end
 
-    # Public: Returns a String being a graphical "ASCII" representation of the Table, suitable for
-    # display in a fixed-width font.
+    # @return [String] a graphical "ASCII" representation of the Table, suitable for
+    #   display in a fixed-width font.
     def to_s
       join_lines(map(&:to_s))
     end
 
-    # Public: Calls the given block once for each Row in the Table, passing that Row as parameter.
-    #
-    # Examples
+    # Calls the given block once for each {Row} in the Table, passing that {Row} as parameter.
     #
+    # @example
     #   table.each do |row|
     #     puts row
     #   end
@@ -150,18 +122,15 @@ module Tabulo
       end
     end
 
-    # Public: Returns a String being an "ASCII" graphical representation of the Table column
-    # headers.
-    def header_row
+    # @return [String] an "ASCII" graphical representation of the Table column headers.
+    def formatted_header
       format_row(true, &:header_cell)
     end
 
-    # Public: Returns a String being an "ASCII" graphical representation of a horizontal
-    # dividing line suitable for printing at any point in the table.
-    #
-    # Examples
+    # @return [String] an "ASCII" graphical representation of a horizontal
+    #   dividing line suitable for printing at any point in the table.
     #
-    #   # To print a horizontal divider after every row:
+    # @example Print a horizontal divider after every row:
     #   table.each do |row|
     #     puts row
     #     puts table.horizontal_rule
@@ -171,11 +140,11 @@ module Tabulo
       format_row(false, HORIZONTAL_RULE_CHARACTER, CORNER_CHARACTER, &:horizontal_rule)
     end
 
-    # Internal
+    # @!visibility private
     def formatted_body_row(source, options = { with_header: false })
       inner = format_row { |column| column.body_cell(source) }
       if options[:with_header]
-        join_lines([horizontal_rule, header_row, horizontal_rule, inner])
+        join_lines([horizontal_rule, formatted_header, horizontal_rule, inner])
       else
         inner
       end
@@ -183,12 +152,12 @@ module Tabulo
 
     private
 
-    # Internal
+    # @!visibility private
     def body_row(source, options = { with_header: false })
       Row.new(self, source, options)
     end
 
-    # Internal
+    # @!visibility private
     def format_row(header = false, padder = @padding_character, joiner = @joiner)
       # TODO Tidy this up -- or at least comment it.
       cell_stacks = @columns.map do |column|
@@ -219,12 +188,12 @@ module Tabulo
       join_lines(subrows.map { |subrow| "#{joiner}#{subrow.join(joiner)}#{joiner}" })
     end
 
-    # Internal
+    # @!visibility private
     def join_lines(lines)
       lines.join($/)  # join strings with cross-platform newline
     end
 
-    # Internal
+    # @!visibility private
     def make_column(item, options = { })
       case item
       when Column

data/lib/tabulo/version.rb

@@ -1,3 +1,3 @@
 module Tabulo
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 end

data/tabulo.gemspec

@@ -28,4 +28,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "simplecov"
   spec.add_development_dependency "coveralls"
+  spec.add_development_dependency "yard"
+  spec.add_development_dependency "yard-tomdoc"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tabulo
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Matthew Harvey
@@ -80,6 +80,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard-tomdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Enumerable ASCII table
 email:
 - software@matthewharvey.net