Skip to content

Commit

Permalink
fix(edit): Deprecate easy for toml
Browse files Browse the repository at this point in the history 
Fixes #340
  • Loading branch information
@epage
epage committed Jan 20, 2023
1 parent 12503c8 commit 9978e0a
Show file tree
Hide file tree
Showing 5 changed files with 15 additions and 167 deletions.
26 changes: 2 additions & 24 deletions crates/toml_edit/src/easy/macros.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,30 +2,8 @@ pub use serde::de::{Deserialize, IntoDeserializer};

use crate::easy::value::{Array, Table, Value};

/// Construct a [`toml_edit::easy::Value`] from TOML syntax.
///
/// [`toml_edit::easy::Value`]: value/enum.Value.html
///
/// ```rust
/// let cargo_toml = toml_edit::easy::toml! {
/// [package]
/// name = "toml"
/// version = "0.4.5"
/// authors = ["Alex Crichton <[email protected]>"]
///
/// [badges]
/// travis-ci = { repository = "alexcrichton/toml-rs" }
///
/// [dependencies]
/// serde = "1.0"
///
/// [dev-dependencies]
/// serde_derive = "1.0"
/// serde_json = "1.0"
/// };
///
/// println!("{:#?}", cargo_toml);
/// ```
#[doc(hidden)]
#[deprecated(since = "0.18.0", note = "Replaced with `toml::toml!`")]
#[macro_export]
macro_rules! toml {
($($toml:tt)+) => {{
Expand Down
3 changes: 2 additions & 1 deletion crates/toml_edit/src/easy/map.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,8 @@ use serde::{de, ser};

use crate::easy::value::Value;

/// Represents a TOML key/value type.
#[doc(hidden)]
#[deprecated(since = "0.18.0", note = "Replaced with `toml::map::Map`")]
pub struct Map<K, V> {
map: MapImpl<K, V>,
}
Expand Down
137 changes: 3 additions & 134 deletions crates/toml_edit/src/easy/mod.rs
View file
Original file line number Diff line number Diff line change
@@ -1,137 +1,6 @@
//! A [TOML]-parsing library
//!
//! This library implements a [TOML] v0.5.0 compatible parser,
//! primarily supporting the [`serde`] library for encoding/decoding
//! various types in Rust
//!
//! **NOTE:** Unlike the core `toml_edit` API, this is not format preserving but is a drop-in
//! replacement for [toml-rs](https://github.com/alexcrichton/toml-rs) for those needing both
//! `toml_edit` and `toml-rs` but want either consistency in behavior or to reduce their
//! dependencies.
//!
//! TOML itself is a simple, ergonomic, and readable configuration format:
//!
//! ```toml
//! [package]
//! name = "toml"
//! version = "0.4.2"
//! authors = ["Alex Crichton <[email protected]>"]
//!
//! [dependencies]
//! serde = "1.0"
//! ```
//!
//! The TOML format tends to be relatively common throughout the Rust community
//! for configuration, notably being used by [Cargo], Rust's package manager.
//!
//! ## TOML values
//!
//! A value in TOML is represented with the [`Value`] enum in this crate.
//!
//! TOML is similar to JSON with the notable addition of a [`Datetime`][crate::Datetime]
//! type. In general, TOML and JSON are interchangeable in terms of
//! formats.
//!
//! ## Parsing TOML
//!
//! The easiest way to parse a TOML document is via the [`Value`] type:
//!
//! ```rust
//! use toml_edit::easy::Value;
//!
//! let value = "foo = 'bar'".parse::<Value>().unwrap();
//!
//! assert_eq!(value["foo"].as_str(), Some("bar"));
//! ```
//!
//! The [`Value`] type implements a number of convenience methods and
//! traits; the example above uses [`FromStr`][std::str::FromStr] to parse a [`str`] into a
//! [`Value`].
//!
//! ## Deserialization and Serialization
//!
//! This crate supports [`serde`] 1.0 with a number of
//! implementations of the `Deserialize`, `Serialize`, `Deserializer`, and
//! `Serializer` traits. Namely, you'll find:
//!
//! * `Deserialize for Value`
//! * `Serialize for Value`
//! * `Deserialize for Datetime`
//! * `Serialize for Datetime`
//! * `Deserializer for de::Deserializer`
//! * `Serializer for ser::Serializer`
//! * `Deserializer for Value`
//!
//! This means that you can use Serde to deserialize/serialize the
//! [`Value`] type as well as the [`Datetime`][crate::Datetime] type in this crate. You can also
//! use the [`Deserializer`], [`ValueSerializer`], or [`Value`] type itself to act as
//! a deserializer/serializer for arbitrary types.
//!
//! An example of deserializing with TOML is:
//!
//! ```rust
//! use serde::Deserialize;
//!
//! #[derive(Deserialize)]
//! struct Config {
//! ip: String,
//! port: Option<u16>,
//! keys: Keys,
//! }
//!
//! #[derive(Deserialize)]
//! struct Keys {
//! github: String,
//! travis: Option<String>,
//! }
//!
//! let config: Config = toml_edit::easy::from_str(r#"
//! ip = '127.0.0.1'
//!
//! [keys]
//! github = 'xxxxxxxxxxxxxxxxx'
//! travis = 'yyyyyyyyyyyyyyyyy'
//! "#).unwrap();
//!
//! assert_eq!(config.ip, "127.0.0.1");
//! assert_eq!(config.port, None);
//! assert_eq!(config.keys.github, "xxxxxxxxxxxxxxxxx");
//! assert_eq!(config.keys.travis.as_ref().unwrap(), "yyyyyyyyyyyyyyyyy");
//! ```
//!
//! You can serialize types in a similar fashion:
//!
//! ```rust
//! use serde::Serialize;
//!
//! #[derive(Serialize)]
//! struct Config {
//! ip: String,
//! port: Option<u16>,
//! keys: Keys,
//! }
//!
//! #[derive(Serialize)]
//! struct Keys {
//! github: String,
//! travis: Option<String>,
//! }
//!
//! let config = Config {
//! ip: "127.0.0.1".to_string(),
//! port: None,
//! keys: Keys {
//! github: "xxxxxxxxxxxxxxxxx".to_string(),
//! travis: Some("yyyyyyyyyyyyyyyyy".to_string()),
//! },
//! };
//!
//! let toml = toml_edit::easy::to_string(&config).unwrap();
//! ```
//!
//! [TOML]: https://github.com/toml-lang/toml
//! [Cargo]: https://crates.io/
//! [`serde`]: https://serde.rs/
#![doc(hidden)]
#![deprecated(since = "0.18.0", note = "Replaced with `toml::Value`")]
#![allow(deprecated)]

mod datetime;

Expand Down
11 changes: 6 additions & 5 deletions crates/toml_edit/src/easy/value.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,8 @@ pub use crate::easy::datetime::*;
use crate::easy::map::Entry;
pub use crate::easy::map::Map;

/// Representation of a TOML value.
#[doc(hidden)]
#[deprecated(since = "0.18.0", note = "Replaced with `toml::Value`")]
#[derive(PartialEq, Clone, Debug, serde::Serialize)]
#[serde(untagged)]
pub enum Value {
Expand All @@ -34,12 +35,12 @@ pub enum Value {
Table(Table),
}

/// Type representing a TOML array, payload of the `Value::Array` variant
#[doc(hidden)]
#[deprecated(since = "0.18.0", note = "Replaced with `toml::value::Array`")]
pub type Array = Vec<Value>;

/// Type representing a TOML table, payload of the `Value::Table` variant.
/// By default it is backed by a BTreeMap, enable the `preserve_order` feature
/// to use a LinkedHashMap instead.
#[doc(hidden)]
#[deprecated(since = "0.18.0", note = "Replaced with `toml::Table`")]
pub type Table = Map<String, Value>;

impl Value {
Expand Down
5 changes: 2 additions & 3 deletions crates/toml_edit/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,7 @@
//! documents, while preserving comments, spaces *and
//! relative order* or items.
//!
//! It is primarily tailored to the needs of [cargo-edit](https://github.com/killercup/cargo-edit/).
//!
//! If you also need the ease of a more traditional API, see the [`easy`] module.
//! If you also need the ease of a more traditional API, see the [`toml`] crate.
//!
//! # Example
//!
Expand Down Expand Up @@ -62,6 +60,7 @@
//! * Scattered array of tables (tables are reordered by default, see [test]).
//! * Order of dotted keys, see [issue](https://github.com/ordian/toml_edit/issues/163).
//!
//! [toml]: https://docs.rs/toml/latest/toml/
//! [test]: https://github.com/ordian/toml_edit/blob/f09bd5d075fdb7d2ef8d9bb3270a34506c276753/tests/test_valid.rs#L84
mod array;
Expand Down

0 comments on commit 9978e0a

Please sign in to comment.