Add --files-with-matches flag.

Closes #26.

Acts like --count but emits only the paths of files with matches,
suitable for piping to xargs. Both mmap and no-mmap searches terminate
after the first match is found. Documentation updated and tests added.

3 files changed, 73 insertions, 9 deletions

diff --git a/src/args.rs b/src/args.rs
index 99e01fdd..1d3e8812 100644
--- a/src/args.rs
+++ b/src/args.rs
@@ -47,6 +47,7 @@ rg recursively searches your current directory for a regex pattern.
 Common options:
     -a, --text                 Search binary files as if they were text.
     -c, --count                Only show count of line matches for each file.
+    -l, --files-with-matches   Only show path of each file with matches.
     --color WHEN               Whether to use coloring in match.
                                Valid values are never, always or auto.
                                [default: auto]
@@ -199,6 +200,7 @@ pub struct RawArgs {
     flag_context: usize,
     flag_context_separator: String,
     flag_count: bool,
+    flag_files_with_matches: bool,
     flag_debug: bool,
     flag_files: bool,
     flag_follow: bool,
@@ -246,6 +248,7 @@ pub struct Args {
     column: bool,
     context_separator: Vec<u8>,
     count: bool,
+    files_with_matches: bool,
     eol: u8,
     files: bool,
     follow: bool,
@@ -370,6 +373,7 @@ impl RawArgs {
             column: self.flag_column,
             context_separator: unescape(&self.flag_context_separator),
             count: self.flag_count,
+            files_with_matches: self.flag_files_with_matches,
             eol: eol,
             files: self.flag_files,
             follow: self.flag_follow,
@@ -554,7 +558,7 @@ impl Args {
     /// to the writer given.
     pub fn out(&self) -> Out {
         let mut out = Out::new(self.color);
-        if self.heading && !self.count {
+        if self.heading && !self.count && !self.files_with_matches {
             out = out.file_separator(b"".to_vec());
         } else if self.before_context > 0 || self.after_context > 0 {
             out = out.file_separator(self.context_separator.clone());
@@ -608,6 +612,7 @@ impl Args {
             .after_context(self.after_context)
             .before_context(self.before_context)
             .count(self.count)
+            .files_with_matches(self.files_with_matches)
             .eol(self.eol)
             .line_number(self.line_number)
             .invert_match(self.invert_match)
@@ -626,6 +631,7 @@ impl Args {
     ) -> BufferSearcher<'a, W> {
         BufferSearcher::new(printer, grep, path, buf)
             .count(self.count)
+            .files_with_matches(self.files_with_matches)
             .eol(self.eol)
             .line_number(self.line_number)
             .invert_match(self.invert_match)
diff --git a/src/search_buffer.rs b/src/search_buffer.rs
index fb16bf0b..a3edbcb0 100644
--- a/src/search_buffer.rs
+++ b/src/search_buffer.rs
@@ -53,6 +53,14 @@ impl<'a, W: Send + Terminal> BufferSearcher<'a, W> {
         self
     }
 
+    /// If enabled, searching will print the path instead of each match.
+    ///
+    /// Disabled by default.
+    pub fn files_with_matches(mut self, yes: bool) -> Self {
+        self.opts.files_with_matches = yes;
+        self
+    }
+
     /// Set the end-of-line byte used by this searcher.
     pub fn eol(mut self, eol: u8) -> Self {
         self.opts.eol = eol;
@@ -96,6 +104,9 @@ impl<'a, W: Send + Terminal> BufferSearcher<'a, W> {
                 self.print_match(m.start(), m.end());
             }
             last_end = m.end();
+            if self.opts.files_with_matches {
+                break;
+            }
         }
         if self.opts.invert_match {
             let upto = self.buf.len();
@@ -104,13 +115,16 @@ impl<'a, W: Send + Terminal> BufferSearcher<'a, W> {
         if self.opts.count && self.match_count > 0 {
             self.printer.path_count(self.path, self.match_count);
         }
+        if self.opts.files_with_matches && self.match_count > 0 {
+            self.printer.path(self.path);
+        }
         self.match_count
     }
 
     #[inline(always)]
     pub fn print_match(&mut self, start: usize, end: usize) {
         self.match_count += 1;
-        if self.opts.count {
+        if self.opts.skip_matches() {
             return;
         }
         self.count_lines(start);
@@ -238,6 +252,14 @@ and exhibited clearly, with a label attached.\
     }
 
     #[test]
+    fn files_with_matches() {
+        let (count, out) = search(
+            "Sherlock", SHERLOCK, |s| s.files_with_matches(true));
+        assert_eq!(1, count);
+        assert_eq!(out, "/baz.rs\n");
+    }
+
+    #[test]
     fn invert_match() {
         let (count, out) = search(
             "Sherlock", SHERLOCK, |s| s.invert_match(true));
diff --git a/src/search_stream.rs b/src/search_stream.rs
index fbae781c..7b661808 100644
--- a/src/search_stream.rs
+++ b/src/search_stream.rs
@@ -80,6 +80,7 @@ pub struct Options {
     pub after_context: usize,
     pub before_context: usize,
     pub count: bool,
+    pub files_with_matches: bool,
     pub eol: u8,
     pub invert_match: bool,
     pub line_number: bool,
@@ -92,12 +93,22 @@ impl Default for Options {
             after_context: 0,
             before_context: 0,
             count: false,
+            files_with_matches: false,
             eol: b'\n',
             invert_match: false,
             line_number: false,
             text: false,
         }
     }
+
+}
+
+impl Options {
+    /// Both --count and --files-with-matches options imply that we should not
+    /// display matches at all.
+    pub fn skip_matches(&self) -> bool {
+        return self.count || self.files_with_matches;
+    }
 }
 
 impl<'a, R: io::Read, W: Terminal + Send> Searcher<'a, R, W> {
@@ -158,6 +169,14 @@ impl<'a, R: io::Read, W: Terminal + Send> Searcher<'a, R, W> {
         self
     }
 
+    /// If enabled, searching will print the path instead of each match.
+    ///
+    /// Disabled by default.
+    pub fn files_with_matches(mut self, yes: bool) -> Self {
+        self.opts.files_with_matches = yes;
+        self
+    }
+
     /// Set the end-of-line byte used by this searcher.
     pub fn eol(mut self, eol: u8) -> Self {
         self.opts.eol = eol;
@@ -193,7 +212,7 @@ impl<'a, R: io::Read, W: Terminal + Send> Searcher<'a, R, W> {
         self.line_count = if self.opts.line_number { Some(0) } else { None };
         self.last_match = Match::default();
         self.after_context_remaining = 0;
-        loop {
+        while !self.terminate() {
             let upto = self.inp.lastnl;
             self.print_after_context(upto);
             if !try!(self.fill()) {
@@ -202,7 +221,7 @@ impl<'a, R: io::Read, W: Terminal + Send> Searcher<'a, R, W> {
             if !self.opts.text && self.inp.is_binary {
                 break;
             }
-            while self.inp.pos < self.inp.lastnl {
+            while !self.terminate() && self.inp.pos < self.inp.lastnl {
                 let matched = self.grep.read_match(
                     &mut self.last_match,
                     &mut self.inp.buf[..self.inp.lastnl],
@@ -234,13 +253,22 @@ impl<'a, R: io::Read, W: Terminal + Send> Searcher<'a, R, W> {
                 }
             }
         }
-        if self.opts.count && self.match_count > 0 {
-            self.printer.path_count(self.path, self.match_count);
+        if self.match_count > 0 {
+            if self.opts.count {
+                self.printer.path_count(self.path, self.match_count);
+            } else if self.opts.files_with_matches {
+                self.printer.path(self.path);
+            }
         }
         Ok(self.match_count)
     }
 
     #[inline(always)]
+    fn terminate(&self) -> bool {
+        return self.opts.files_with_matches && self.match_count > 0;
+    }
+
+    #[inline(always)]
     fn fill(&mut self) -> Result<bool, Error> {
         let mut keep = self.inp.lastnl;
         if self.opts.before_context > 0 || self.opts.after_context > 0 {
@@ -281,7 +309,7 @@ impl<'a, R: io::Read, W: Terminal + Send> Searcher<'a, R, W> {
 
     #[inline(always)]
     fn print_before_context(&mut self, upto: usize) {
-        if self.opts.count || self.opts.before_context == 0 {
+        if self.opts.skip_matches() || self.opts.before_context == 0 {
             return;
         }
         let start = self.last_printed;
@@ -304,7 +332,7 @@ impl<'a, R: io::Read, W: Terminal + Send> Searcher<'a, R, W> {
 
     #[inline(always)]
     fn print_after_context(&mut self, upto: usize) {
-        if self.opts.count || self.after_context_remaining == 0 {
+        if self.opts.skip_matches() || self.after_context_remaining == 0 {
             return;
         }
         let start = self.last_printed;
@@ -322,7 +350,7 @@ impl<'a, R: io::Read, W: Terminal + Send> Searcher<'a, R, W> {
     #[inline(always)]
     fn print_match(&mut self, start: usize, end: usize) {
         self.match_count += 1;
-        if self.opts.count {
+        if self.opts.skip_matches() {
             return;
         }
         self.print_separator(start);
@@ -993,6 +1021,14 @@ fn main() {
     }
 
     #[test]
+    fn files_with_matches() {
+        let (count, out) = search_smallcap(
+            "Sherlock", SHERLOCK, |s| s.files_with_matches(true));
+        assert_eq!(1, count);
+        assert_eq!(out, "/baz.rs\n");
+    }
+
+    #[test]
     fn invert_match() {
         let (count, out) = search_smallcap(
             "Sherlock", SHERLOCK, |s| s.invert_match(true));