Remove toml as a public dependency

This removes toml as a public dependency. This reduces the exposure of
the public API, reduces exposure of internal implementation, and makes
it easier to make semver-incompatible changes to toml.

This is accomplished through a variety of changes:

- `get` and `get_mut` are removed.
- `get_deserialized_opt` is renamed to `get`.
- Dropped the AsRef for `get_deserialized_opt` for ergonomics, since
  using an `&` for a String is not too much to ask, and the other
  generic arg needs to be specified in a fair number of situations.
- Removed deprecated `get_deserialized`.
- Dropped `TomlExt` from the public API.
- Removed `get_renderer` and `get_preprocessor` since they were trivial
  wrappers over `get`.

Author: ehuss

Cargo.lock

@@ -24,32 +24,32 @@
 //! [build]
 //! src = "out"
 //!
-//! [other-table.foo]
+//! [preprocessor.my-preprocessor]
 //! bar = 123
 //! "#;
 //!
 //! // load the `Config` from a toml string
 //! let mut cfg = Config::from_str(src)?;
 //!
 //! // retrieve a nested value
-//! let bar = cfg.get("other-table.foo.bar").cloned();
-//! assert_eq!(bar, Some(Value::Integer(123)));
+//! let bar = cfg.get::<i32>("preprocessor.my-preprocessor.bar")?;
+//! assert_eq!(bar, Some(123));
 //!
 //! // Set the `output.html.theme` directory
-//! assert!(cfg.get("output.html").is_none());
+//! assert!(cfg.get::<Value>("output.html")?.is_none());
 //! cfg.set("output.html.theme", "./themes");
 //!
 //! // then load it again, automatically deserializing to a `PathBuf`.
-//! let got: Option<PathBuf> = cfg.get_deserialized_opt("output.html.theme")?;
+//! let got = cfg.get("output.html.theme")?;
 //! assert_eq!(got, Some(PathBuf::from("./themes")));
 //! # Ok(())
 //! # }
 //! # run().unwrap()
 //! ```
 
+use crate::utils::TomlExt;
 use crate::utils::log_backtrace;
-use crate::utils::toml_ext::TomlExt;
-use anyhow::{Context, Error, Result, bail};
+use anyhow::{Context, Error, Result};
 use log::{debug, trace, warn};
 use serde::{Deserialize, Deserializer, Serialize, Serializer};
 use std::collections::HashMap;
@@ -154,18 +154,28 @@ impl Config {
         }
     }
 
-    /// Fetch an arbitrary item from the `Config` as a `toml::Value`.
+    /// Get a value from the configuration.
     ///
