feat: SectionMut::push_with_comment(key, comment) to add a new variable with a comment.

This is useful for providing more information about a value at hand, especially if it was
added programmatically and then shows up in the configuration.

Author: Byron

git-config/src/file/mutable/section.rs

@@ -28,9 +28,26 @@ pub struct SectionMut<'a, 'event> {
 
 /// Mutating methods.
 impl<'a, 'event> SectionMut<'a, 'event> {
-    /// Adds an entry to the end of this section name `key` and `value`. If `value` is None`, no equal sign will be written leaving
+    /// Adds an entry to the end of this section name `key` and `value`. If `value` is `None`, no equal sign will be written leaving
     /// just the key. This is useful for boolean values which are true if merely the key exists.
     pub fn push<'b>(&mut self, key: Key<'event>, value: Option<&'b BStr>) {
+        self.push_with_comment_inner(key, value, None)
+    }
+
+    /// Adds an entry to the end of this section name `key` and `value`. If `value` is `None`, no equal sign will be written leaving
+    /// just the key. This is useful for boolean values which are true if merely the key exists.
+    /// `comment` has to be the text to put right after the value and behind a `#` character. Note that newlines are silently transformed
+    /// into spaces.
+    pub fn push_with_comment<'b, 'c>(
+        &mut self,
+        key: Key<'event>,
+        value: Option<&'b BStr>,
+        comment: impl Into<&'c BStr>,
+    ) {
+        self.push_with_comment_inner(key, value, comment.into().into())
+    }
+
+    fn push_with_comment_inner(&mut self, key: Key<'event>, value: Option<&BStr>, comment: Option<&BStr>) {
         let body = &mut self.section.body.0;
         if let Some(ws) = &self.whitespace.pre_key {
             body.push(Event::Whitespace(ws.clone()));
@@ -44,6 +61,21 @@ impl<'a, 'event> SectionMut<'a, 'event> {
             }
             None => body.push(Event::Value(Cow::Borrowed("".into()))),
         }
+        if let Some(comment) = comment {
+            body.push(Event::Whitespace(Cow::Borrowed(" ".into())));
+            body.push(Event::Comment(parse::Comment {
+                tag: b'#',
+                text: Cow::Owned({
+                    let mut c = Vec::with_capacity(comment.len());
+                    let mut bytes = comment.iter().peekable();
+                    if !bytes.peek().map_or(true, |b| b.is_ascii_whitespace()) {
+                        c.insert(0, b' ');
+                    }
+                    c.extend(bytes.map(|b| (*b == b'\n').then(|| b' ').unwrap_or(*b)));
+                    c.into()
+                }),
+            }));
+        }
         if self.implicit_newline {
             body.push(Event::Newline(BString::from(self.newline.to_vec()).into()));
         }

git-config/tests/file/mutable/section.rs

@@ -202,6 +202,37 @@ mod push {
     }
 }
 
+mod push_with_comment {
+    use git_config::parse::section::Key;
+
+    #[test]
+    fn various_comments_and_escaping() {
+        for (comment, expected) in [
+            ("", "$head\tk = v #$nl"),
+            ("this is v!", "$head\tk = v # this is v!$nl"),
+            (" no double space", "$head\tk = v # no double space$nl"),
+            ("\tno double whitespace", "$head\tk = v #\tno double whitespace$nl"),
+            (
+                "one\ntwo\nnewlines are replaced with space",
+                "$head\tk = v # one two newlines are replaced with space$nl",
+            ),
+            (
+                "a\rb\r\nlinefeeds aren't special",
+                "$head\tk = v # a\rb\r linefeeds aren't special$nl",
+            ),
+        ] {
+            let mut config = git_config::File::default();
+            let mut section = config.new_section("a", None).unwrap();
+            section.set_implicit_newline(false);
+            section.push_with_comment(Key::try_from("k").unwrap(), Some("v".into()), comment);
+            let expected = expected
+                .replace("$head", &format!("[a]{nl}", nl = section.newline()))
+                .replace("$nl", &section.newline().to_string());
+            assert_eq!(config.to_bstring(), expected);
+        }
+    }
+}
+
 mod set_leading_whitespace {
     use std::{borrow::Cow, convert::TryFrom};