Merge branch 'master' into zerosnacks/fix-missing-imports

scripts/gen_output/help.rs

@@ -11,8 +11,8 @@ regex = "1"
 use clap::Parser;
 use regex::Regex;
 use std::borrow::Cow;
-use std::fs::{self, File};
-use std::io::{self, Write};
+use std::fs;
+use std::io;
 use std::iter::once;
 use std::path::{Path, PathBuf};
 use std::process::{Command, Stdio};
@@ -46,11 +46,11 @@ macro_rules! regex {
 #[command(about, long_about = None)]
 struct Args {
     /// Root directory
-    #[arg(long, default_value_t = String::from("."))]
-    root_dir: String,
+    #[arg(long, default_value = ".")]
+    root_dir: PathBuf,
 
     /// Indentation for the root SUMMARY.md file
-    #[arg(long, default_value_t = 2)]
+    #[arg(long, default_value = "2")]
     root_indentation: usize,
 
     /// Output directory
@@ -98,19 +98,15 @@ fn main() -> io::Result<()> {
         .commands
         .iter()
         .rev() // reverse to keep the order (pop)
-        .map(Cmd::new)
+        .map(|path| Cmd::new(path, vec![]))
         .collect();
     let mut output = Vec::new();
 
     // Iterate over all commands and their subcommands.
     while let Some(cmd) = todo_iter.pop() {
         let (new_subcmds, stdout) = get_entry(&cmd)?;
         if args.verbose && !new_subcmds.is_empty() {
-            println!(
-                "Found subcommands for \"{}\": {:?}",
-                cmd.command_name(),
-                new_subcmds
-            );
+            println!("Found subcommands for `{cmd}`: {}", new_subcmds.join(", "));
         }
         // Add new subcommands to todo_iter (so that they are processed in the correct order).
         for subcmd in new_subcmds.into_iter().rev() {
@@ -121,10 +117,7 @@ fn main() -> io::Result<()> {
                 .chain(once(subcmd))
                 .collect();
 
-            todo_iter.push(Cmd {
-                cmd: cmd.cmd,
-                subcommands: new_subcmds,
-            });
+            todo_iter.push(Cmd::new(cmd.cmd, new_subcmds));
         }
         output.push((cmd, stdout));
     }
@@ -147,7 +140,7 @@ fn main() -> io::Result<()> {
     if args.readme {
         let path = &out_dir.join("README.md");
         if args.verbose {
-            println!("Writing README.md to \"{}\"", path.to_string_lossy());
+            println!("Writing README.md to {}", path.display());
         }
         write_file(path, README)?;
     }
@@ -162,9 +155,9 @@ fn main() -> io::Result<()> {
             })
             .collect();
 
-        let path = Path::new(args.root_dir.as_str());
+        let path = &args.root_dir;
         if args.verbose {
-            println!("Updating root summary in \"{}\"", path.to_string_lossy());
+            println!("Updating root summary in {}", path.display());
         }
         update_root_summary(path, &root_summary)?;
     }
@@ -178,7 +171,7 @@ fn get_entry(cmd: &Cmd) -> io::Result<(Vec<String>, String)> {
         .args(&cmd.subcommands)
         .arg("--help")
         .env("NO_COLOR", "1")
-        .env("COLUMNS", "100")
+        .env("COLUMNS", "80")
         .env("LINES", "10000")
         .stdout(Stdio::piped())
         .output()?;
@@ -227,7 +220,7 @@ fn parse_sub_commands(s: &str) -> Vec<String> {
 fn cmd_markdown(out_dir: &Path, cmd: &Cmd, stdout: &str) -> io::Result<()> {
     let out = format!("# {}\n\n{}", cmd, help_markdown(cmd, stdout));
 
-    let out_path = out_dir.join(cmd.to_string().replace(" ", "/"));
+    let out_path = out_dir.join(cmd.md_path());
     fs::create_dir_all(out_path.parent().unwrap())?;
     write_file(&out_path.with_extension("md"), &out)?;
 
@@ -237,12 +230,8 @@ fn cmd_markdown(out_dir: &Path, cmd: &Cmd, stdout: &str) -> io::Result<()> {
 /// Returns the markdown for a command's help output.
 fn help_markdown(cmd: &Cmd, stdout: &str) -> String {
     let (description, s) = parse_description(stdout);
-    format!(
-        "{}\n\n```bash\n$ {} --help\n{}\n```",
-        description,
-        cmd,
-        preprocess_help(s.trim())
-    )
+    let help = preprocess_help(s.trim());
+    format!("{description}\n\n```bash\n$ {cmd} --help\n```\n\n```txt\n{help}\n```")
 }
 
 /// Splits the help output into a description and the rest.
@@ -258,14 +247,13 @@ fn parse_description(s: &str) -> (&str, &str) {
 
 /// Returns the summary for a command and its subcommands.
 fn cmd_summary(md_root: Option<PathBuf>, cmd: &Cmd, indent: usize) -> String {
-    let cmd_s = cmd.to_string();
-    let cmd_path = cmd_s.replace(" ", "/");
+    let cmd_path = cmd.md_path();
     let full_cmd_path = match md_root {
         None => cmd_path,
         Some(md_root) => format!("{}/{}", md_root.to_string_lossy(), cmd_path),
     };
     let indent_string = " ".repeat(indent + (cmd.subcommands.len() * 2));
-    format!("{}- [`{}`](./{}.md)\n", indent_string, cmd_s, full_cmd_path)
+    format!("{indent_string}- [`{cmd}`](./{full_cmd_path}.md)\n")
 }
 
 /// Replaces the CLI_REFERENCE section in the root SUMMARY.md file.
@@ -297,8 +285,7 @@ fn update_root_summary(root_dir: &Path, root_summary: &str) -> io::Result<()> {
         .replace(&original_summary_content, replace_with.as_str())
         .to_string();
 
-    let mut root_summary_file = File::create(&summary_file)?;
-    root_summary_file.write_all(new_root_summary.as_bytes())
+    fs::write(&summary_file, &new_root_summary)
 }
 
 /// Preprocesses the help output of a command.
@@ -322,36 +309,57 @@ fn preprocess_help(s: &str) -> Cow<'_, str> {
     s
 }
 
+/// Command with subcommands.
 #[derive(Hash, Debug, PartialEq, Eq)]
 struct Cmd<'a> {
-    /// path to binary (e.g. ./target/debug/reth)
+    /// Path to the binary file (e.g. ./target/debug/reth).
     cmd: &'a Path,
-    /// subcommands (e.g. [db, stats])
+    /// Subcommands (e.g. [db, stats]).
     subcommands: Vec<String>,
 }
 
 impl<'a> Cmd<'a> {
+    #[track_caller]
+    fn new(cmd: &'a Path, subcommands: Vec<String>) -> Self {
+        let cmd = Self { cmd, subcommands };
+        cmd.assert();
+        cmd
+    }
+
+    #[track_caller]
+    fn assert(&self) {
+        for subcmd in &self.subcommands {
+            assert!(!subcmd.is_empty(), "subcommand is empty");
+            assert!(
+                subcmd.chars().all(|c| !c.is_whitespace()),
+                "subcommand contains invalid characters: {subcmd}"
+            );
+        }
+    }
+
     fn command_name(&self) -> &str {
         self.cmd
             .file_name()
             .and_then(|os_str| os_str.to_str())
             .expect("Expect valid command")
     }
 
-    fn new(cmd: &'a PathBuf) -> Self {
-        Self {
-            cmd,
-            subcommands: Vec::new(),
+    fn md_path(&self) -> String {
+        self.join_s("/")
+    }
+
+    fn join_s(&self, sep: &str) -> String {
+        let mut joined = self.command_name().to_string();
+        for subcmd in &self.subcommands {
+            joined.push_str(sep);
+            joined.push_str(subcmd);
         }
+        joined
     }
 }
 
 impl<'a> fmt::Display for Cmd<'a> {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        write!(f, "{}", self.command_name())?;
-        if !self.subcommands.is_empty() {
-            write!(f, " {}", self.subcommands.join(" "))?;
-        }
-        Ok(())
+        self.join_s(" ").fmt(f)
     }
 }

src/reference/cli/anvil.md

@@ -4,6 +4,9 @@ A fast local Ethereum development node
 
 ```bash
 $ anvil --help
+```
+
+```txt
 Usage: anvil [OPTIONS] [COMMAND]
 
 Commands:
@@ -36,32 +39,36 @@ Options:
           [default: m/44'/60'/0'/0/]
 
       --dump-state <PATH>
-          Dump the state and block environment of chain on exit to the given file.
+          Dump the state and block environment of chain on exit to the given
+          file.
           
-          If the value is a directory, the state will be written to `<VALUE>/state.json`.
+          If the value is a directory, the state will be written to
+          `<VALUE>/state.json`.
 
   -h, --help
           Print help (see a summary with '-h')
 
       --hardfork <HARDFORK>
           The EVM hardfork to use.
           
-          Choose the hardfork by name, e.g. `shanghai`, `paris`, `london`, etc... [default: latest]
+          Choose the hardfork by name, e.g. `shanghai`, `paris`, `london`,
+          etc... [default: latest]
 
       --init <PATH>
           Initialize the genesis block with the given `genesis.json` file
 
       --ipc [<PATH>]
-          Launch an ipc server at the given path or default path = `/tmp/anvil.ipc`
+          Launch an ipc server at the given path or default path =
+          `/tmp/anvil.ipc`
           
           [aliases: ipcpath]
 
       --load-state <PATH>
           Initialize the chain from a previously saved state snapshot
 
   -m, --mnemonic <MNEMONIC>
-          BIP39 mnemonic phrase used for generating accounts. Cannot be used if `mnemonic_random` or
-          `mnemonic_seed` are used
+          BIP39 mnemonic phrase used for generating accounts. Cannot be used if
+          `mnemonic_random` or `mnemonic_seed` are used
 
       --max-persisted-states <MAX_PERSISTED_STATES>
           Max number of states to persist on disk.
@@ -72,16 +79,16 @@ Options:
           [aliases: mixed-mining]
 
       --mnemonic-random [<MNEMONIC_RANDOM>]
-          Automatically generates a BIP39 mnemonic phrase, and derives accounts from it. Cannot be
-          used with other `mnemonic` options. You can specify the number of words you want in the
-          mnemonic. [default: 12]
+          Automatically generates a BIP39 mnemonic phrase, and derives accounts
+          from it. Cannot be used with other `mnemonic` options. You can specify
+          the number of words you want in the mnemonic. [default: 12]
 
       --mnemonic-seed-unsafe <MNEMONIC_SEED>
-          Generates a BIP39 mnemonic phrase from a given seed Cannot be used with other `mnemonic`
-          options.
+          Generates a BIP39 mnemonic phrase from a given seed Cannot be used
+          with other `mnemonic` options.
           
-          CAREFUL: This is NOT SAFE and should only be used for testing. Never use the private keys
-          generated in production.
+          CAREFUL: This is NOT SAFE and should only be used for testing. Never
+          use the private keys generated in production.
 
       --no-mining
           Disable auto and interval mining, and mine on demand instead
@@ -99,13 +106,15 @@ Options:
           [default: 8545]
 
       --prune-history [<PRUNE_HISTORY>]
-          Don't keep full chain history. If a number argument is specified, at most this number of
-          states is kept in memory.
+          Don't keep full chain history. If a number argument is specified, at
+          most this number of states is kept in memory.
           
-          If enabled, no state will be persisted on disk, so `max_persisted_states` will be 0.
+          If enabled, no state will be persisted on disk, so
+          `max_persisted_states` will be 0.
 
   -s, --state-interval <SECONDS>
-          Interval in seconds at which the state and block environment is to be dumped to disk.
+          Interval in seconds at which the state and block environment is to be
+          dumped to disk.
           
           See --state and --dump-state
 
@@ -120,8 +129,8 @@ Options:
       --state <PATH>
           This is an alias for both --load-state and --dump-state.
           
-          It initializes the chain with the state and block environment stored at the file, if it
-          exists, and dumps the chain's state on exit.
+          It initializes the chain with the state and block environment stored
+          at the file, if it exists, and dumps the chain's state on exit.
 
       --timestamp <NUM>
           The timestamp of the genesis block
@@ -148,22 +157,26 @@ Server options:
           Disable CORS
 
       --no-request-size-limit
-          Disable the default request body size limit. At time of writing the default limit is 2MB
+          Disable the default request body size limit. At time of writing the
+          default limit is 2MB
 
 Fork config:
       --compute-units-per-second <CUPS>
-          Sets the number of assumed available compute units per second for this provider
+          Sets the number of assumed available compute units per second for this
+          provider
           
           default value: 330
           
           See also --fork-url and
           <https://docs.alchemy.com/reference/compute-units#what-are-cups-compute-units-per-second>
 
   -f, --fork-url <URL>
-          Fetch state over a remote endpoint instead of starting from an empty state.
+          Fetch state over a remote endpoint instead of starting from an empty
+          state.
           
-          If you want to fetch state from a specific block number, add a block number like
-          `http://localhost:8545@1400000` or use the `--fork-block-number` argument.
+          If you want to fetch state from a specific block number, add a block
+          number like `http://localhost:8545@1400000` or use the
+          `--fork-block-number` argument.
           
           [aliases: rpc-url]
 
@@ -173,11 +186,12 @@ Fork config:
           See --fork-url.
 
       --fork-chain-id <CHAIN>
-          Specify chain id to skip fetching it from remote endpoint. This enables offline-start
-          mode.
+          Specify chain id to skip fetching it from remote endpoint. This
+          enables offline-start mode.
           
-          You still must pass both `--fork-url` and `--fork-block-number`, and already have your
-          required state cached on disk, anything missing locally would be fetched from the remote.
+          You still must pass both `--fork-url` and `--fork-block-number`, and
+          already have your required state cached on disk, anything missing
+          locally would be fetched from the remote.
 
       --fork-header <HEADERS>
           Headers to use for the rpc client, e.g. "User-Agent: test-agent"
@@ -219,7 +233,8 @@ Fork config:
           Default value 5
 
       --timeout <timeout>
-          Timeout in ms for requests sent to remote JSON-RPC server in forking mode.
+          Timeout in ms for requests sent to remote JSON-RPC server in forking
+          mode.
           
           Default value 45000
 
@@ -233,8 +248,9 @@ Environment config:
           The chain ID
 
       --code-size-limit <CODE_SIZE>
-          EIP-170: Contract code size limit in bytes. Useful to increase this because of tests. To
-          disable entirely, use `--disable-code-size-limit`. By default, it is 0x6000 (~25kb)
+          EIP-170: Contract code size limit in bytes. Useful to increase this
+          because of tests. To disable entirely, use
+          `--disable-code-size-limit`. By default, it is 0x6000 (~25kb)
 
       --disable-block-gas-limit
           Disable the `call.gas_limit <= block.gas_limit` constraint