toml-rs / toml Goto Github PK

View Code? Open in Web Editor NEW

662.0 662.0 101.0 2.93 MB

Rust TOML Parser

Home Page: https://docs.rs/toml

License: Apache License 2.0

Rust 100.00%

rust toml

toml's Introduction

toml-rs

Development of the toml crate has moved to https://github.com/toml-rs/toml/tree/master/crates/toml.

This repo is now archived.

toml's People

Contributors

Stargazers

Watchers

Forkers

gitter-badger bjgill pwoolcoc alsuren azanellato ironyman tofay murarth kgv sunshowers museun orsenkucher thomaseizinger coriolinus riey devinr528 anp epage isgasho steveej-forks parasyte bryanburgers mati865 theneikos parkmycar notriddle zkat jonhoo projectanni clarfonthey evanrichter mayhemheroes winstonewert vikigenius klensy mgsloan manunio clint-white harveyhunt marcusgrass 9uapaw thomas-k-cameron jinguang-dong davidkorczynski popflamingo baloo sanbox-irl npc-studio azzamsa ibeckermayer dtolnay-contrib darrenbaldwin07 doytsujin matthiasbeyer muthsera lymslive cnpryer qwertz19281 chengzhidada zong-zhe rustforneo est31 konstin iq-scm chrisduerr zertosh joshtriplett sksat cuviper akyram marcospb19 yassun7010 newtykip tamird volkalex28 blu-dev dhardy yssource szabgab diliop youknowone trevyn alseinx nneesshh exotik850 justusadam llde tyilo mahkoh cgzones minminm thecaralice manishearth tversteeg mistydemeo

toml's Issues

API revamp

Current API is not easy to use. Inserting into the document requires borrowing the root table.

Make `toml_edit` viable for `cargo`

We might also need

Dotted key ordering isn't always preserved

hello.world = "a"
goodbye = "b"
hello.moon = "c"

gets turned into

hello.world = "a"
hello.moon = "c"
goodbye = "b"

`toml-rs` API on top of `toml_edit`

This is for ease-of-use when people only want one toml parser, like cargo.

de
Values
ser

See #122 for some thoughts

It looks like Table implements Index and IndexMut, and has an inherent method Table::get for getting an optional immutable reference, but there's no easy way to get an optional mutable reference to a key's value. I found myself writing code like this:

        if table.get(&key).is_some() {
            Some(&mut table[&key])
        } else {
            None
        }

It would be useful to expose a get_mut method too.

Memory error when running tests on Windows

When I run the tests on Windows, the test runner crashes in test_insert_nonleaf_table with a read access violation. I tried to debug and got the following stack trace:

test_edit-e9fa5d7815bf14cc.exe!core::cell::Cell<intrusive_collections::linked_list::NodePtr>::get<intrusive_collections::linked_list::NodePtr>() Line 212
test_edit-e9fa5d7815bf14cc.exe!intrusive_collections::linked_list::NodePtr::next() Line 130
test_edit-e9fa5d7815bf14cc.exe!intrusive_collections::linked_list::LinkedList<toml_edit::document::intrusive::TableAdapter>::clear<toml_edit::document::intrusive::TableAdapter>() Line 728
test_edit-e9fa5d7815bf14cc.exe!intrusive_collections::linked_list::{{impl}}::drop<toml_edit::document::intrusive::TableAdapter>(intrusive_collections::linked_list::LinkedList<toml_edit::document::intrusive::TableAdapter> * self) Line 804
test_edit-e9fa5d7815bf14cc.exe!core::ptr::drop_in_place<intrusive_collections::linked_list::LinkedList<toml_edit::document::intrusive::TableAdapter>>(intrusive_collections::linked_list::LinkedList<toml_edit::document::intrusive::TableAdapter> *) Line 61
test_edit-e9fa5d7815bf14cc.exe!core::ptr::drop_in_place<toml_edit::document::DocumentInner>(toml_edit::document::DocumentInner *) Line 61
test_edit-e9fa5d7815bf14cc.exe!core::ptr::drop_in_place<alloc::boxed::Box<toml_edit::document::DocumentInner>>(toml_edit::document::DocumentInner * *) Line 61
test_edit-e9fa5d7815bf14cc.exe!core::ptr::drop_in_place<toml_edit::document::Document>(toml_edit::document::Document *) Line 61
test_edit-e9fa5d7815bf14cc.exe!test_edit::test_insert_nonleaf_table() Line 77

So it looks like the problem is probably coming from intrusive_collections::linked_list (i.e., not your fault, @ordian). Maybe the raw pointer in NodePtr is invalid ... but I didn't investigate further.

