search

toml-rs / toml

Rust TOML Parser
https://docs.rs/toml
Apache License 2.0
699 stars 104 forks source link

`toml_edit`: `toml_edit::value` returns an `Item`, not a `Value` #790

Closed teythoon closed 6 days ago

teythoon commented 1 week ago 
pub fn value<V: Into<Value>>(v: V) -> Item

Further, the documentation says it returns a formatted value.

This seems to be either an oversight from a previous refactoring, or an ingenious attempt of gaslighting downstream consumers ;)

epage commented 1 week ago

Further, the documentation says it returns a formatted value.

This seems to be either an oversight from a previous refactoring, or an ingenious attempt of gaslighting downstream consumers ;)

Neither. It is doing what its saying. It says

Returns a formatted value.

In contrast to

Returns a formatted Value.

In TOML semantics, it is returning a value and that is carried over in it being an Item::Value.

The API is optimized for DocumentMut::index_mut and Table::index_mut for quick creation of a document, rather than any calls on InlineTable or Array.

e.g. code like https://github.com/toml-rs/toml/blob/0b4cf74420cc65e04e909945f48a36a19370327c/crates/toml_edit/tests/testsuite/edit.rs#L166-L168

teythoon commented 6 days ago

As a new user of toml_edit, the most challenging aspect of its API was that it is so inhomogeneous. Depending on what kind of object you have, doing a get or an iter may give you Items, Arrays, or Values. That is a significant cognitive burden.

On top of that, having a function called value that returns an item doesn't help.

epage commented 6 days ago

get and iter are generally returning the most specific types which gives you type level feedback on what you can do, rather than having to assume and unwrap.
Doing this is fairly idiomatic in Rust. It is made worse by TOML having two different kinds of arrays and tables.

value doesn't because it was generally geared for a different purpose (inserting into Tables)

At this time, I do not see us changing this part of the API