Item::as_table is a beatrap

[ijackson]

Item::as_table looks at first glance like the obvious method to call if you want to do a normal table value lookup. But it returns None for Item::Value(Value::InlineTable(..)).

The call you should use instead for this is as_table_like. That's a longer name (so less obvious). There's nothing in the documentation of as_table to warn you about this.

I was tripped up by this because the author of a crate that now uses toml_edit wrote the bug that this API induces. (I suspect from the history there that that project switched from another toml library, which presumably an .as_table function that gave Some for inline tables too.)

I suggest:

1. Right away, improve the documentation for .as_table and .is_table (in Item)
2. Next time we do an incompatible bump, rename {as,is}_table -> {as,is}_outline_table (or similar bikeshed) and {as,is}_table_like to {as,is}_table.

[epage]

Next time we do an incompatible bump, rename {as,is}_table -> {as,is}_outline_table (or similar bikeshed) and {as,is}_table_like to {as,is}_table.

The current naming is very consistent {as,is}_{type}. We have Table, InlineTable, and dyn TableLike. The first two names are setup to match the TOML Specification.

[ijackson]

The current naming is very consistent {as,is}_{type}. We have Table, InlineTable, and dyn TableLike. The first two names are setup to match the TOML Specification.

I see the value in consistency. I do think we should at least consider renaming them (and, therefore, renaming these types too). I think it's more important to provide an API that helps our users avoid foreseeable bugs, than to be 100% faithful with upstream terminology.

[epage]

This is a low level API dealing with concepts as they exist in the TOML grammar. toml should be used if they want an API that deals only with high-leveler details.