Add support for source tracking (#16)

Adds the `track-source` feature flag that, when enabled:
- Allows `RawValue` to store the file and line number it originated
from.
- Makes `ConfigParser` generate `RawValue`s that store their sources.

Adds flags to `ec4rs-parse` to allow printing sources.

Closes #15

Author: TheDaemoness

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## 1.2.0 (Next)
 
+- Added feature `track-source` to track where any given value came from.
+- Added `-0Hl` flags to `ec4rs-parse` for displaying value sources.
 - Added `RawValue::to_lowercase`.
 - Implemented `Display` for `RawValue`.
 - Changed `ec4rs-parse` to support empty values for compliance with

Cargo.toml

@@ -21,6 +21,7 @@ members = ["tools"]
 
 [features]
 allow-empty-values = []
+track-source = []
 
 [dependencies]
 language-tags = { version = "0.3.2", optional = true }

rustdoc.md

@@ -55,3 +55,7 @@ as invalid, necessitating this feature flag to reduce behavioral breakage.
 
 **language-tags**: Use the `language-tags` crate, which adds parsing for the
 `spelling_language` property.
+
+**track-source**: Allow [`RawValue`][crate::rawvalue::RawValue]
+to store the file and line number it originates from.
+[`ConfigParser`] will add this information where applicable.

src/file.rs

@@ -4,6 +4,7 @@ use crate::{ConfigParser, Error, ParseError, Properties, PropertiesSource, Secti
 
 /// Convenience wrapper for an [`ConfigParser`] that reads files.
 pub struct ConfigFile {
+    // TODO: Arc<Path>. It's more important to have cheap clones than mutability.
     /// The path to the open file.
     pub path: PathBuf,
     /// A [`ConfigParser`] that reads from the file.
@@ -17,7 +18,7 @@ impl ConfigFile {
     pub fn open(path: impl Into<PathBuf>) -> Result<ConfigFile, ParseError> {
         let path = path.into();
         let file = std::fs::File::open(&path).map_err(ParseError::Io)?;
-        let reader = ConfigParser::new_buffered(file)?;
+        let reader = ConfigParser::new_buffered_with_path(file, Some(path.as_ref()))?;
         Ok(ConfigFile { path, reader })
     }
 

src/parser.rs

@@ -2,6 +2,7 @@ use crate::linereader::LineReader;
 use crate::ParseError;
 use crate::Section;
 use std::io;
+use std::path::Path;
 
 /// Parser for the text of an EditorConfig file.
 ///
@@ -13,6 +14,8 @@ pub struct ConfigParser<R: io::BufRead> {
     pub is_root: bool,
     eof: bool,
     reader: LineReader<R>,
+    #[cfg(feature = "track-source")]
+    path: Option<std::sync::Arc<Path>>,
 }
 
 impl<R: io::Read> ConfigParser<io::BufReader<R>> {
@@ -22,14 +25,33 @@ impl<R: io::Read> ConfigParser<io::BufReader<R>> {
     pub fn new_buffered(source: R) -> Result<ConfigParser<io::BufReader<R>>, ParseError> {
         Self::new(io::BufReader::new(source))
     }
+    /// Convenience function for construction using an unbuffered [`io::Read`]
+    /// which is assumed to be a file at `path`.
+    ///
+    /// See [`ConfigParser::new_with_path`].
+    pub fn new_buffered_with_path(
+        source: R,
+        path: Option<impl Into<std::sync::Arc<Path>>>,
+    ) -> Result<ConfigParser<io::BufReader<R>>, ParseError> {
+        Self::new_with_path(io::BufReader::new(source), path)
+    }
 }
 
 impl<R: io::BufRead> ConfigParser<R> {
-    /// Constructs a new [`ConfigParser`] and reads the preamble from the provided source.
+    /// Constructs a new [`ConfigParser`] and reads the preamble from the provided source,
+    /// which is assumed to be a file at `path`.
     ///
     /// Returns `Ok` if the preamble was parsed successfully,
     /// otherwise returns `Err` with the error that occurred during reading.
-    pub fn new(buf_source: R) -> Result<ConfigParser<R>, ParseError> {
+    ///
+    /// If the `track-source` feature is enabled and `path` is `Some`,
+    /// [`RawValue`][crate::rawvalue::RawValue]s produced by this parser will
+    /// have their sources set appropriately.
+    /// Otherwise, `path` is unused.
+    pub fn new_with_path(
+        buf_source: R,
+        #[allow(unused)] path: Option<impl Into<std::sync::Arc<Path>>>,
+    ) -> Result<ConfigParser<R>, ParseError> {
         let mut reader = LineReader::new(buf_source);
         let mut is_root = false;
         let eof = loop {
@@ -49,12 +71,23 @@ impl<R: io::BufRead> ConfigParser<R> {
                 }
             }
         };
+        #[cfg(feature = "track-source")]
+        let path = path.map(Into::into);
         Ok(ConfigParser {
             is_root,
             eof,
             reader,
+            #[cfg(feature = "track-source")]
+            path,
         })
     }
+    /// Constructs a new [`ConfigParser`] and reads the preamble from the provided source.
+    ///
+    /// Returns `Ok` if the preamble was parsed successfully,
+    /// otherwise returns `Err` with the error that occurred during reading.
+    pub fn new(buf_source: R) -> Result<ConfigParser<R>, ParseError> {
+        Self::new_with_path(buf_source, Option::<std::sync::Arc<Path>>::None)
+    }
 
     /// Returns `true` if there may be another section to read.
     pub fn has_more(&self) -> bool {
@@ -75,6 +108,9 @@ impl<R: io::BufRead> ConfigParser<R> {
         if let Ok(Line::Section(header)) = self.reader.reparse() {
             let mut section = Section::new(header);
             loop {
+                // Get line_no here to avoid borrowing issues, increment for 1-based indices.
+                #[cfg(feature = "track-source")]
+                let line_no = self.reader.line_no() + 1;
                 match self.reader.next_line() {
                     Err(e) => {
                         self.eof = true;
@@ -87,7 +123,13 @@ impl<R: io::BufRead> ConfigParser<R> {
                     Ok(Line::Section(_)) => break Ok(section),
                     Ok(Line::Nothing) => (),
                     Ok(Line::Pair(k, v)) => {
-                        section.insert(k, v.to_owned());
+                        #[allow(unused_mut)]
+                        let mut v = crate::rawvalue::RawValue::from(v.to_owned());
+                        #[cfg(feature = "track-source")]
+                        if let Some(path) = self.path.as_ref() {
+                            v.set_source(path.clone(), line_no);
+                        }
+                        section.insert(k, v);
                     }
                 }
             }

src/rawvalue.rs

@@ -8,32 +8,93 @@ use std::borrow::Cow;
 ///
 /// Not all unset `&RawValues` returned by this library are referentially equal to this one.
 /// This exists to provide an unset raw value for whenever a reference to one is necessary.
-pub static UNSET: RawValue = RawValue(Cow::Borrowed(""));
+pub static UNSET: RawValue = RawValue {
+    value: Cow::Borrowed(""),
+    #[cfg(feature = "track-source")]
+    source: None,
+};
 
 /// An unparsed property value.
 ///
 /// This is conceptually an optional non-empty string with some convenience methods.
-#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Default)]
-pub struct RawValue(Cow<'static, str>);
+/// With the `track-source` feature,
+/// objects of this type can also track the file and line number they originate from.
+#[derive(Clone, Debug, Default)]
+pub struct RawValue {
+    value: Cow<'static, str>,
+    #[cfg(feature = "track-source")]
+    source: Option<(std::sync::Arc<std::path::Path>, usize)>,
+}
+
+// Manual-impl (Partial)Eq, (Partial)Ord, and Hash so that the source isn't considered.
+
+impl PartialEq for RawValue {
+    fn eq(&self, other: &Self) -> bool {
+        self.value == other.value
+    }
+}
+impl Eq for RawValue {}
+impl PartialOrd for RawValue {
+    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
+        Some(self.value.cmp(&other.value))
+    }
+}
+impl Ord for RawValue {
+    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
+        self.value.cmp(&other.value)
+    }
+}
+impl std::hash::Hash for RawValue {
+    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
+        state.write(self.value.as_bytes());
+        state.write_u8(0);
+    }
+}
 
 impl RawValue {
     #[must_use]
     fn detect_unset(&self) -> Option<bool> {
         if self.is_unset() {
             Some(false)
-        } else if "unset".eq_ignore_ascii_case(self.0.as_ref()) {
+        } else if "unset".eq_ignore_ascii_case(self.value.as_ref()) {
             Some(true)
         } else {
             None
         }
     }
 
+    #[cfg(feature = "track-source")]
+    /// Returns the path to the file and the line number that this value originates from.
+    ///
+    /// The line number is 1-indexed to match convention;
+    /// the first line will have a line number of 1 rather than 0.
+    pub fn source(&self) -> Option<(&std::path::Path, usize)> {
+        self.source
+            .as_ref()
+            .map(|(path, line)| (std::sync::Arc::as_ref(path), *line))
+    }
+
+    #[cfg(feature = "track-source")]
+    /// Sets the path and line number from which this value originated.
+    ///
+    /// The line number should be 1-indexed to match convention;
+    /// the first line should have a line number of 1 rather than 0.
+    pub fn set_source(&mut self, path: impl Into<std::sync::Arc<std::path::Path>>, line: usize) {
+        self.source = Some((path.into(), line))
+    }
+
+    #[cfg(feature = "track-source")]
+    /// Clears the path and line number from which this value originated.
+    pub fn clear_source(&mut self) {
+        self.source = None;
+    }
+
     /// Returns true if the value is unset.
     ///
     /// Does not handle values of "unset".
     /// See [`RawValue::filter_unset`].
     pub fn is_unset(&self) -> bool {
-        self.0.is_empty()
+        self.value.is_empty()
     }
 
     /// Returns a reference to.an unset `RawValue`
@@ -66,13 +127,13 @@ impl RawValue {
         if let Some(v) = self.detect_unset() {
             Err(v)
         } else {
-            Ok(self.0.as_ref())
+            Ok(self.value.as_ref())
         }
     }
 
     /// Converts this `RawValue` into an [`Option`].
     pub fn into_option(&self) -> Option<&str> {
-        Some(self.0.as_ref()).filter(|v| !v.is_empty())
+        Some(self.value.as_ref()).filter(|v| !v.is_empty())
     }
 
     /// Converts this `RawValue` into `&str`.
@@ -82,7 +143,7 @@ impl RawValue {
         if self.is_unset() {
             "unset"
         } else {
-            self.0.as_ref()
+            self.value.as_ref()
         }
     }
 
@@ -111,19 +172,27 @@ impl RawValue {
     /// Returns a lowercased version of `self`.
     #[must_use]
     pub fn to_lowercase(&self) -> Self {
-        Self(Cow::Owned(self.0.to_lowercase()))
+        Self {
+            value: Cow::Owned(self.value.to_lowercase()),
+            #[cfg(feature = "track-source")]
+            source: self.source.clone(),
+        }
     }
 }
 
 impl std::fmt::Display for RawValue {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(f, "{}", self.0.as_ref())
+        write!(f, "{}", self.value.as_ref())
     }
 }
 
 impl From<String> for RawValue {
     fn from(value: String) -> Self {
-        RawValue(Cow::Owned(value))
+        RawValue {
+            value: Cow::Owned(value),
+            #[cfg(feature = "track-source")]
+            source: None,
+        }
     }
 }
 
@@ -132,7 +201,11 @@ impl From<&'static str> for RawValue {
         if value.is_empty() {
             UNSET.clone()
         } else {
-            RawValue(Cow::Borrowed(value))
+            RawValue {
+                value: Cow::Borrowed(value),
+                #[cfg(feature = "track-source")]
+                source: None,
+            }
         }
     }
 }

src/tests/ecparser.rs

@@ -1,25 +1,35 @@
 fn validate<'a>(
     text: &str,
     should_be_root: bool,
-    expected: impl IntoIterator<Item = &'a [(&'a str, &'a str)]>,
+    expected: impl IntoIterator<Item = &'a [(&'a str, &'a str, usize)]>,
 ) {
-    let mut parser =
-        crate::ConfigParser::new(text.as_bytes()).expect("Should have created the parser");
+    let path = std::sync::Arc::<std::path::Path>::from(std::path::Path::new(".editorconfig"));
+    let mut parser = crate::ConfigParser::new_buffered_with_path(text.as_bytes(), Some(path))
+        .expect("Should have created the parser");
     assert_eq!(parser.is_root, should_be_root);
     for section_expected in expected {
         let section = parser.next().unwrap().unwrap();
-        let mut iter = section.props().iter().map(|(k, v)| (k, v.into_str()));
-        for (key, value) in section_expected {
-            assert_eq!(iter.next(), Some((*key, *value)))
+        let mut iter = section.props().iter();
+        #[allow(unused)]
+        for (key, value, line_no) in section_expected {
+            let (key_test, value_test) = iter.next().expect("Unexpected end of section");
+            assert_eq!(key_test, *key, "unexpected key");
+            assert_eq!(value_test.into_str(), *value, "unexpected value");
+            #[cfg(feature = "track-source")]
+            assert_eq!(
+                value_test.source().map(|(_, idx)| idx),
+                Some(*line_no),
+                "unexpected line number"
+            )
         }
         assert!(iter.next().is_none());
     }
     assert!(parser.next().is_none());
 }
 
 macro_rules! expect {
-	[$([$(($key:literal, $value:literal)),*]),*] => {
-		[$(&[$(($key, $value)),*][..]),*]
+	[$([$(($key:literal, $value:literal, $line_no:literal)),*]),*] => {
+		[$(&[$(($key, $value, $line_no)),*][..]),*]
 	}
 }
 
@@ -53,31 +63,36 @@ fn sections() {
     validate(
         "[foo]\nbk=bv\nak=av",
         false,
-        expect![[("bk", "bv"), ("ak", "av")]],
+        expect![[("bk", "bv", 2), ("ak", "av", 3)]],
     );
     validate(
         "[foo]\nbk=bv\n[bar]\nak=av",
         false,
-        expect![[("bk", "bv")], [("ak", "av")]],
+        expect![[("bk", "bv", 2)], [("ak", "av", 4)]],
     );
     validate(
         "[foo]\nk=a\n[bar]\nk=b",
         false,
-        expect![[("k", "a")], [("k", "b")]],
+        expect![[("k", "a", 2)], [("k", "b", 4)]],
     );
 }
 
 #[test]
 fn trailing_newline() {
-    validate("[foo]\nbar=baz\n", false, expect![[("bar", "baz")]]);
-    validate("[foo]\nbar=baz\n\n", false, expect![[("bar", "baz")]]);
+    validate("[foo]\nbar=baz\n", false, expect![[("bar", "baz", 2)]]);
+    validate("[foo]\nbar=baz\n\n", false, expect![[("bar", "baz", 2)]]);
 }
 
 #[test]
 fn section_with_comment_after_it() {
     validate(
         "[/*] # ignore this comment\nk=v",
         false,
-        expect![[("k", "v")]],
+        expect![[("k", "v", 2)]],
     );
 }
+
+#[test]
+fn duplicate_key() {
+    validate("[*]\nfoo=bar\nfoo=baz", false, expect![[("foo", "baz", 3)]]);
+}

tools/Cargo.toml

@@ -1,12 +1,12 @@
 [package]
 name = "ec4rs_tools"
-version = "1.0.1"
+version = "1.1.0"
 edition = "2021"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-ec4rs = { path = "..", features = ["allow-empty-values"] }
+ec4rs = { path = "..", features = ["allow-empty-values", "track-source"] }
 semver = "1.0"
 clap = { version = "3.1", features = ["derive"] }
 

tools/src/bin/ec4rs-parse.rs

@@ -3,9 +3,24 @@ use std::path::PathBuf;
 use clap::Parser;
 use semver::{Version, VersionReq};
 
+#[derive(Parser)]
+struct DisplayArgs {
+    /// Prefix each line with the path to the file where the value originated
+    #[clap(short = 'H', long)]
+    with_filename: bool,
+    /// Prefix each line with the line number where the value originated
+    #[clap(short = 'n', long)]
+    line_number: bool,
+    /// Use the NUL byte as a field delimiter instead of ':'
+    #[clap(short = '0', long)]
+    null: bool,
+}
+
 #[derive(Parser)]
 #[clap(disable_version_flag = true)]
 struct Args {
+    #[clap(flatten)]
+    display: DisplayArgs,
     /// Override config filename
     #[clap(short)]
     filename: Option<PathBuf>,
@@ -18,7 +33,21 @@ struct Args {
     files: Vec<PathBuf>,
 }
 
-fn print_config(path: &std::path::Path, filename: Option<&PathBuf>, legacy_fallbacks: bool) {
+fn print_empty_prefix(display: &DisplayArgs) {
+    if display.with_filename {
+        print!("{}", if display.null { '\0' } else { ':' });
+    }
+    if display.line_number {
+        print!("{}", if display.null { '\0' } else { ':' });
+    }
+}
+
+fn print_config(
+    path: &std::path::Path,
+    filename: Option<&PathBuf>,
+    legacy_fallbacks: bool,
+    display: &DisplayArgs,
+) {
     match ec4rs::properties_from_config_of(path, filename) {
         Ok(mut props) => {
             if legacy_fallbacks {
@@ -27,11 +56,27 @@ fn print_config(path: &std::path::Path, filename: Option<&PathBuf>, legacy_fallb
                 props.use_fallbacks();
             }
             for (key, value) in props.iter() {
-                if ec4rs::property::STANDARD_KEYS.contains(&key) {
-                    println!("{}={}", key, value.to_lowercase())
+                let mut lc_value: Option<ec4rs::rawvalue::RawValue> = None;
+                let value_ref = if ec4rs::property::STANDARD_KEYS.contains(&key) {
+                    lc_value.get_or_insert(value.to_lowercase())
+                } else {
+                    value
+                };
+                if let Some((path, line_no)) = value_ref.source() {
+                    if display.with_filename {
+                        print!(
+                            "{}{}",
+                            path.to_string_lossy(),
+                            if display.null { '\0' } else { ':' }
+                        );
+                    }
+                    if display.line_number {
+                        print!("{}{}", line_no, if display.null { '\0' } else { ':' });
+                    }
                 } else {
-                    println!("{}={}", key, value);
+                    print_empty_prefix(display);
                 }
+                println!("{}={}", key, value_ref)
             }
         }
         Err(e) => eprintln!("{}", e),
@@ -52,14 +97,17 @@ fn main() {
             args.files.first().unwrap(),
             args.filename.as_ref(),
             legacy_ver.matches(&args.ec_version),
+            &args.display,
         );
     } else {
         for path in args.files {
+            print_empty_prefix(&args.display);
             println!("[{}]", path.to_string_lossy());
             print_config(
                 &path,
                 args.filename.as_ref(),
                 legacy_ver.matches(&args.ec_version),
+                &args.display,
             );
         }
     }