Add docs and tests for --format

Also fix bug where we didn't strip leading cwd.

doc/fd.1

@@ -363,6 +363,30 @@ Set the path separator to use when printing file paths. The default is the OS-sp
 Provide paths to search as an alternative to the positional \fIpath\fR argument. Changes the usage to
 \'fd [FLAGS/OPTIONS] \-\-search\-path PATH \-\-search\-path PATH2 [PATTERN]\'
 .TP
+.BI "\-\-format " fmt
+Specify a template string that is used for printing a line for each file found.
+
+The following placeholders are substituted into the string for each file before printing:
+.RS
+.IP {}
+path (of the current search result)
+.IP {/}
+basename
+.IP {//}
+parent directory
+.IP {.}
+path without file extension
+.IP {/.}
+basename without file extension
+.IP {{
+literal '{' (an escape sequence)
+.IP }}
+literal '}' (an escape sequence)
+.P
+Notice that you can use "{{" and "}}" to escape "{" and "}" respectively, which is especially
+useful if you need to include the literal text of one of the above placeholders.
+.RE
+.TP
 .BI "\-x, \-\-exec " command
 .RS
 Execute
@@ -383,29 +407,12 @@ If parallelism is enabled, the order commands will be executed in is non-determi
 --threads=1, the order is determined by the operating system and may not be what you expect. Thus, it is
 recommended that you don't rely on any ordering of the results.
 
-The following placeholders are substituted before the command is executed:
-.RS
-.IP {}
-path (of the current search result)
-.IP {/}
-basename
-.IP {//}
-parent directory
-.IP {.}
-path without file extension
-.IP {/.}
-basename without file extension
-.IP {{
-literal '{' (an escape sequence)
-.IP }}
-literal '}' (an escape sequence)
-.RE
+Before executing the command, any placeholder patterns in the command are replaced with the
+corresponding values for the current file. The same placeholders are used as in the "\-\-format"
+option.
 
 If no placeholder is present, an implicit "{}" at the end is assumed.
 
-Notice that you can use "{{" and "}}" to escape "{" and "}" respectively, which is especially
-useful if you need to include the literal text of one of the above placeholders.
-
 Examples:
 
  - find all *.zip files and unzip them:
@@ -429,19 +436,9 @@ once, with all search results as arguments.
 
 The order of the arguments is non-deterministic and should not be relied upon.
 
-One of the following placeholders is substituted before the command is executed:
-.RS
-.IP {}
-path (of all search results)
-.IP {/}
-basename
-.IP {//}
-parent directory
-.IP {.}
-path without file extension
-.IP {/.}
-basename without file extension
-.RE
+This uses the same placeholders as "\-\-format" and "\-\-exec", but instead of expanding
+once per command invocation each argument containing a placeholder is expanding for every
+file in a batch and passed as separate arguments.
 
 If no placeholder is present, an implicit "{}" at the end is assumed.
 

src/fmt/mod.rs

@@ -209,3 +209,60 @@ fn token_from_pattern_id(id: u32) -> Token {
  _ => unreachable!(),
  }
 }
+
+
+#[cfg(test)]
+mod fmt_tests {
+ use super::*;
+ use std::path::PathBuf;
+
+ #[test]
+ fn parse_no_placeholders() {
+ let templ = FormatTemplate::parse("This string has no placeholders");
+ assert_eq!(templ, FormatTemplate::Text("This string has no placeholders".into()));
+ }
+
+ #[test]
+ fn parse_only_brace_escapes() {
+ let templ = FormatTemplate::parse("This string only has escapes like {{ and }}");
+ assert_eq!(templ, FormatTemplate::Text("This string only has escapes like { and }".into()));
+ }
+
+ #[test]
+ fn all_placeholders() {
+ use Token::*;
+
+ let templ = FormatTemplate::parse("{{path={} \
+ basename={/} \
+ parent={//} \
+ noExt={.} \
+ basenameNoExt={/.} \
+ }}");
+ assert_eq!(templ, FormatTemplate::Tokens(vec![
+ Text("{path=".into()),
+ Placeholder,
+ Text(" basename=".into()),
+ Basename,
+ Text(" parent=".into()),
+ Parent,
+ Text(" noExt=".into()),
+ NoExt,
+ Text(" basenameNoExt=".into()),
+ BasenameNoExt,
+ Text(" }".into()),
+ ]));
+
+ let mut path = PathBuf::new();
+ path.push("a");
+ path.push("folder");
+ path.push("file.txt");
+
+ let expanded = templ.generate(&path, Some("/")).into_string().unwrap();
+
+ assert_eq!(expanded, "{path=a/folder/file.txt \
+ basename=file.txt \
+ parent=a/folder \
+ noExt=a/folder/file \
+ basenameNoExt=file }");
+ }
+}

src/output.rs

@@ -66,7 +66,7 @@ fn print_entry_format<W: Write>(
  format: &FormatTemplate,
 ) -> io::Result<()> {
  let separator = if config.null_separator { "\0" } else { "\n" };
- let output = format.generate(entry.path(), config.path_separator.as_deref());
+ let output = format.generate(entry.stripped_path(&config), config.path_separator.as_deref());
  // TODO: support writing raw bytes on unix?
  write!(stdout, "{}{}", output.to_string_lossy(), separator)
 }

tests/tests.rs

@@ -1622,6 +1622,66 @@ fn test_excludes() {
  );
 }
 
+#[test]
+fn format() {
+ let te = TestEnv::new(DEFAULT_DIRS, DEFAULT_FILES);
+
+ te.assert_output(
+ &["--format", "path={}", "--path-separator=/"],
+ "path=a.foo
+ path=e1 e2
+ path=one
+ path=one/b.foo
+ path=one/two
+ path=one/two/C.Foo2
+ path=one/two/c.foo
+ path=one/two/three
+ path=one/two/three/d.foo
+ path=one/two/three/directory_foo
+ path=symlink"
+ );
+
+ te.assert_output(
+ &["foo", "--format", "noExt={.}", "--path-separator=/"],
+ "noExt=a
+ noExt=one/b
+ noExt=one/two/C
+ noExt=one/two/c
+ noExt=one/two/three/d
+ noExt=one/two/three/directory_foo"
+ );
+
+ te.assert_output(
+ &["foo", "--format", "basename={/}", "--path-separator=/"],
+ "basename=a.foo
+ basename=b.foo
+ basename=C.Foo2
+ basename=c.foo
+ basename=d.foo
+ basename=directory_foo"
+ );
+
+ te.assert_output(
+ &["foo", "--format", "name={/.}", "--path-separator=/"],
+ "name=a
+ name=b
+ name=C
+ name=c
+ name=d
+ name=directory_foo"
+ );
+
+ te.assert_output(
+ &["foo", "--format", "parent={//}", "--path-separator=/"],
+ "parent=.
+ parent=one
+ parent=one/two
+ parent=one/two
+ parent=one/two/three
+ parent=one/two/three"
+ );
+}
+
 /// Shell script execution (--exec)
 #[test]
 fn test_exec() {