add support for toml 1.0

#128
#91
Verify encoding is compliant

set_dotted(true) on InlineTable doesn't work as expected

use toml_edit::*;

fn main() {
    let mut d = Document::new();
    d["nixpkgs"] = table();
    d["nixpkgs"]["src"]["git"] = value("https://git");
    d["nixpkgs"]["src"].as_inline_table_mut().unwrap().set_dotted(true);
    println!("{}", d);
}

prints

[nixpkgs]
src = { git = "https://git"}

keys that contain the dot character are always quoted

hey 👋

i'm trying to create a toml that has key names with dot in them as in the following example:

# nvfetcher.toml
[feeluown-core]
src.pypi = "feeluown"


(...)

FYI, this example is taken from the nvfetcher readme.

according to the toml spec#keys these dotted keys are valid and not necessarily quoted. it would be great to have a way to generate toml in this manner with this library.

Documentation

Document all public API
enable `#[deny(missing_docs)]

Migrate to combine 3.0

Users can't determine what kind of DateTime is included

For me, this is for building on top of #111 to properly encode the data for validation, but I imagine this would be generally useful. toml_edit::DateTime is pub but not exposed in a pub mod.

Should we have toml_edit::DateTime or split out the cases directly in toml_edit::Value? I lean towards the latter as I'm unsure the value for having an extra layer but that extra layer requires a lot of verbosity to access.

Not the greatest error message on bad dotted-key insertion

This is a regression compared to toml-rs found by cargo's tests

For the following document

[http]
ssl-version = 'tlsv1.1'
ssl-version.min = 'tlsv1.2'
ssl-version.max = 'tlsv1.3'

---- config::config_get_ssl_version_both_forms_configured stdout ----                                                                              
thread 'config::config_get_ssl_version_both_forms_configured' panicked at '                                                                        
                                                                                                                                                   
error: output did not match:                                                                                                                       
1   1     could not load Cargo configuration                                                                                                       
2   2                                                                                                                                              
3   3     Caused by:                                                                                                                               
4   4       could not parse TOML configuration in `[..]/.cargo/config`                                                                             
5   5                                                                                                                                              
6   6     Caused by:                                                                                                                               
7   7       could not parse input as TOML                                                                                                          
8   8                                                                                                                                              
9   9     Caused by:                                                                                                                               
10       -  dotted key attempted to extend non-table type at line 2 column 15                                                                      
    10   +  TOML parse error at line 3, column 1                                                                                                   
    11   +  |                                                                                                                                      
    12   +3 | ssl-version.min = 'tlsv1.2'                                                                                                          
    13   +  | ^                                                                                                                                    
    14   +Duplicate key `ssl-version` in `[]` table                                                                                                
    15   +

as_table_like_ mut?

I'm messing with Cargo.toml files and can't guarantee what fields will exist, so I use a lot of get_mut. I also can't guarantee what style of table is being used, but there isn't a as_table_like_mut.

Any concerns with me adding this?

Dotted keys are not supported

Status

Parse dotted keys in tables
Parse dotted keys in inline tables
Preserve notion of dotted keys
#163
Error when inserting dotted key into table
Error when inserting table into dotted key

The following TOML file is not parsed successfully:

ssh.public-key-path = "C:/Users/andrew.hickman/.ssh/id_rsa.pub"

It fails with

TOML parse error at line 68, column 4
   |
68 | ssh.public-key-path = "C:/Users/andrew.hickman/.ssh/id_rsa.pub"
   |    ^
Unexpected `.`
Expected `=`

However the toml crate parses this correctly, and looking at the ABNF grammar I think it is a valid TOML file

toml = expression *( newline expression )

expression =/ ws keyval ws [ comment ]

dotted-key = simple-key 1*( dot-sep simple-key )

Support parsing all `Cargo.toml` files

This is a pre-req to replacing toml-rs in cargo.

To do this, we might need a feature flag for deviating from the toml standard.

This will require comparing parse results between both parsers across all of crates.io. My assumption is we'd have a command that pulls in both crates and uses the toml_test encoding to compare the resylts

#129
Create toml_test encoding for toml-rs
Create test utility that compares toml-rs against #129
Fix issues as needed, using a feature flag when deviating from TOML spec

toml_edit does not preserve table order

As reported by @lucab in crate-ci/cargo-release#144

Example of a diff where toml_edit re-ordered tables: https://github.com/coreos/afterburn/pull/269/files

Reproduction case using cargo-script

#!/usr/bin/env run-cargo-script
//! ```cargo
//! [dependencies]
//! toml_edit = "0.1"
//! difference = "2.0"
//! ```

