From d27d5e9094f0f5916266e0460ff0877ef330bd2d Mon Sep 17 00:00:00 2001
From: Federico Igne <git@federicoigne.com>
Date: Fri, 30 Dec 2022 16:14:19 +0000
Subject: feat(list): add flag to list valid entry points

---
 README.md   | 36 +++++++++++++++++++++++++++---------
 src/main.rs | 25 ++++++++++++++++---------
 2 files changed, 43 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 94f4a43..a5979ee 100644
--- a/README.md
+++ b/README.md
@@ -236,6 +236,7 @@ The `struct` holding the CLI information is defined as follow
 #[derive(Parser, Debug)]
 #[clap(author, version, about, long_about = None)]
 struct Config {
+  <<config_list>>
   <<config_depth>>
   <<config_output>>
   <<config_target>>
@@ -265,8 +266,8 @@ By default `pangler` will generate all entry points gathered from the input file
 This behaviour can be overridden with the `-t/--target` flag.
 
 ```{#config_target .rust}
-/// Target files prefix
-#[clap(short, long)]
+/// Limit entry points to those matching the provided prefix
+#[clap(short, long, value_name = "PREFIX")]
 target: Option<PathBuf>,
 ```
 
@@ -276,6 +277,18 @@ let target = config.target.unwrap_or_default();
 
 Any entry point that does not have the provided target *as a prefix* will be ignored.
 
+## Listing entry points
+
+Sometimes it might be useful to simply get a list of all entry points considered by `pangler` for a specific input.
+Using the `-l/--list` flag, `pangler` will simply list all valid entry points to stdout and exit.
+Note that the output will be consistent with any provided [target](#specifying-target-entry-points).
+
+```{#config_list .rust}
+/// Simply list entry points and exit
+#[clap(short, long)]
+list: bool,
+```
+
 ## Custom output folder
 
 By default, files are generated in the current working directory.
@@ -289,7 +302,7 @@ If the output folder does not exists, *it will be created*.
 
 ```{#config_output .rust}
 /// Base output directory [default: './']
-#[clap(short, long)]
+#[clap(short, long, value_name = "PATH")]
 output: Option<PathBuf>,
 ```
 
@@ -300,7 +313,7 @@ By default, `pangler` will stop after 10 substitution iterations, but this param
 
 ```{#config_depth .rust}
 /// Maximum substitution depth
-#[clap(short, long, default_value_t = 10)]
+#[clap(short, long, default_value_t = 10, value_name = "N")]
 depth: u32,
 ```
 
@@ -405,9 +418,17 @@ pandoc.blocks.iter().for_each(|block|
 ```
 
 And then we build the source code, making sure to cut off recursive code generation with depth larger than `config.depth`.
+If the `-l/--list` flag is provided, `pangler` will simply list the available entry points and exit.
 
 ```{#pandoc_filter .rust}
-build(&config.output, &blocks, config.depth);
+if config.list {
+  blocks.keys().for_each(|k| match k {
+    Key::Entry(s) => println!("{}", s.display()),
+    Key::Macro(_) => {}
+  });
+} else {
+  build(&config.output, &blocks, config.depth);
+}
 ```
 
 The filter returns the Pandoc JSON unchanged.
@@ -626,10 +647,7 @@ fn write_to_file(
     <<parent_directory_creation>>
     <<write_to_file>>
   } else { 
-    eprintln!(
-      "Absolute paths not supported: {}",
-      path.to_string_lossy()
-    )
+    eprintln!("Absolute paths not supported: {}", path.display())
   }
   Ok(())
 }
diff --git a/src/main.rs b/src/main.rs
index 1d6bdd4..acb08ad 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -17,14 +17,17 @@ const BASE: &str = "./";
 #[derive(Parser, Debug)]
 #[clap(author, version, about, long_about = None)]
 struct Config {
+  /// Simply list entry points and exit
+  #[clap(short, long)]
+  list: bool,
   /// Maximum substitution depth
-  #[clap(short, long, default_value_t = 10)]
+  #[clap(short, long, default_value_t = 10, value_name = "N")]
   depth: u32,
   /// Base output directory [default: './']
-  #[clap(short, long)]
+  #[clap(short, long, value_name = "PATH")]
   output: Option<PathBuf>,
-  /// Target files prefix
-  #[clap(short, long)]
+  /// Limit entry points to those matching the provided prefix
+  #[clap(short, long, value_name = "PREFIX")]
   target: Option<PathBuf>,
   /// Input files
   input: Vec<PathBuf>,
@@ -122,10 +125,7 @@ fn write_to_file(
     fs::create_dir_all(path.parent().unwrap())?;
     fs::write(path, content)?;
   } else { 
-    eprintln!(
-      "Absolute paths not supported: {}",
-      path.to_string_lossy()
-    )
+    eprintln!("Absolute paths not supported: {}", path.display())
   }
   Ok(())
 }
@@ -186,7 +186,14 @@ fn main() -> Result<()> {
             }
           }
         );
-        build(&config.output, &blocks, config.depth);
+        if config.list {
+          blocks.keys().for_each(|k| match k {
+            Key::Entry(s) => println!("{}", s.display()),
+            Key::Macro(_) => {}
+          });
+        } else {
+          build(&config.output, &blocks, config.depth);
+        }
         pandoc
       }
     )
-- 
cgit v1.2.3