tabulo 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1dc99325b75930d06ef7865ccf9cf88149040598
-  data.tar.gz: 1fbcea2102de94f56ba29d7d763db7b4e164fd10
+  metadata.gz: 758e3d9a0c11ce15ef23bcfc38c6e1e5dcf1e818
+  data.tar.gz: 5ffb67d92e38efec2b4eec90beea8ea1a047fb3c
 SHA512:
-  metadata.gz: b106d3d9c33e003bba7ad38065c54ba25a7f348d58bd20b5508dd512d6fb0a0600f89ba7c4a5f8239736ff2add5a490ae0d7f6bf5952a21e2fc8a80176ea2091
-  data.tar.gz: f50e7092a449944c3bff02fe8ee5a477bb94b3b5ef80232f12aa1ec4a397ed43e47011b8cc45856d847a33616c00dd0ed6e371092479d48ae95808f0a9838843
+  metadata.gz: e6ea3bb9c620c39e784949174afe15d028892af72a148159a6cfc1282f07aaf858c265d70fa41ee516c04f55fe1b34e3b21f23b684196adcb488dcf02a6f4335
+  data.tar.gz: f68ca83f4647a7d8f21976ef838248bbbcbd6b4aba21ec6c81087c521e07dc3b8d9f0c4aee59c45c5935107ff4740d72c6c3f70287e94d27d57c3ecb94008305

data/.rdoc_options

@@ -0,0 +1,23 @@
+--- !ruby/object:RDoc::Options
+encoding: UTF-8
+static_path: []
+rdoc_include:
+- "."
+- "/Users/matthew/Workbench/versioned/linode/tabulo"
+charset: UTF-8
+exclude: 
+hyperlink_all: false
+line_numbers: false
+locale: 
+locale_dir: locale
+locale_name: 
+main_page: 
+markup: tomdoc
+output_decoration: true
+page_dir: 
+show_hash: false
+tab_width: 8
+template_stylesheets: []
+title: 
+visibility: :protected
+webcvs: 

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v0.2.2
+
+* Write documentation
+* Create a TODO file
 
 ## v0.2.1
 

data/README.md

@@ -217,8 +217,6 @@ table = Tabulo::Table.new(1..10, columns: %i(itself even?), header_frequency: 5)
 |       10 |   true   |
 ```
 
-TODO: Write rdocs, and link to them here "for more".
-
 ### Using a Table Enumerator
 
 Because it's an `Enumerable`, a `Tabulo::Table` can also give you an `Enumerator`,
@@ -242,7 +240,7 @@ end.to_enum  # <-- make an Enumerator
 => nil
 ```
 
-Note the used of `.find_each`: we can start printing the table without having to load the entire
+Note the use of `.find_each`: we can start printing the table without having to load the entire
 underlying collection. (The cost of supporting this behaviour is that Tabulo requires us to set
 column widths up front, rather than adapting to the width of the widest value.)
 

data/TODO.md

@@ -0,0 +1,13 @@
+# 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.rb

@@ -2,8 +2,3 @@ require "tabulo/version"
 require "tabulo/table"
 require "tabulo/row"
 require "tabulo/column"
-
-# TODO Document the methods.
-# TODO Tidy the code.
-# TODO Handle newline in output.
-# TODO Allow the option of a horizontal rule between rows.

data/lib/tabulo/column.rb

@@ -4,25 +4,65 @@ module Tabulo
 
     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.
     def initialize(options)
       @label, @header = options[:label], options[:header]
       @align_header = options[:align_header] || :center
       @align_body = options[:align_body]  || nil
       @extractor = options[:extractor] || @label.to_proc
       @formatter = options[:formatter] || :to_s.to_proc
-
-      # TODO Should be able to set these default on a Table-by-Table basis.
       @width = options[:width] || Table::DEFAULT_COLUMN_WIDTH
     end
 
+    # Internal
     def header_cell
       align_cell_content(@header, @align_header)
     end
 
+    # Internal
     def horizontal_rule
       Table::HORIZONTAL_RULE_CHARACTER * @width
     end
 