fn main () {
    println!("Start");
    let original = r#"
[package]
name = "afterburn"
repository = "https://github.com/coreos/afterburn"
license = "Apache-2.0"
edition = "2018"
authors = [ "Stephen Demos <[email protected]>",
            "Luca Bruno <[email protected]>" ]
description = "A simple cloud provider agent"
version = "4.1.4-alpha.0"

[[bin]]
name = "afterburn"
path = "src/main.rs"

[profile.release]
lto = true

[dependencies]
base64 = "^0.10.1"
byteorder = "1.3"
clap = "2.33"
error-chain = { version = "0.12", default-features = false }
hostname = "0.1"
ipnetwork = "^0.14.0"
mime = "0.3"
nix = "^0.15.0"
openssh-keys = "^0.4.1"
openssl = "^0.10.24"
pnet_base = "^0.22.0"
pnet_datalink = "^0.22.0"
reqwest = "^0.9.19"
serde = "1.0"
serde-xml-rs = "0.3"
serde_derive = "1.0"
serde_json = "1.0"
slog-async = "2.1"
slog-scope = "~4.1"
slog-term = "2.4"
tempdir = "0.3"
tempfile = "^3.0.9"
update-ssh-keys = { version = "^0.5.0", optional = true }
users = "^0.9.1"

[features]
cl-legacy = ["update-ssh-keys"]

[dependencies.slog]
version = "2.5"
features = ["max_level_trace", "release_max_level_info"]

[dev-dependencies]
mockito = "^0.17.1"

[package.metadata.release]
sign-commit = true
upload-doc = false
disable-push = true
disable-publish = true
pre-release-commit-message = "cargo: Afterburn release {{version}}"
pro-release-commit-message = "cargo: development version bump"
tag-message = "Afterburn v{{version}}"
tag-prefix = "v"

    "#;

    let manifest: toml_edit::Document = original.parse().unwrap();
    let new = manifest.to_string();
    difference::assert_diff!(&new, &original, "\n", 0);
}

No validation on date parsing

With #187, we dropped most of our date validation, like 2021-02-31 now works.

Looks like chrono has some pretty complex lookup logic to prevent that

Playground of it erroring

No way to control "decorations"

I needed to convert a TOML doc like

[[bins]]
name = 'native-image'

[bins.target]
type = 'Sdk'
name = 'jdk-graal'

into equivalent form with inline tables:

[[bins]]
name = 'native-image'
target ={ type = 'Sdk', name = 'jdk-graal' }

[[bins]]
name = 'gu'
target ={ type = 'Sdk', name = 'jdk-graal' }

I managed to do it with toml_edit, my solution is insanely dirty, but, thankfully, it works:

fn make_inline_tbls(paths_arr: &mut ArrayOfTables) {
    for x in (0..paths_arr.len()) {
        let sub = paths_arr.get_mut(x).expect("");
        let tgt_raw = sub.entry("target");

        tgt_raw.as_inline_table_mut().map(|e| e.fmt());
        let tgt_table = tgt_raw.as_table().expect("");
        let mut tgt_inline = InlineTable::default();
        tgt_table.iter().for_each(|i| {
            let key = i.0;
            let value = i.1.as_value().expect("").to_owned();
            tgt_inline.get_or_insert(key, value);
        });
        tgt_inline.fmt();


        let mut tgt_val = Value::InlineTable(tgt_inline);
        let tgt_item = Item::Value(tgt_val);
        *tgt_raw = tgt_item;

    }
}

let mut doc = tout.parse::<Document>().expect("invalid doc");
let bins_arr = doc["bins"].as_array_of_tables_mut().expect("xxx");
make_inline_tbls(bins_arr)

But, unfortunately, there is a minor issue with the output doc:

target ={ type = 'Sdk', name = 'jdk-graal' }

