aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--src/lib.rs2
-rw-r--r--src/ser.rs74
2 files changed, 71 insertions, 5 deletions
diff --git a/src/lib.rs b/src/lib.rs
index ee4e961..c4a7e9d 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -161,7 +161,7 @@ mod datetime;
pub mod ser;
#[doc(no_inline)]
-pub use ser::{to_string, to_vec, Serializer};
+pub use ser::{to_string, to_string_pretty, to_vec, Serializer};
pub mod de;
#[doc(no_inline)]
pub use de::{from_slice, from_str, Deserializer};
diff --git a/src/ser.rs b/src/ser.rs
index 283fee9..a267b3a 100644
--- a/src/ser.rs
+++ b/src/ser.rs
@@ -93,6 +93,18 @@ pub fn to_string<T: ?Sized>(value: &T) -> Result<String, Error>
Ok(dst)
}
+/// Serialize the given data structure as a "pretty" String of TOML.
+///
+/// This is identical to `to_string` except the output string has a more
+/// "pretty" output. See `Serializer::pretty` for more details.
+pub fn to_string_pretty<T: ?Sized>(value: &T) -> Result<String, Error>
+ where T: ser::Serialize,
+{
+ let mut dst = String::with_capacity(128);
+ value.serialize(&mut Serializer::pretty(&mut dst))?;
+ Ok(dst)
+}
+
/// Errors that can occur when serializing a type.
#[derive(Debug, PartialEq, Eq, Clone)]
pub enum Error {
@@ -226,9 +238,12 @@ impl<'a> Serializer<'a> {
/// Instantiate a "pretty" formatter
///
- /// By default this will use :
- /// - pretty strings
- /// - arrays with an indentation of 4 and a trailing comma
+ /// By default this will use:
+ ///
+ /// - pretty strings: strings with newlines will use the `'''` syntax. See
+ /// `Serializer::pretty_string`
+ /// - pretty arrays: each item in arrays will be on a newline, have an indentation of 4 and
+ /// have a trailing comma. See `Serializer::pretty_array`
pub fn pretty(dst: &'a mut String) -> Serializer<'a> {
Serializer {
dst: dst,
@@ -241,12 +256,59 @@ impl<'a> Serializer<'a> {
}
/// Enable or Disable pretty strings
+ ///
+ /// If enabled, strings with one or more newline character will use the `'''` syntax.
+ ///
+ /// # Examples
+ ///
+ /// Instead of:
+ ///
+ /// ```toml,no_run
+ /// single = "no newlines"
+ /// text = "\nfoo\nbar\n"
+ /// ```
+ ///
+ /// You will have:
+ ///
+ /// ```toml,no_run
+ /// single = "no newlines"
+ /// text = '''
+ /// foo
+ /// bar
+ /// '''
+ /// ```
pub fn pretty_string(&mut self, value: bool) -> &mut Self {
self.settings.pretty_string = value;
self
}
/// Enable or Disable pretty arrays
+ ///
+ /// If enabled, arrays will always have each item on their own line.
+ ///
+ /// Some specific features can be controlled via other builder methods:
+ ///
+ /// - `Serializer::pretty_array_indent`: set the indent to a value other
+ /// than 4.
+ /// - `Serializer::pretty_array_trailing_comma`: enable/disable the trailing
+ /// comma on the last item.
+ ///
+ /// # Examples
+ ///
+ /// Instead of:
+ ///
+ /// ```toml,no_run
+ /// array = ["foo", "bar"]
+ /// ```
+ ///
+ /// You will have:
+ ///
+ /// ```toml,no_run
+ /// array = [
+ /// "foo",
+ /// "bar",
+ /// ]
+ /// ```
pub fn pretty_array(&mut self, value: bool) -> &mut Self {
self.settings.array = Some(if value {
ArraySettings::pretty()
@@ -256,7 +318,9 @@ impl<'a> Serializer<'a> {
self
}
- /// Set the indent to value for pretty arrays
+ /// Set the indent for pretty arrays
+ ///
+ /// See `Serializer::pretty_array` for more details.
pub fn pretty_array_indent(&mut self, value: usize) -> &mut Self {
let use_default = if let &mut Some(ref mut a) = &mut self.settings.array {
a.indent = value;
@@ -274,6 +338,8 @@ impl<'a> Serializer<'a> {
}
/// Specify whether to use a trailing comma when serializing pretty arrays
+ ///
+ /// See `Serializer::pretty_array` for more details.
pub fn pretty_array_trailing_comma(&mut self, value: bool) -> &mut Self {
let use_default = if let &mut Some(ref mut a) = &mut self.settings.array {
a.trailing_comma = value;