+    # Internal
     def body_cell(source)
       cell_datum = body_cell_value(source)
       formatted_cell_content = @formatter.call(cell_datum)
@@ -30,12 +70,14 @@ module Tabulo
       align_cell_content(formatted_cell_content, real_alignment)
     end
 
+    # Internal
     def body_cell_value(source)
       @extractor.call(source)
     end
 
     private
 
+    # Internal
     def align_cell_content(content, real_alignment)
       padding = [@width - content.length, 0].max
       left_padding, right_padding =
@@ -52,6 +94,7 @@ module Tabulo
       "#{' ' * left_padding}#{content}#{' ' * right_padding}"
     end
 
+    # Internal
     def infer_alignment(cell_datum)
       case cell_datum
       when Numeric

data/lib/tabulo/row.rb

@@ -3,22 +3,47 @@ module Tabulo
   class Row
     include Enumerable
 
+    # Internal
     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
+    # source item.
+    #
+    # Examples
+    #
+    #   table = Tabulo::Table.new([1, 10], columns: %i(itself even?))
+    #   row = table.first
+    #   row.each do |cell|
+    #     cell        # => 1,      => false
+    #     cell.class  # => Fixnum, => FalseClass
+    #   end
     def each
       @table.columns.each do |column|
         yield column.body_cell_value(@source)
       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).
     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
+    #
+    #   table = Tabulo::Table.new([1, 10], columns: %i(itself even?))
+    #   row = table.first
+    #   row.to_h  # -> { :itself => 1, :even? => false }
+    #
     def to_h
       @table.columns.map(&:label).zip(to_a).to_h
     end

data/lib/tabulo/table.rb

@@ -1,14 +1,55 @@
 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.
   class Table
     include Enumerable
 
     DEFAULT_COLUMN_WIDTH = 8
+
     HORIZONTAL_RULE_CHARACTER = "-"
     CORNER_CHARACTER = "+"
 
     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
     def initialize(sources, options = { })
       opts = {
         columns: [],
@@ -32,14 +73,68 @@ module Tabulo
       yield self if block_given?
     end
 
-    def add_column(label, options = {}, &extractor)
+    # 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.
+    #
+    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.
     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
+    #
+    #   table.each do |row|
+    #     puts row
+    #   end
+    #
+    # Note that when printed, the first row will visually include the headers (assuming these
+    # were not disabled when the Table was initialized).
     def each
       @sources.each_with_index do |source, index|
         include_header =
@@ -55,14 +150,28 @@ module Tabulo
       end
     end
 
+    # Public: Returns a String being an "ASCII" graphical representation of the Table column
+    # headers.
     def header_row
       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
+    #
+    #   # To print a horizontal divider after every row:
+    #   table.each do |row|
+    #     puts row
+    #     puts table.horizontal_rule
+    #   end
+    #
     def horizontal_rule
       format_row(false, HORIZONTAL_RULE_CHARACTER, CORNER_CHARACTER, &:horizontal_rule)
     end
 
+    # Internal
     def formatted_body_row(source, options = { with_header: false })
       inner = format_row { |column| column.body_cell(source) }
       if options[:with_header]
@@ -74,11 +183,14 @@ module Tabulo
 
     private
 
+    # Internal
     def body_row(source, options = { with_header: false })
       Row.new(self, source, options)
     end
 
+    # Internal
     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|
         raw = yield column
         wrap = (header ? @wrap_header_cells_to : @wrap_body_cells_to)
@@ -107,10 +219,12 @@ module Tabulo
       join_lines(subrows.map { |subrow| "#{joiner}#{subrow.join(joiner)}#{joiner}" })
     end
 
+    # Internal
     def join_lines(lines)
       lines.join($/)  # join strings with cross-platform newline
     end
 
+    # Internal
     def make_column(item, options = { })
       case item
       when Column

data/lib/tabulo/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tabulo
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Matthew Harvey
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-04-23 00:00:00.000000000 Z
+date: 2017-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -88,6 +88,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".rdoc_options"
 - ".rspec"
 - ".travis.yml"
 - CHANGELOG.md
@@ -95,6 +96,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- TODO.md
 - bin/console
 - bin/setup
 - lib/tabulo.rb