There is no space between = and {. Seems like it's possible to add it using decor field but it's private.

Could you please help me?

Allow inserting `serde` types as values

Bringing toml_edit::easy::de into toml_edit and exposing a ValueSerializer would make it easier for editing fields using data types internal to the caller, like cargo_edits Dependency.

Test with raw multiline string is failing on Windows

        thread 'test_raw_multiline_string' panicked at 'assertion failed: `(left == right)`
  left: `Object({"firstnl": Object({"type": String("string"), "value": String("This string has a \' quote character.")}), "multiline": Object({"type": String("string"), "value": String("This string\nhas \' a quote character\nand more than\none newline\nin it.")}), "oneline": Object({"type": String("string"), "value": String("This string has a \' quote character.")})})`,
 right: `Object({"firstnl": Object({"type": String("string"), "value": String("This string has a \' quote character.")}), "multiline": Object({"type": String("string"), "value": String("This string\r\nhas \' a quote character\r\nand more than\r\none newline\r\nin it.")}), "oneline": Object({"type": String("string"), "value": String("This string has a \' quote character.")})})`', tests\test_valid.rs:54:4
note: Run with `RUST_BACKTRACE=1` for a backtrace.

reported by @Boddlnagg in comment

feature request: Array drain

Would be nice if there was an easier way to remove items from an array than having to remove via position.

Could not compile toml_edit due to recursion limit reached

I am trying to install cargo-edit, which fails on trying to compile toml_edit. Building toml_edit by itself also fails. Minimal test case:

bram@raggel:~/Code$ cargo new --bin toml_edit_test
     Created binary (application) `toml_edit_test` project
bram@raggel:~/Code$ cd toml_edit_test/
bram@raggel:~/Code/toml_edit_test$ vi Cargo.toml 
bram@raggel:~/Code/toml_edit_test$ cat Cargo.toml 
[package]
name = "toml_edit_test"
version = "0.1.0"
authors = ["..."]

[dependencies]
toml_edit = "*"
bram@raggel:~/Code/toml_edit_test$ cargo build -vv
[...]
   Compiling toml_edit v0.1.2
     Running `rustc --crate-name toml_edit /home/bram/.cargo/registry/src/github.com-1ecc6299db9ec823/toml_edit-0.1.2/src/lib.rs --crate-type lib --emit=dep-info,link -C debuginfo=2 --cfg 'feature="default"' -C metadata=33d17469c5ea603f -C extra-filename=-33d17469c5ea603f --out-dir /home/bram/Code/toml_edit_test/target/debug/deps -L dependency=/home/bram/Code/toml_edit_test/target/debug/deps --extern combine=/home/bram/Code/toml_edit_test/target/debug/deps/libcombine-a3f87f244ed072d4.rlib --extern chrono=/home/bram/Code/toml_edit_test/target/debug/deps/libchrono-9e8cfa828b060d66.rlib --extern linked_hash_map=/home/bram/Code/toml_edit_test/target/debug/deps/liblinked_hash_map-e0125a89193b31b6.rlib --cap-lints warn`
error: reached the recursion limit while instantiating `<parser::datetime::date_time<combine::easy::Stream<combine::stream::state::State<&str, combine::stream::state::SourcePosition>>> as combine::Parser>::parse_mode::<combine::parser::FirstMode>`

error: aborting due to previous error

error: Could not compile `toml_edit`.

Caused by:
  process didn't exit successfully: `rustc --crate-name toml_edit /home/bram/.cargo/registry/src/github.com-1ecc6299db9ec823/toml_edit-0.1.2/src/lib.rs --crate-type lib --emit=dep-info,link -C debuginfo=2 --cfg feature="default" -C metadata=33d17469c5ea603f -C extra-filename=-33d17469c5ea603f --out-dir /home/bram/Code/toml_edit_test/target/debug/deps -L dependency=/home/bram/Code/toml_edit_test/target/debug/deps --extern combine=/home/bram/Code/toml_edit_test/target/debug/deps/libcombine-a3f87f244ed072d4.rlib --extern chrono=/home/bram/Code/toml_edit_test/target/debug/deps/libchrono-9e8cfa828b060d66.rlib --extern linked_hash_map=/home/bram/Code/toml_edit_test/target/debug/deps/liblinked_hash_map-e0125a89193b31b6.rlib --cap-lints warn` (exit code: 101)
bram@raggel:~/Code/toml_edit_test$ rustc -V
rustc 1.27.0 (3eda71b00 2018-06-19)

I am using Linux x86_64, on a pretty low-specced netbook (2 cores, 4GB RAM). I am curious as to why this fails to compile, as I have installed cargo-edit (and thus toml_edit) on a couple of x86_64 machines using the same rustc version over the last couple of days, which all worked fine. Is rustc's recursion limit dynamic based on the machine's specs? That's the only thing I can think of why compilation fails on this netbook, and not on other machines.

Migrate parser from nom

nom is great for parsing binary formats, but no-so-great for parsing languages and reporting human readable errors. I'm considering combine, pest (procedural branch), peg, larlpop at the moment.

The real "value"

hi.
I want to know if there is a way to get the real value? "a"="s" -> a s
What we get now is "a"="s" ->a "s"，we know that '""' is not part of the value.

Fix grammatical oversight in repo description

Hi @epage! This is so minor, of course, but I'd recommend you change "format preserving" in this repo's description to "format-preserving". It can be slightly confusing at first what is intended to be read. :)