-    /// You can use dotted indices to access nested items (e.g.
-    /// `output.html.playground` will fetch the "playground" out of the html output
-    /// table).
-    pub fn get(&self, key: &str) -> Option<&Value> {
-        self.rest.read(key)
-    }
-
-    /// Fetch a value from the `Config` so you can mutate it.
-    pub fn get_mut(&mut self, key: &str) -> Option<&mut Value> {
-        self.rest.read_mut(key)
+    /// This fetches a value from the book configuration. The key can have
+    /// dotted indices to access nested items (e.g. `output.html.playground`
+    /// will fetch the "playground" out of the html output table).
+    ///
+    /// This does not have access to the [`Config::book`], [`Config::build`],
+    /// or [`Config::rust`] fields.
+    ///
+    /// Returns `Ok(None)` if the field is not set.
+    ///
+    /// Returns `Err` if it fails to deserialize.
+    pub fn get<'de, T: Deserialize<'de>>(&self, name: &str) -> Result<Option<T>> {
+        self.rest
+            .read(name)
+            .map(|value| {
+                value
+                    .clone()
+                    .try_into()
+                    .with_context(|| "Couldn't deserialize the value")
+            })
+            .transpose()
     }
 
     /// Convenience method for getting the html renderer's configuration.
@@ -177,7 +187,7 @@ impl Config {
     #[doc(hidden)]
     pub fn html_config(&self) -> Option<HtmlConfig> {
         match self
-            .get_deserialized_opt("output.html")
+            .get("output.html")
             .with_context(|| "Parsing configuration [output.html]")
         {
             Ok(Some(config)) => Some(config),
@@ -189,35 +199,12 @@ impl Config {
         }
     }
 
-    /// Deprecated, use get_deserialized_opt instead.
-    #[deprecated = "use get_deserialized_opt instead"]
-    pub fn get_deserialized<'de, T: Deserialize<'de>, S: AsRef<str>>(&self, name: S) -> Result<T> {
-        let name = name.as_ref();
-        match self.get_deserialized_opt(name)? {
-            Some(value) => Ok(value),
-            None => bail!("Key not found, {:?}", name),
-        }
-    }
-
-    /// Convenience function to fetch a value from the config and deserialize it
-    /// into some arbitrary type.
-    pub fn get_deserialized_opt<'de, T: Deserialize<'de>, S: AsRef<str>>(
-        &self,
-        name: S,
-    ) -> Result<Option<T>> {
-        let name = name.as_ref();
-        self.get(name)
-            .map(|value| {
-                value
-                    .clone()
-                    .try_into()
-                    .with_context(|| "Couldn't deserialize the value")
-            })
-            .transpose()
-    }
-
     /// Set a config key, clobbering any existing values along the way.
     ///
+    /// The key can have dotted indices for nested items (e.g.
+    /// `output.html.playground` will set the "playground" in the html output
+    /// table).
+    ///
     /// The only way this can fail is if we can't serialize `value` into a
     /// `toml::Value`.
     pub fn set<S: Serialize, I: AsRef<str>>(&mut self, index: I, value: S) -> Result<()> {
@@ -239,18 +226,6 @@ impl Config {
         Ok(())
     }
 
-    /// Get the table associated with a particular renderer.
-    pub fn get_renderer<I: AsRef<str>>(&self, index: I) -> Option<&Table> {
-        let key = format!("output.{}", index.as_ref());
-        self.get(&key).and_then(Value::as_table)
-    }
-
-    /// Get the table associated with a particular preprocessor.
-    pub fn get_preprocessor<I: AsRef<str>>(&self, index: I) -> Option<&Table> {
-        let key = format!("preprocessor.{}", index.as_ref());
-        self.get(&key).and_then(Value::as_table)
-    }
-
     fn from_legacy(mut table: Value) -> Config {
         let mut cfg = Config::default();
 
@@ -1021,32 +996,16 @@ mod tests {
         };
 
         let cfg = Config::from_str(src).unwrap();
-        let got: RandomOutput = cfg.get_deserialized_opt("output.random").unwrap().unwrap();
+        let got: RandomOutput = cfg.get("output.random").unwrap().unwrap();
 
         assert_eq!(got, should_be);
 
-        let got_baz: Vec<bool> = cfg
-            .get_deserialized_opt("output.random.baz")
-            .unwrap()
-            .unwrap();
+        let got_baz: Vec<bool> = cfg.get("output.random.baz").unwrap().unwrap();
         let baz_should_be = vec![true, true, false];
 
         assert_eq!(got_baz, baz_should_be);
     }
 
-    #[test]
-    fn mutate_some_stuff() {
-        // really this is just a sanity check to make sure the borrow checker
-        // is happy...
-        let src = COMPLEX_CONFIG;
-        let mut config = Config::from_str(src).unwrap();
-        let key = "output.html.playground.editable";
-
-        assert_eq!(config.get(key).unwrap(), &Value::Boolean(true));
-        *config.get_mut(key).unwrap() = Value::Boolean(false);
-        assert_eq!(config.get(key).unwrap(), &Value::Boolean(false));
-    }
-
     /// The config file format has slightly changed (metadata stuff is now under
     /// the `book` table instead of being at the top level) so we're adding a
     /// **temporary** compatibility check. You should be able to still load the
@@ -1106,10 +1065,10 @@ mod tests {
         let key = "foo.bar.baz";
         let value = "Something Interesting";
 
-        assert!(cfg.get(key).is_none());
+        assert!(cfg.get::<i32>(key).unwrap().is_none());
         cfg.set(key, value).unwrap();
 
-        let got: String = cfg.get_deserialized_opt(key).unwrap().unwrap();
+        let got: String = cfg.get(key).unwrap().unwrap();
         assert_eq!(got, value);
     }
 
@@ -1159,18 +1118,15 @@ mod tests {
         let key = "foo.bar";
         let value = "baz";
 
-        assert!(cfg.get(key).is_none());
+        assert!(cfg.get::<String>(key).unwrap().is_none());
 
         let encoded_key = encode_env_var(key);
         // TODO: This is unsafe, and should be rewritten to use a process.
         unsafe { env::set_var(encoded_key, value) };
 
         cfg.update_from_env();
 
-        assert_eq!(
-            cfg.get_deserialized_opt::<String, _>(key).unwrap().unwrap(),
-            value
-        );
+        assert_eq!(cfg.get::<String>(key).unwrap().unwrap(), value);
     }
 
     #[test]
@@ -1180,20 +1136,15 @@ mod tests {
         let value = json!({"array": [1, 2, 3], "number": 13.37});
         let value_str = serde_json::to_string(&value).unwrap();
 
-        assert!(cfg.get(key).is_none());
+        assert!(cfg.get::<serde_json::Value>(key).unwrap().is_none());
 
         let encoded_key = encode_env_var(key);
         // TODO: This is unsafe, and should be rewritten to use a process.
         unsafe { env::set_var(encoded_key, value_str) };
 
         cfg.update_from_env();
 
-        assert_eq!(
-            cfg.get_deserialized_opt::<serde_json::Value, _>(key)
-                .unwrap()
-                .unwrap(),
-            value
-        );
+        assert_eq!(cfg.get::<serde_json::Value>(key).unwrap().unwrap(), value);
     }
 
     #[test]

crates/mdbook-core/src/config.rs

@@ -9,7 +9,9 @@ use std::sync::LazyLock;
 
 pub mod fs;
 mod string;
-pub mod toml_ext;
+mod toml_ext;
+
+pub(crate) use self::toml_ext::TomlExt;
 
 pub use self::string::{
     take_anchored_lines, take_lines, take_rustdoc_include_anchored_lines,

crates/mdbook-core/src/utils/mod.rs

@@ -3,11 +3,9 @@
 use toml::value::{Table, Value};
 
 /// Helper for working with toml types.
-pub trait TomlExt {
+pub(crate) trait TomlExt {
     /// Read a dotted key.
     fn read(&self, key: &str) -> Option<&Value>;
-    /// Read a dotted key for a mutable value.
-    fn read_mut(&mut self, key: &str) -> Option<&mut Value>;
     /// Insert with a dotted key.
     fn insert(&mut self, key: &str, value: Value);
     /// Delete a dotted key value.
@@ -23,14 +21,6 @@ impl TomlExt for Value {
         }
     }
 
-    fn read_mut(&mut self, key: &str) -> Option<&mut Value> {
-        if let Some((head, tail)) = split(key) {
-            self.get_mut(head)?.read_mut(tail)
-        } else {
-            self.get_mut(key)
-        }
-    }
-
     fn insert(&mut self, key: &str, value: Value) {
         if !self.is_table() {
             *self = Value::Table(Table::new());

crates/mdbook-core/src/utils/toml_ext.rs

@@ -17,6 +17,7 @@ mdbook-preprocessor.workspace = true
 mdbook-renderer.workspace = true
 mdbook-summary.workspace = true
 regex.workspace = true
+serde.workspace = true
 serde_json.workspace = true
 shlex.workspace = true
 tempfile.workspace = true

crates/mdbook-driver/Cargo.toml

@@ -10,7 +10,6 @@ use std::fs;
 use std::io::{self, ErrorKind};
 use std::path::{Path, PathBuf};
 use std::process::{Command, Stdio};
-use toml::Value;
 
 pub use self::markdown_renderer::MarkdownRenderer;
 
@@ -108,8 +107,9 @@ impl CmdRenderer {
             let optional_key = format!("output.{}.optional", self.name);
 
             let is_optional = match ctx.config.get(&optional_key) {
-                Some(Value::Boolean(value)) => *value,
-                _ => false,
+                Ok(Some(value)) => value,
+                Err(e) => bail!("expected bool for `{optional_key}`: {e}"),
+                Ok(None) => false,
             };
 
             if is_optional {