jwodder / txtble Goto Github PK

This could be done either through dedicated configuration options or just by permitting Cell classes from #5 to be used in headers.

Cf. #11.

• Settings for a reStructuredText "simple table":

  RST_BORDER = BorderStyle(
      hline    = "=",
      vline    = "  ",
      ulcorner = "  ",
      urcorner = "  ",
      llcorner = "  ",
      lrcorner = "  ",
      vrtee    = "  ",
      vltee    = "  ",
      dhtee    = "  ",
      uhtee    = "  ",
      plus     = "  ",
  )
  
  border_style = RST_BORDER
  left_border  = False
  right_border = False

  Note that this does not support indicating column spans with hyphen rules. It also can result in multiline or blank cells in the first column, which rST will misinterpret.

• Settings for a reStructuredText "grid table":

  padding = 1  # Optional
  row_border = True
  header_border = ASCII_EQ_BORDERS

• Settings for a GitHub-Flavored Markdown table, sans alignment-indicating colons:

  GFM_LEFT_BORDER_STYLE = BorderStyle(
      hline = None,
      vline = "| ",
      ulcorner = "| ",
      urcorner = "| ",
      llcorner = "| ",
      lrcorner = "| ",
      vrtee = "| ",
      vltee = "| ",
      dhtee = "| ",
      uhtee = "| ",
      plus = "| ",
  )
  
  GFM_RIGHT_BORDER_STYLE = BorderStyle(
      hline = None,
      vline = " |",
      ulcorner = " |",
      urcorner = " |",
      llcorner = " |",
      lrcorner = " |",
      vrtee = " |",
      vltee = " |",
      dhtee = " |",
      uhtee = " |",
      plus = " |",
  )
  
  GFM_COLUMN_BORDER_STYLE = BorderStyle(
      hline = None,
      vline = " | ",
      ulcorner = " | ",
      urcorner = " | ",
      llcorner = " | ",
      lrcorner = " | ",
      vrtee = " | ",
      vltee = " | ",
      dhtee = " | ",
      uhtee = " | ",
      plus = " | ",
  )
  
  GFM_HEADER_BORDER_STYLE = BorderStyle(
      hline = "-",
      vline = None,
      ulcorner = None,
      urcorner = None,
      llcorner = None,
      lrcorner = None,
      vrtee = "| ",
      vltee = " |",
      dhtee = None,
      uhtee = None,
      plus = " | ",
  )
  
  top_border = False
  bottom_border = False
  left_border = GFM_LEFT_BORDER_STYLE
  right_border = GFM_RIGHT_BORDER_STYLE
  column_border = GFM_COLUMN_BORDER_STYLE
  header_border = GFM_HEADER_BORDER_STYLE