`easy::to_string_pretty` doesn't produce pretty results

Strange extra whitespace in cargo test failure

Unsure if this is a bug in our code or the port of cargo to toml_edit. Needs more investigation

---- cargo_features::wrong_position stdout ----                                                                                                    
running `/home/epage/src/personal/cargo/target/debug/cargo check`                                                                                  
thread 'cargo_features::wrong_position' panicked at '                                                                                              
test failed running `/home/epage/src/personal/cargo/target/debug/cargo check`                                                                      
error: stderr did not match:                                                                                                                       
1   1     error: failed to parse manifest at [..]                                                                                                  
2   2                                                                                                                                              
3   3     Caused by:                                                                                                                               
4        -  cargo-features = ["test-dummy-unstable"] was found in the wrong location: it should be set at the top of Cargo.toml before any tables  
    4    +  cargo-features =  ["test-dummy-unstable"] was found in the wrong location: it should be set at the top of Cargo.toml before any tables

`toml_edit` doesn't properly handle quotes in strings

Run cargo test decoder_compliance -- --noignore and you'll see a test failure for '''' test '''' which should produce ' test 'but instead errors.

Publish new version including combine update?

Hi! Would it be possible to publish a new version of the crate including #107? I'm working to import toml_edit into Fuchsia where we vendor all of our crates, and we'd like to not import the combine 3.x dependency. I'm happy to assist if I can, maybe by updating the changelog?

NLL future-compat warning on nightly

Latest nightly has enabled the NLL migration mode for Edition 2015 code, this is triggering a couple of warnings (that will become errors in the future) in toml_edit 0.1.3:

warning[E0502]: cannot borrow `v` as immutable because it is also borrowed as mutable
  --> /home/travis/.cargo/registry/src/github.com-1ecc6299db9ec823/toml_edit-0.1.3/src/index.rs:55:65
   |
44 |       fn index_or_insert<'v>(&self, v: &'v mut Item) -> &'v mut Item {
   |                          -- lifetime `'v` defined here
45 | /         match *v {
46 | |             Item::ArrayOfTables(ref mut vec) => {
47 | |                 vec.values.get_mut(*self).expect("index out of bounds")
48 | |             }
49 | |             Item::Value(ref mut a) if a.is_array() => a
   | |                         --------- mutable borrow occurs here
...  |
55 | |             _ => panic!("cannot access index {} in {:?}", self, v),
   | |                                                                 ^ immutable borrow occurs here
56 | |         }
   | |_________- returning this value requires that `v.0` is borrowed for `'v`
   |
   = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
   = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future

warning[E0502]: cannot borrow `v` as immutable because it is also borrowed as mutable
  --> /home/travis/.cargo/registry/src/github.com-1ecc6299db9ec823/toml_edit-0.1.3/src/index.rs:88:63
   |
70 |       fn index_or_insert<'v>(&self, v: &'v mut Item) -> &'v mut Item {
   |                          -- lifetime `'v` defined here
