separate_rows

Whether or not to draw a separator between rows. This is useful when you have a record that contains lists.

limit_width_to

Maximum width of the printed table. This is useful to restrict the size of the table so that it fits within the editor window.

nested_columns

How to render the column headers for fields in nested records. Valid options are `dotted, `stacked, `last, and `auto. By default, Expectable uses `auto, which is a simple heuristic that chooses between `dotted and `stacked rendering based on the length of field names:

  let records = [ [%sexp { label = { rows = 10; columns = 20 } }] ] in
  Expectable.print records ~nested_columns:`auto;
  [%expect
    {|
    ┌────────────┬─────────┐
    │            │ label   │
    │ label.rows │ columns │
    ├────────────┼─────────┤
    │ 10         │ 20      │
    └────────────┴─────────┘
    |}];

This can lead to goofy results like the above, where it infers different layouts for sibling fields. You can force a specific layout instead:

  Expectable.print records ~nested_columns:`dotted;
  [%expect
    {|
    ┌────────────┬───────────────┐
    │ label.rows │ label.columns │
    ├────────────┼───────────────┤
    │ 10         │ 20            │
    └────────────┴───────────────┘
    |}];

  Expectable.print records ~nested_columns:`stacked;
  [%expect
    {|
    ┌───────┬─────────┐
    │ label │ label   │
    │ rows  │ columns │
    ├───────┼─────────┤
    │ 10    │ 20      │
    └───────┴─────────┘
    |}];

Or you can choose to omit all but the final component of the field's header:

  Expectable.print records ~nested_columns:`last;
  [%expect
    {|
    ┌──────┬─────────┐
    │ rows │ columns │
    ├──────┼─────────┤
    │ 10   │ 20      │
    └──────┴─────────┘
    |}];

Although note that this can result in ambiguous column headers:

  Expectable.print
    [ [%sexp { foo = { rows = 10; columns = 20 }; bar = { rows = 1; columns = 20 } }] ]
    ~nested_columns:`last;
  [%expect
    {|
    ┌──────┬─────────┬──────┬─────────┐
    │ rows │ columns │ rows │ columns │
    ├──────┼─────────┼──────┼─────────┤
    │ 10   │ 20      │ 1    │ 20      │
    └──────┴─────────┴──────┴─────────┘
    |}];

max_depth

Expectable does its best to present a reasonable view of whatever data you throw at it, but its "magic" autoformatting might not always we what you want. For example, optional fields equal to None render as empty cells, and optional fields that are Some don't render with parentheses.

  let records =
    [ [%sexp { foo = 1; bar = (None       : string option) }]
    ; [%sexp { foo = 2; bar = (Some ""    : string option) }]
    ; [%sexp { foo = 3; bar = (Some "hey" : string option) }]
    ]
  in
  Expectable.print records;
  [%expect
    {|
    ┌─────┬─────┐
    │ foo │ bar │
    ├─────┼─────┤
    │ 1   │     │
    │ 2   │     │
    │ 3   │ hey │
    └─────┴─────┘
    |}];

You can tell Expectable to be a little less clever by passing the ~max_depth argument, which will control how deeply it will traverse the input sexp.

  Expectable.print records ~max_depth:1;
  [%expect
    {|
    ┌─────┬───────┐
    │ foo │ bar   │
    ├─────┼───────┤
    │ 1   │ ()    │
    │ 2   │ ("")  │
    │ 3   │ (hey) │
    └─────┴───────┘
    |}];

Note though that this is a global setting, and not something you can control per-column. If you want more control over the format of your table, you're probably better off constructing the ASCII table directly.

align

The default alignment is ~align:`numbers, which pads purely numeric columns so that their decimal points line up.

  Expectable.print_cases
    ~align:`numbers
    ~sexp_of_input:[%sexp_of: string]
    ~sexp_of_output:[%sexp_of: float option]
    ~f:Float.of_string_opt
    cases;
  [%expect
    {|
    ┌┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┐
    ├┴┴┴┴┴┴┴┴┴┴┴┴┼┴┴┴┴┴┴┴┴┴┴┴┤
    │ -0         │    -0     │
    │ +0         │     0     │
    │ 000        │     0     │
    │ 245e-3     │     0.245 │
    │ 7.0        │     7     │
    │ 9.5        │     9.5   │
    │ 0x10       │    16     │
    │ 0x1e1      │   481     │
    │ 1_000      │  1000     │
    │ 1.234567e4 │ 12345.67  │
    │ abc        │           │
    └────────────┴───────────┘
    |}];

