txt: ## dist_cpan-ANTONOV-Pretty-Table.md
  # Name
  
  `Pretty::Table`, a simple Raku module to make it quick and easy to represent tabular data in visually appealing ASCII tables.
  
  `Pretty::Table` is a port of the Python library [PTable](https://github.com/kxxoling/PTable).
  
  **Disclaimer:** This module is still a work in progress. Although some basic features are implemented, they still require further testing.
  
  # Synopsis
  
  **Example 1**:
  
  ```
  use Pretty::Table;
  
  my $table = Pretty::Table.new:
      title => "Australian Cities",
      field-names => ["City name", "Area", "Population", "Annual Rainfall"],
      sort-by => 'Area',
      align => %('City name' => 'l'),
  ;
  
  given $table {
      .add-row: ["Adelaide",  1295,  1158259,  600.5 ];
      .add-row: ["Brisbane",  5905,  1857594,  1146.4];
      .add-row: ["Darwin",    112,   120900,   1714.7];
      .add-row: ["Hobart",    1357,  205556,   619.5 ];
      .add-row: ["Sydney",    2058,  4336374,  1214.8];
      .add-row: ["Melbourne", 1566,  3806092,  646.9 ];
      .add-row: ["Perth",     5386,  1554769,  869.4 ];
  }
  
  say $table;
  
  ```
  
  Output:
  
  ```
  +—————————————————————————————————————————————————+
  |                Australian Cities                |
  +———————————+——————+————————————+—————————————————+
  | City name | Area | Population | Annual Rainfall |
  +———————————+——————+————————————+—————————————————+
  | Darwin    | 112  |   120900   |      1714.7     |
  | Adelaide  | 1295 |  1158259   |      600.5      |
  | Hobart    | 1357 |   205556   |      619.5      |
  | Melbourne | 1566 |  3806092   |      646.9      |
  | Sydney    | 2058 |  4336374   |      1214.8     |
  | Perth     | 5386 |  1554769   |      869.4      |
  | Brisbane  | 5905 |  1857594   |      1146.4     |
  +———————————+——————+————————————+—————————————————+
  
  ```
  
  **Example 2**:
  
  ```
  use Pretty::Table;
  
  my $table = Pretty::Table.new;
  
  given $table {
      .add-column('Planet', ['Earth', 'Mercury', 'Venus', 'Mars', 'Jupiter', 'Saturn', 'Uranus', 'Neptune']);
      .add-column('Position', [3, 1, 2, 4, 5, 6, 7, 8])
      .add-column('Known Satellites', [1, 0, 0, 2, 79, 82, 27, 14]);
      .add-column('Orbital period (days)', [365.256, 87.969, 224.701, 686.971, 4332.59, 10_759.22, 30_688.5, 60_182.0]);
      .add-column('Surface gravity (m/s)', [9.806, 3.7, 8.87, 3.721, 24.79, 10.44, 8.69, 11.15]);
  }
  
  $table.title('Planets in the Solar System');
  $table.align(%(:Planet<l>));
  $table.float-format(%('Orbital period (days)' => '-10.3f', 'Surface gravity (m/s)' => '-5.3f'));
  $table.sort-by('Position');
  $table.junction-char('*');
  
  put $table;
  
  ```
  
  Output:
  
  ```
  *————————————————————————————————————————————————————————————————————*
  |                    Planets in the Solar System                     |
  *—————————*——————————*———————————————————————*———————————————————————*
  | Planet  | Position | Orbital period (days) | Surface gravity (m/s) |
  *—————————*——————————*———————————————————————*———————————————————————*
  | Mercury |    1     |       87.969          |         3.700         |
  | Venus   |    2     |       224.701         |         8.870         |
  | Earth   |    3     |       365.256         |         9.806         |
  | Mars    |    4     |       686.971         |         3.721         |
  | Jupiter |    5     |       4332.590        |         24.790        |
  | Saturn  |    6     |       10759.220       |         10.440        |
  | Uranus  |    7     |       30688.500       |         8.690         |
  | Neptune |    8     |       60182.000       |         11.150        |
  *—————————*——————————*———————————————————————*———————————————————————*
  
  ```
  
  # Installation
  
  Using zef:
  
  ```
  zef install Pretty::Table
  
  ```
  
  From source:
  
  ```
  $ git clone 
  $ cd raku-pretty-table
  $ zef install .
  
  ```
  
  # Quickstart
  
  `Pretty::Table` supports two kinds of usage:
  
  ## As a module
  
  ```
  use Pretty::Table;
  my $x = Pretty::Table.new;
  
  ```
  
  Read the section **Getter and Setter Methods** to find about the public attributes and their respective methods. For the [tutorial](https://gitlab.com/uzluisf/raku-pretty-table/tree/master/doc/Pretty/Table/Tutorial.rakumod), run `p6doc Pretty::Table::Tutorial`.
  
  ## As a command-line tool
  
  ```
  pt --csv somefile.csv
  
  ```
  
  Run `pt` to get the full usage message.
  
  # Methods
  
  ## Getter and Setter Methods
  
  **NOTE**: These methods's names are the same as their respective attributes. To set a specific attribute during the instantiation of a `Pretty::Table` object, use its method's name. For instance, to set `title`, `Pretty::Table.new(title => "Table's title")`. Thus, all methods listed here have an associated attribute that can be set during object construction.
  
  ### multi method field-names
  
  ```
  multi method field-names() returns Array
  
  ```
  
  Return a list of field names.
  
  ### multi method field-names
  
  ```
  multi method field-names(
      @values
  ) returns Nil
  
  ```
  
  Set a list of field names.
  
  ### multi method align
  
  ```
  multi method align() returns Hash
  
  ```
  
  Return how the alignment of fields is controlled.
  
  ### multi method align
  
  ```
  multi method align(
      $val
  ) returns Nil
  
  ```
  
  Set how the alignment of fields is controlled. Either an alignment string (l, c, or r) or a hash of field-to-alignment pairs.
  
  ### multi method valign
  
  ```
  multi method valign() returns Hash
  
  ```
  
  Return how the vertical alignment of fields is controlled.
  
  ### multi method valign
  
  ```
  multi method valign(
      $val
  ) returns Nil
  
  ```
  
  Set how the vertical alignment of fields is controlled. Either an alignment string (t, m, or b) or a hash of field-to-alignment pairs.
  
  ### multi method max-width
  
  ```
  multi method max-width() returns Pretty::Table::Constrains::NonNeg
  
  ```
  
  Return the maximum width of fields.
  
  ### multi method max-width
  
  ```
  multi method max-width(
      $val where { ... }
  ) returns Nil
  
  ```
  
  Set the maximum width of fields.
  
  ### multi method min-width
  
  ```
  multi method min-width() returns Hash
  
  ```
  
  Return the minimum width of fields.
  
  ### multi method min-width
  
  ```
  multi method min-width(
      $val where { ... }
  ) returns Nil
  
  ```
  
  Set the minimum width of fields.
  
  ### multi method min-table-width
  
  ```
  multi method min-table-width() returns Pretty::Table::Constrains::NonNeg
  
  ```
  
  Return the minimum desired table width, in characters.
  
  ### multi method min-table-width
  
  ```
  multi method min-table-width(
      $val where { ... }
  ) returns Mu
  
  ```
  
  Set the minimum desired table width, in characters.
  
  ### multi method max-table-width
  
  ```
  multi method max-table-width() returns Mu
  
  ```
  
  Return the maximum desired table width, in characters.
  
  ### multi method max-table-width
  
  ```
  multi method max-table-width(
      $val where { ... }
  ) returns Mu
  
  ```
  
  Set the minimum desired table width, in characters.
  
  ### multi method fields
  
  ```
  multi method fields() returns Array
  
  ```
  
  Return the list of field names to include in displays.
  
  ### multi method fields
  
  ```
  multi method fields(
      @values
  ) returns Mu
  
  ```
  
  Return the list of field names to include in displays.
  
  ### multi method title
  
  ```
  multi method title() returns Str
  
  ```
  
  Return the table title (if existent).
  
  ### multi method title
  
  ```
  multi method title(
      Str $val
  ) returns Mu
  
  ```
  
  Set the table title.
  
  ### multi method start
  
  ```
  multi method start() returns Pretty::Table::Constrains::NonNeg
  
  ```
  
  Return the start index of the range of rows to print.
  
  ### multi method start
  
  ```
  multi method start(
      $val where { ... }
  ) returns Mu
  
  ```
  
  Set the start index of the range of rows to print.
  
  ### multi method end
  
  ```
  multi method end() returns Mu
  
  ```
  
  Return the end index of the range of rows to print.
  
  ### multi method end
  
  ```
  multi method end(
      $val
  ) returns Mu
  
  ```
  
  Set the end index of the range of rows to print.
  
  ### multi method sort-by
  
  ```
  multi method sort-by() returns Mu
  
  ```
  
  Return the name of field by which to sort rows.
  
  ### multi method sort-by
  
  ```
  multi method sort-by(
      Str $val where { ... }
  ) returns Mu
  
  ```
  
  Set the name of field by which to sort rows.
  
  ### multi method reverse-sort
  
  ```
  multi method reverse-sort() returns Bool
  
  ```
  
  Return the direction of sorting, ascending (False) vs descending (True).
  
  ### multi method reverse-sort
  
  ```
  multi method reverse-sort(
      Bool $val
  ) returns Nil
  
  ```
  
  Set the direction of sorting (ascending (False) vs descending (True).
  
  ### multi method sort-key
  
  ```
  multi method sort-key() returns Callable
  
  ```
  
  Return the sorting key function, applied to data points before sorting.
  
  ### multi method sort-key
  
  ```
  multi method sort-key(
      &val
  ) returns Nil
  
  ```
  
  Set the sorting key function, applied to data points before sorting.
  
  ### multi method header
  
  ```
  multi method header() returns Bool
  
  ```
  
  Return whether the table has a heading showing the field names.
  
  ### multi method header
  
  ```
  multi method header(
      Bool $val
  ) returns Nil
  
  ```
  
  Set whether the table has a heading showing the field names.
  
  ### multi method header-style
  
  ```
  multi method header-style() returns Pretty::Table::Constrains::HeaderStyle
  
  ```
  
  Return style to apply to field names in header ("cap", "title", "upper", or "lower").
  
  ### multi method header-style
  
  ```
  multi method header-style(
      $val where { ... }
  ) returns Mu
  
  ```
  
  Set style to apply to field names in header ("cap", "title", "upper", or "lower").
  
  ### multi method border
  
  ```
  multi method border() returns Bool
  
  ```
  
  Return whether a border is printed around table.
  
  ### multi method border
  
  ```
  multi method border(
      Bool $val
  ) returns Mu
  
  ```
  
  Set whether a border is printed around table.
  
  ### multi method hrules
  
  ```
  multi method hrules() returns Pretty::Table::Constrains::HorizontalRule
  
  ```
  
  Return how horizontal rules are printed after rows.
  
  ### multi method hrules
  
  ```
  multi method hrules(
      $val where { ... }
  ) returns Mu
  
  ```
  
  Set how horizontal rules are printed after rows. Allowed values: FRAME, ALL, HEADER, NONE
  
  ### multi method vrules
  
  ```
  multi method vrules() returns Pretty::Table::Constrains::VerticalRule
  
  ```
  
  Return how vertical rules are printed between columns.
  
  ### multi method vrules
  
  ```
  multi method vrules(
      $val where { ... }
  ) returns Mu
  
  ```
  
  Set how vertical rules are printed between columns. Allowed values: FRAME, ALL, NONE
  
  ### multi method int-format
  
  ```
  multi method int-format() returns Mu
  
  ```
  
  Return how the integer data is formatted.
  
  ### multi method int-format
  
  ```
  multi method int-format(
      $val
  ) returns Nil
  
  ```
  
  Set how the integer data is formatted. The value can either be a string or a hash of field-to-format pairs.
  
  ### multi method float-format
  
  ```
  multi method float-format() returns Mu
  
  ```
  
  Return how the integer data is formatted.
  
  ### multi method float-format
  
  ```
  multi method float-format(
      $val
  ) returns Nil
  
  ```
  
  Set how the integer data is formatted. The value can either be a string or a hash of field-to-format pairs.
  
  ### multi method padding-width
  
  ```
  multi method padding-width() returns Pretty::Table::Constrains::NonNeg
  
  ```
  
  Return the number of empty spaces between a column's edge and its content.
  
  ### multi method padding-width
  
  ```
  multi method padding-width(
      $val where { ... }
  ) returns Nil
  
  ```
  
  Set the number of empty spaces between a column's edge and its content.
  
  ### multi method left-padding-width
  
  ```
  multi method left-padding-width() returns Pretty::Table::Constrains::NonNeg
  
  ```
  
  Return the number of empty spaces between a column's left edge and its content.
  
  ### multi method left-padding-width
  
  ```
  multi method left-padding-width(
      $val where { ... }
  ) returns Nil
  
  ```
  
  Set the number of empty spaces between a column's left edge and its content.
  
  ### multi method right-padding-width
  
  ```
  multi method right-padding-width() returns Pretty::Table::Constrains::NonNeg
  
  ```
  
  Return the number of empty spaces between a column's right edge and its content.
  
  ### multi method right-padding-width
  
  ```
  multi method right-padding-width(
      $val where { ... }
  ) returns Nil
  
  ```
  
  Set the number of empty spaces between a column's right edge and its content.
  
  ### multi method vertical-char
  
  ```
  multi method vertical-char() returns Pretty::Table::Constrains::Char
  
  ```
  
  Return character used when printing table borders to draw vertical lines.
  
  ### multi method vertical-char
  
  ```
  multi method vertical-char(
      $val where { ... }
  ) returns Nil
  
  ```
  
  Return character used when printing table borders to draw vertical lines.
  
  ### multi method horizontal-char
  
  ```
  multi method horizontal-char() returns Pretty::Table::Constrains::Char
  
  ```
  
  Return character used when printing table borders to draw horizontal lines.
  
  ### multi method horizontal-char
  
  ```
  multi method horizontal-char(
      $val where { ... }
  ) returns Nil
  
  ```
  
  Return character used when printing table borders to draw horizontal lines.
  
  ### multi method junction-char
  
  ```
  multi method junction-char() returns Pretty::Table::Constrains::Char
  
  ```
  
  Return character used when printing table borders to draw line junctions.
  
  ### multi method junction-char
  
  ```
  multi method junction-char(
      $val where { ... }
  ) returns Nil
  
  ```
  
  Return character used when printing table borders to draw line junctions.
  
  ### multi method format
  
  ```
  multi method format() returns Bool
  
  ```
  
  Return whether or not HTML tables are formatted to match styling options.
  
  ### multi method format
  
  ```
  multi method format(
      Bool $val
  ) returns Nil
  
  ```
  
  Set whether or not HTML tables are formatted to match styling options.
  
  ### multi method print-empty
  
  ```
  multi method print-empty() returns Bool
  
  ```
  
  Return whether or not empty tables produce a header and frame or just an empty string.
  
  ### multi method print-empty
  
  ```
  multi method print-empty(
      Bool $val
  ) returns Nil
  
  ```
  
  Set whether or not empty tables produce a header and frame or just an empty string.
  
  ### multi method old-sort-slice
  
  ```
  multi method old-sort-slice() returns Bool
  
  ```
  
  Return whether to slice rows before sorting in the "old style".
  
  ### multi method old-sort-slice
  
  ```
  multi method old-sort-slice(
      Bool $val
  ) returns Nil
  
  ```
  
  Return whether to slice rows before sorting in the "old style".
  
  ## Style of Table
  
  ### method set-style
  
  ```
  method set-style(
      TableStyle $style
  ) returns Nil
  
  ```
  
  Set the style to be used for the table. Allowed values: DEFAULT: Show header and border, hrules and vrules are FRAME and ALL respectively, paddings are 1, vert. char is |, hor. char is -, and junction char is +. MSWORD-FRIENDLY: Show header and border, hrules is NONE, paddings are 1, and vert. char is | PLAIN-COLUMNS: Show header and hide border, hrules is NONE, padding is 1, left padding is 0, and right padding is 8 RANDOM: random style
  
  ## Data Input Methods
  
  ### method add-row
  
  ```
  method add-row(
      @row
  ) returns Nil
  
  ```
  
  Add a row to the table.
  
  ## class Mu $
  
  Row of data, should be a list with as many elements as the table has fields.
  
  ### method del-row
  
  ```
  method del-row(
      Int $row-index
  ) returns Nil
  
  ```
  
  Delete a row from the table.
  
  ## class Mu $
  
  Index of the row to delete (0-based index).
  
  ### method add-column
  
  ```
  method add-column(
      Str $fieldname,
      @column,
      $align where { ... } = "c",
      $valign where { ... } = "m"
  ) returns Nil
  
  ```
  
  Add a column to the table.
  
  ## class Mu $
  
  Name of the field to contain the new column of data.
  
  ## class Mu $
  
  Column of data, should be a list with as many elements as the table has rows.
  
  ## class Mu $
  
  Desired alignment for this column - "l" (left), "c" (center), and "r" (right).
  
  ## class Mu $
  
  Desired vertical alignment for new columns - "t" (top), "m" (middle), and "b" (bottom).
  
  ### method clear-rows
  
  ```
  method clear-rows() returns Nil
  
  ```
  
  Delete all rows from the table but keep the current field names.
  
  ### method clear
  
  ```
  method clear() returns Nil
  
  ```
  
  Delete all rows and field names from the table, maintaining nothing but styling options.
  
  ## Plain Text String methods
  
  ### method get-string
  
  ```
  method get-string(
      Str :$title = Str,
      :$start where { ... } = Pretty::Table::Constrains::NonNeg,
      :$end where { ... } = Pretty::Table::Constrains::NonNeg,
      :@fields,
      Bool :$header = Bool,
      Bool :$border = Bool,
      :$hrules where { ... } = Pretty::Table::Constrains::HorizontalRule,
      :$vrules where { ... } = Pretty::Table::Constrains::VerticalRule,
      Str :$int-format = Str,
      Str :$float-format = Str,
      :$padding-width where { ... } = Pretty::Table::Constrains::NonNeg,
      :$left-padding-width where { ... } = Pretty::Table::Constrains::NonNeg,
      :$right-padding-width where { ... } = Pretty::Table::Constrains::NonNeg,
      :$vertical-char where { ... } = Pretty::Table::Constrains::Char,
      :$horizontal-char where { ... } = Pretty::Table::Constrains::Char,
      :$junction-char where { ... } = Pretty::Table::Constrains::Char,
      Str :$sort-by = Str,
      :&sort-key,
      Bool :$reverse-sort = Bool,
      Bool :$old-sort-slice = Bool,
      Bool :$print-empty = Bool
  ) returns Str
  
  ```
  
  Return string representation of table in current state.
  
  ## class Mu $
  
  See method title
  
  ## class Mu $
  
  See method start
  
  ## class Mu $
  
  See method end
  
  ## class Mu $
  
  See method fields
  
  ## class Mu $
  
  See method header
  
  ## class Mu $
  
  See method border
  
  ## class Mu $
  
  See method hrules
  
  ## class Mu $
  
  See method vrules
  
  ## class Mu $
  
  See method int-format
  
  ## class Mu $
  
  See method float-format
  
  ## class Mu $
  
  See method padding-width
  
  ## class Mu $
  
  See method left-padding-width
  
  ## class Mu $
  
  See method right-padding-width
  
  ## class Mu $
  
  See method vertical-char
  
  ## class Mu $
  
  See method horizontal-char
  
  ## class Mu $
  
  See method junction-char
  
  ## class Mu $
  
  See method sort-by
  
  ## class Mu $
  
  See method sort-key
  
  ## class Mu $
  
  See method reverse-sort
  
  ## class Mu $
  
  see method old-sort-slice
  
  ## class Mu $
  
  See method print-empty
  
  ## Miscellaneous Methods
  
  ### method row-count
  
  ```
  method row-count() returns Int
  
  ```
  
  Return the number of rows.
  
  ### method col-count
  
  ```
  method col-count() returns Int
  
  ```
  
  Return the number of columns.
  