...
77 | /         match *v {
78 | |             Item::Table(ref mut t) => t.entry(self).or_insert(Item::None),
79 | |             Item::Value(ref mut v) if v.is_inline_table() => {
   | |                         --------- mutable borrow occurs here
80 | |                 &mut v
...  |
88 | |             _ => panic!("cannot access key {} in {:?}", self, v),
   | |                                                               ^ immutable borrow occurs here
89 | |         }
   | |_________- returning this value requires that `v.0` is borrowed for `'v`
   |
   = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
   = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future

Stack overflow when parsing a deeply nested toml_edit::Document

Basically the same error as seen as toml-rs/toml-rs#428

Reproduction code:

fn main() {
    let brackets = "[".repeat(20000);
    let input_string = format!("x={}", &brackets);
    input_string.parse::<toml_edit::Document>().unwrap();
}

`easy::Value` equality doesn't handle keys being in other orders

Noticed this when porting toml-rs tests. linked_hash_map requires two maps to have keys in the same order to be equal.

Options

easy::Map could have its own equality
We can switch to indexmap, which is what toml-rs uses
- It loses ordering on remove but I suspect that is less of a problem with us tracking table positions. We don't track inline table positions (#163).

Replace value preserving decoration

I have &mut Value and want to replace value preserving decoration.

There is value function, but it always decorate with leading space and returns Item.
There is decorated method, but it is in private formatted module and isn't reexported.

Am I missing anything?

[feature] Table -> InlineTable

Hello! I'm trying to turn

[site]
bucket = ""
entry-point = "workers-site"

into an inline table using toml_edit. Oddly enough, when I parse my toml, I get

Table(Table { items: {"bucket": TableKeyValue { key: Repr { decor: Decor { prefix: "", suffix: " " }, raw_value: "bucket" }, value: Value(String(Formatted { value: "", repr: Repr { decor: Decor { prefix: " ", suffix: "" }, raw_value: "\"\"" } })) }, "entry-point": TableKeyValue { key: Repr { decor: Decor { prefix: "", suffix: " " }, raw_value: "entry-point" }, value: Value(String(Formatted { value: "workers-site", repr: Repr { decor: Decor { prefix: " ", suffix: "" }, raw_value: "\"workers-site\"" } })) }}, decor: Decor { prefix: "\n", suffix: "" }, implicit: false, position: Some(1) })

Type Table(Table... was not I expected to see above, and I suspect it's why calling .as_inline_table() fails on the table provided above. (instead, calling .as_inline_table() returns None).

Any pieces of advice? :)

Remove `chrono` from the public API

This was talked about in #122

Should we define a custom datetime?

I suspect most people are not dealing with datetimes and so having a dependency on chrono is extra bloat.

toml-rs takes an interesting approach to this problem and just made it public

Should we do similar?

This would mean going back on Value having a variant per case.
There is the non-sense case of only having an offset that would fail encoding

#[derive(PartialEq, Clone)]
pub struct Datetime {
    /// Optional date.
    /// Required for: *Offset Date-Time*, *Local Date-Time*, *Local Date*.
    pub date: Option<Date>,

    /// Optional time.
    /// Required for: *Offset Date-Time*, *Local Date-Time*, *Local Time*.
    pub time: Option<Time>,

    /// Optional offset.
    /// Required for: *Offset Date-Time*.
    pub offset: Option<Offset>,
}

#[derive(PartialEq, Clone)]
pub struct Date {
    /// Year: four digits
    pub year: u16,
    /// Month: 1 to 12
    pub month: u8,
    /// Day: 1 to {28, 29, 30, 31} (based on month/year)
    pub day: u8,
}

pub struct Time {
    /// Hour: 0 to 23
    pub hour: u8,
    /// Minute: 0 to 59
    pub minute: u8,
    /// Second: 0 to {58, 59, 60} (based on leap second rules)
    pub second: u8,
    /// Nanosecond: 0 to 999_999_999
    pub nanosecond: u32,
}

#[derive(PartialEq, Clone)]
pub enum Offset {
    /// > A suffix which, when applied to a time, denotes a UTC offset of 00:00;
    /// > often spoken "Zulu" from the ICAO phonetic alphabet representation of
    /// > the letter "Z". --- [RFC 3339 section 2]
    ///
    /// [RFC 3339 section 2]: https://datatracker.ietf.org/doc/html/rfc3339#section-2
    Z,

    /// Offset between local time and UTC
    Custom {
        /// Hours: -12 to +12
        hours: i8,

        /// Minutes: 0 to 59
        minutes: u8,
    },
}

Improve the documentation

Add more examples to address #42.

reuse tokens from toml crate

cc rust-lang/cargo#5611 (comment)

Allow inserting where we carry over the original formatting

For example, if we insert an Integer over an integer, we keep the decor.

If we merge a Table over a Table, we keep the type (inline vs standard, dotted) and recursively keep formatting of items in the table.

Inconsistent .len() on Array and ArrayOfTables

Should we return values.len() or values.filter(!is_none).len()?

Performance test against `toml-rs`

The cargo team is concerned about negatively impacting cargos performance in switching to toml_edit. Specifically, they are concerned about parsing large dependency trees.

It is unclear how much impact toml-rs has on the whole operation and how much would be solved by

Storing immutable Cargo.toml files in binary
Moving strings in cargo to smol_str or kstring

But we should at least be able to say how we compare with the same API (#129)

#129
Identify test cases to compare toml_edit, #129, and toml-rs
Bring performance in line with toml-rs

Show table that duplicate key errors come from

This is a regression in error reporting from toml-rs as caught by cargo's test suite

---- git::invalid_git_dependency_manifest stdout ----                                                                                              
running `/home/epage/src/personal/cargo/target/debug/cargo build`                                                                                  
thread 'git::invalid_git_dependency_manifest' panicked at '                                                                                        
test failed running `/home/epage/src/personal/cargo/target/debug/cargo build`                                                                      
error: stderr did not match:                                                                                                                       
1   1         Updating git repository `file:///home/epage/src/personal/cargo/target/tmp/cit/t1037/dep1`                                            
2   2     error: failed to get `dep1` as a dependency of package `foo v0.5.0 ([..])`                                                               
3   3                                                                                                                                              
4   4     Caused by:                                                                                                                               
5   5       failed to load source for dependency `dep1`                                                                                            
6   6                                                                                                                                              
7   7     Caused by:                                                                                                                               
8   8       Unable to update file:///home/epage/src/personal/cargo/target/tmp/cit/t1037/dep1                                                       
9   9                                                                                                                                              
10  10    Caused by:                                                                                                                               
11  11      failed to parse manifest at `[..]`                           
12  12                                                                                                                                             
13  13    Caused by:                                                                                                                               
14  14      could not parse input as TOML                                                                                                          
15  15                                                                                                                                             
16  16    Caused by:                                                                                                                               
17       -  duplicate key: `categories` for key `project` at line 10 column 21                                                                     
    17   +  TOML parse error at line 8, column 21                                                                                                  
    18   +    |                                                                                                                                    
    19   +  8 |                     categories = ["algorithms"]                                                                                    
    20   +    |                     ^                                                                                                              
    21   +  Duplicate key `categories` in `<unknown>` table                                                                                        
    22   +

Enforce constraints

Problems

Currently, toml spec does not have any positional constraints on tables (cf toml/issues/446). E.g. this is a valid toml:

[[bin]] # bin 1
[a.b.c.d]
[a]
[other.table]
[a.b.c.e]
[[bin]] # bin 2
[a.b.c]
[[bin]] # bin 3

This greatly complicates internal design of toml_edit, e.g. we have to store this order somewhere outside of the tables (document), and in order to support table insertion and deletion on Table, we have to store a pointer to the document in it. That's why we don't allow a user to own a Table, providing only a (mut) ref to a Table.

If we are free to reorder the tables when printing them, we can simplify the design and get rid of the no-ownership constraint. This, in turn, would allow us to have a single Value enum and implement serde_json-like nice API and get rid of unsafe code!

Another annoying thing is whitespaces in headers.

[ 'this  '   . is . a .valid.    "header..." ]

In order to preserve this layout, we have to store the whole header in the Table, but then Table assignment would be unfortunate, because header will also be mutated, while in hashmap, storing subtable index, there still be the old key.

Proposal

Allow any order when parsing the document, but internally store all children after theirs parent. Also store array of tables in one place. When printing the toml from above, it would look like:

[[bin]] # bin 1
[[bin]] # bin 2
[[bin]] # bin 3
[a]
[a.b.c]
[a.b.c.e]
[a.b.c.d]
[other.table]

Unresolved: should we sort the children as well?

Drop all whitespaces in the header.

['this  '.is.a.valid."header..."]

cc @killercup, what do you think?

Non-nested array is parsed as nested

I don't understand why the following toml parses the way it does, is it a bug?

[table]
array = ["one", "two", "three"]

extern crate toml_edit;

use toml_edit::{Document};

fn main() {
    let toml = r#"
[table]
array = ["one", "two", "three"]
    "#;
    println!("{:#?}", toml.parse::<Document>().unwrap());
}

Output:

Document {
    root: Table(
        Table {
            items: {
                "table": TableKeyValue {
                    key: Repr {
                        decor: Decor {
                            prefix: "",
                            suffix: " "
                        },
                        raw_value: "table"
                    },
                    value: Table(
                        Table {
                            items: {
                                "array": TableKeyValue {
                                    key: Repr {
                                        decor: Decor {
                                            prefix: "",
                                            suffix: " "
                                        },
                                        raw_value: "array"
                                    },
                                    value: Value(
                                        Array(
                                            Array {
                                                values: [
                                                    Value(
                                                        String(
                                                            Formatted {
                                                                value: "one",
                                                                repr: Repr {
                                                                    decor: Decor {
                                                                        prefix: "",
                                                                        suffix: ""
                                                                    },
                                                                    raw_value: "\"one\""
                                                                }
                                                            }
                                                        )
                                                    ),
                                                    Value(
                                                        String(
                                                            Formatted {
                                                                value: "two",
                                                                repr: Repr {
                                                                    decor: Decor {
                                                                        prefix: " ",
                                                                        suffix: ""
                                                                    },
                                                                    raw_value: "\"two\""
                                                                }
                                                            }
                                                        )
                                                    ),
                                                    Value(
                                                        String(
                                                            Formatted {
                                                                value: "three",
                                                                repr: Repr {
                                                                    decor: Decor {
                                                                        prefix: " ",
                                                                        suffix: ""
                                                                    },
                                                                    raw_value: "\"three\""
                                                                }
                                                            }
                                                        )
                                                    )
                                                ],
                                                trailing: "",
                                                trailing_comma: false,
                                                decor: Decor {
                                                    prefix: " ",
                                                    suffix: ""
                                                }
                                            }
                                        )
                                    )
                                }
                            },
                            decor: Decor {
                                prefix: "\n",
                                suffix: ""
                            },
                            implicit: false
                        }
                    )
                }
            },
            decor: Decor {
                prefix: "",
                suffix: ""
            },
            implicit: false
        }
    ),
    trailing: "    "
}

Notice the Array inside Array.

Missing a leading space on the value of a key-value pair?

I'm building a toml document through the API instead of the parser, and I'm wondering if I'm doing something wrong because I end up with key-value pairs that look like this: key ="my value" and key =["my array"]. From the looks of the formatted.rs code, there should be a space at the start of the value, but I'm not sure why it isn't working for me. Here is a minimal example:

extern crate toml_edit;
use toml_edit::{Array, Document, Item, Table, Value};

fn main() {
    let mut doc = Document::new();
    let mut root_table = Table::new();

    // items for the table
    let mut table = Table::new();
    let mut array = Array::default();
    array.push(Value::from("first-element"));
    *table.entry("my-key") = Item::Value(Value::from("my-value".to_string()));
    *table.entry("my-array") = Item::Value(Value::Array(array));

    *root_table.entry("my-table") = Item::Table(table);
    doc.root = Item::Table(root_table);
    println!("{}", doc);
}

and this is what I end up with:

[my-table]
my-key ="my-value"
my-array =["first-element"]

Replacing toml-rs to toml_edit (question)

Hey guys, I'm working on replacing toml-rs for the ability to preserve the order and comments on the file, so toml_edit looked like the perfect tool for it.
I tried to use the easy module, because i thought that it was the toml-rs api but with the toml_edit behaviour, so I wouldn't have to change much code, since the code base written with toml-rs is quite large, but it kept the toml-rs behaviour of getting rid of comments and changing the order of things.
So, what I wanted to ask you guys is if the easy module is meant to preserve comments and like the “main” library or is it supposed to work exactly as toml-rs? And if easy is tooml-rs inside toml_edit, do you guys have any advice on replacing toml-rs?

Decouple end users from our iterator implementations

Right now, our iterators are type aliases. Some iterators have their implementation partially hidden via Box but that still gets exposed.

We should provide newtypes for our iterators so we are free to change them (like optimizing by removing Box) without causing a breaking change.

Iterating on toml_edits API

In working on TOML 1.0 compliance, some things have come up (#120)

External crates need access to a programmatically meaningful version of each date/time variant
- Even if cfg(test) tricks work for black box tests, I'm going to be later be using toml_edit in toml_test as the baseline for testing encoders and validating against toml-rs
- In theory, toml users will want this as we make this crate viable for format-preserving and regular use
Nesting all date-time variants into a single Value::DateTime is verbose and we don't do it for integer/fl;oat (#120, #116)
As we implement toml-rs on top of toml_edit, where should it live? A separate crate, a toml_edit::simple module?
End-users having to distinguish between Table and InlineTable is already a challenging and adding dotted keys is going to make this more challenging
Dotted keys opens up additional API questions (#73)

With additional inputs

Enforcing TOML rules through types is already leaky with get_mut (#110) and IndexMut

Suggest quoted strings to users in errors

This is a regression compared to toml-rs as found by cargo's test suite

---- config::config_get_list stdout ----                                                                                                           
thread 'config::config_get_list' panicked at '                                                                                                     
                                                                                                                                                   
error: output did not match:                                                                                                                       
1        -error in environment variable `CARGO_BAD_ENV`: could not parse TOML list: invalid TOML value, did you mean to use a quoted string? at lin
e 1 column 8                                                                                                                                       
    1    +error in environment variable `CARGO_BAD_ENV`: could not parse TOML list: TOML parse error at line 1, column 8                           
    2    +  |                                                            
    3    +1 | value=[zzz]                                                
    4    +  |        ^                                                   
    5    +Unexpected `z`                                                 
    6    +Expected `a newline` or `#`