• Settings for a Pandoc Markdown table (requires colsep from #4 or #22):

  border = False
  bottom_border = True
  colsep = "  "

• Cf. tabulate's tablefmt

Additionally, even when they are initialized from a list, it should be possible to set indices out of range of the original list but in range for the table's number of columns.

• Should it also be possible to index the properties by column header text?
• Idea: If the final types of the options are publicly exposed, then align_fill etc. can be deprecated in favor of align=FillAlign(["r"], fill="l") (Class name a WIP)

Some basic test cases for this feature can be found on the feature/align-index branch.

Add a public Cell class (not to be confused with the Cell class used internally by the code as of v0.12.0, which will have to be renamed) that wraps and can be passed in place of a cell's content and that takes optional parameters for setting the alignment, padding, etc. for just that cell.

• Cell(None) should be the same as "None", regardless of the value of none_str
• Should Cells be allowed in headers? How would that interact with dict rows?

Some basic test cases for this feature can be found on the feature/cell-class branch.

Support setting the final (or just maximum?) width of a table to a specific value, with columns automatically resized to fit

• Look into how rich does this.

wcwidth.wcswidth() will report the length of a string as -1 ("indeterminate") if it contains any C0 or C1 control characters (other than NUL) or DEL; in particular, it will return -1 for any strings containing ANSI escape sequences. Txtble should have a decent way to handle these strings.

• Should Txtble raise an error upon encountering any strings of indeterminate width? Some ANSI escape sequences (like screen clearing & cursor repositioning) would just completely wreck the table output anyway.

• I plan to eventually give Txtble a configuration option for setting the len()/wcswidth() function to use, which would allow users to supply their own solution to the ANSI string width problem, but is the problem common enough to warrant built-in support in the library?

• Use blessed.Terminal.length()?

• Use one of the solutions at https://stackoverflow.com/q/2186919/744178?

Alternatively, the same effect could mostly just be achieved by manually inserting an HRule from #3 before the "footer" row.

Currently, when a horizontal & vertical rule meet, the style of the horizontal rule is used to draw the intersection. Add options for overriding this.

Add an "HRule" class that can be passed in place of a data row to indicate that a horizontal rule should be inserted there in the resulting table.

• HRule constructor arguments (all keyword-only):

  • fill: Optional[str] = None
  • joint: Optional[str] = None
  • left_cap: Optional[str] = None
  • right_cap: Optional[str] = None
  • border_style: Optional[BorderStyle] = None
    • When specified, border_style is used to fill in the default values for the other parameters. When border_style is None:
      • If fill is None, border_style inherits from the Txtble's row_border (or from border_style if that is not a BorderStyle)
      • If fill is not None, ???

• Give HRule options for (a) not applying the rule's style to the table border intersections at the ends and (b) not applying the rule's style at column intersections?

  • Somehow give header_border and row_border analogous options?
  • Allow header_border and row_border to be set to HRules?

• Give HRule options for controlling what happens when adjacent to a top_border, header_border, row_border, or bottom_border (possibilities: *_border takes precedence, HRule takes precedence, draw both)

Some basic test cases for this feature can be found on the feature/hrule branch.

Add a trim_columns: bool (Rethink name) option for reducing the width of each set-width column until it has no common character-column of filler whitespace (i.e., reducing the width as much as possible without causing re-wrapping)

• Add a colsep: str option for setting the column separator to a constant string (Cf. the option of the same name from #4)
  • Let it be a sequence of strings in order to support "doubling" of specific vrules
• Add an option for setting the column separator only for non-hrule rows (i.e., the separator between adjacent cells) (Cf. #9)
• Allow column_border, left_border, and right_border to be just a string? (since only one string of BorderStyle gets used anyway)

Add filler cells and remove extra cells until the constraints are met.

• Don't break across zero-width joiner, word joiner, or non-breaking space
• Don't break in the middle of combining character sequences
• Don't break on a space or hyphen followed by combining characters
• Break on more than just spaces and hyphens?
• cf. the Unicode line breaking algorithm and Unicode TR 29
• cf. uniseg package

Extend the Cell class from #5 to take colspan: int = 1 and rowspan: int = 1 parameters for producing cells that potentially span multiple columns and/or rows of a table.

• A multicolumn/multirow cell is passed to a Txtble at the location of the cell's top-left corner. The other cells that are "covered up by"/"merged into" a multicolumn/multirow cell must be completely absent from the data array. For example, a four-column row in which the second cell is two cells wide would be written as ["Foo", Cell("Bar", colspan=2), "Baz"] ("Baz" is here the cell in the fourth column, not the third).

  • If all the cells in a row are "covered" by other cells, the row still has to be present as an empty sequence.

• By default, the width of a multicolumn cell takes precedence over the widths of the columns it spans.

  • If the multicolumn cell is narrower than the sum of the widths of the columns it spans (plus column separators), the multicolumn cell is widened to fit.
  • If a multicolumn cell's width X is greater than the sum Y of the widths of the N columns it spans, the columns are widened to match by adding ceil((X - Y) / N) spaces to the first (X - Y) % N columns and floor((X - Y) / N) to the rest.
  • If restrict_width=True is set on a multicolumn Cell, the columns it spans will take precedence over it, width-wise.
    • If such a cell's natural width is greater than the columns it spans, its width will be reduced to match.
    • restrict_width has no effect on Cells that span only one column

• A multicolumn/multirow cell's alignment, padding, etc. is based on that of its upper-left corner.

Some basic test cases for this feature can be found on the feature/span branch.

Cf. #8.

Add a VRule class for specifying the format of vertical rules in tables.

• VRule constructor arguments (all keyword-only; cf. HRule constructor arguments in #3):

  • fill: Optional[str] = None
  • joint: Optional[str] = None
  • top_cap: Optional[str] = None
  • bottom_cap: Optional[str] = None
  • border_style: Optional[BorderStyle] = None

• VRules are passed to a Txtble as elements of a colsep list configuration option and/or as the value of a colsep_fill configuration option.

  • A string element s of colsep/value of colsep_fill is equivalent to VRule(fill=s, joint=s).

• HRule (#3) and VRule should have priority: int parameters (defaulting to 0) for controlling what happens when an HRule and a VRule meet; the rule with the higher priority is used to draw the joint, and if they have the same priority, ???

• When an HRule or VRule meets the table border, whose cap style is used?

(This can happen when a cell contains a very long word, among other cases.)

Possible ways to handle such lines: let them overflow or expand the column to contain them

E.g., editing, deleting, rearranging, sorting rows, etc.