But you can provide an explicit alternate alignment if you prefer:

  Expectable.print_cases
    ~align:`left
    ~sexp_of_input:[%sexp_of: string]
    ~sexp_of_output:[%sexp_of: float option]
    ~f:Float.of_string_opt
    cases;
  [%expect
    {|
    ┌┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┐
    ├┴┴┴┴┴┴┴┴┴┴┴┴┼┴┴┴┴┴┴┴┴┴┴┤
    │ -0         │ -0       │
    │ +0         │ 0        │
    │ 000        │ 0        │
    │ 245e-3     │ 0.245    │
    │ 7.0        │ 7        │
    │ 9.5        │ 9.5      │
    │ 0x10       │ 16       │
    │ 0x1e1      │ 481      │
    │ 1_000      │ 1000     │
    │ 1.234567e4 │ 12345.67 │
    │ abc        │          │
    └────────────┴──────────┘
    |}];

  Expectable.print_cases
    ~align:`right
    ~sexp_of_input:[%sexp_of: string]
    ~sexp_of_output:[%sexp_of: float option]
    ~f:Float.of_string_opt
    cases;
  [%expect
    {|
    ┌┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┐
    ├┴┴┴┴┴┴┴┴┴┴┴┴┼┴┴┴┴┴┴┴┴┴┴┤
    │         -0 │       -0 │
    │         +0 │        0 │
    │        000 │        0 │
    │     245e-3 │    0.245 │
    │        7.0 │        7 │
    │        9.5 │      9.5 │
    │       0x10 │       16 │
    │      0x1e1 │      481 │
    │      1_000 │     1000 │
    │ 1.234567e4 │ 12345.67 │
    │        abc │          │
    └────────────┴──────────┘
    |}];

  Expectable.print_cases
    ~align:`center
    ~sexp_of_input:[%sexp_of: string]
    ~sexp_of_output:[%sexp_of: float option]
    ~f:Float.of_string_opt
    cases;
  [%expect
    {|
    ┌┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┐
    ├┴┴┴┴┴┴┴┴┴┴┴┴┼┴┴┴┴┴┴┴┴┴┴┤
    │     -0     │    -0    │
    │     +0     │    0     │
    │    000     │    0     │
    │   245e-3   │  0.245   │
    │    7.0     │    7     │
    │    9.5     │   9.5    │
    │    0x10    │    16    │
    │   0x1e1    │   481    │
    │   1_000    │   1000   │
    │ 1.234567e4 │ 12345.67 │
    │    abc     │          │
    └────────────┴──────────┘
    |}];

Note that the alignment you pick applies to all columns. If you want more control over the layout of the final table, it's probably best to construct the ASCII table directly.

Functions

In order of usefulness, these are:

• Expectable.print -- print a list of sexps as a table.
• Expectable.print_cases -- given a list of inputs and a function, print a table showing the result of calling that function.
• Expectable.print_alist -- given a list of named sexps, print them in a table with the name on the left-hand side.
• Expectable.print_record_transposed -- print a single sexp record as if each of its fields were a separate row. This is useful when you have a record with multiple fields of the same type, and want to compare them side by side. For example:

  find_extremes readings ~by:Reading.elevation
  |> [%sexp_of: Reading.t option Hi_lo_pair.t]
  |> Expectable.print_record_transposed;
  [%expect
    {|
    ┌────┬───────────┬─────────────┬───────────┐
    │    │ elevation │ temperature │ pressure  │
    ├────┼───────────┼─────────────┼───────────┤
    │ hi │ 13678ft   │ 4C          │ 612mb     │
    │ lo │ 33ft      │ 31C         │ 1013.25mb │
    └────┴───────────┴─────────────┴───────────┘
    |}];

See [expectable.mli][expectable.mli] for a more detailed description of each function.

Schema inference issues

Expectable assumes that field names are lowercase and variant tags are uppercase. So it will interpret (Foo 123) as a single value, not a list of values. And it will interpret ((Foo 123) (Bar 123)) as a list of values, not as a record.

But there's nothing that guarantees that a variant has to be uppercase: polymorphic variants are often lowercase, and the versioned_sexp library produces lower-cased variants like v1. This makes it annoying to use with Expectable, because Expectable will interpret (v1 something) as a list of two values, v1 and something, not as a constructor.

The only way around this right now is to globally change the ~max_depth argument to cut off schema inference before traversing into sexps like that. It would be very reasonable to allow specifying max-depth on a per-column basis, but Expectable doesn't support that yet.