comex 1.0.0

Fast, dependency-free comment extraction and removal for source files, with content-based syntax detection (no file extensions required).
Documentation
//! `comex` command line interface.
//!
//! Argument parsing is hand-rolled to keep the crate dependency-free.

use std::io::{Read, Write};
use std::process::ExitCode;

use comex::{Detection, Dialect, Options};

const USAGE: &str = "\
comex - strip comments from source code, or keep only the comments

USAGE:
    comex [OPTIONS] [FILE]...

With no FILE, or when FILE is `-`, reads standard input.

MODES:
    (default)             print the code with every comment removed
    -c, --comments        print only the comments
    -d, --detect          print the detected syntax and confidence, change nothing

OPTIONS:
    -s, --syntax <NAME>   force a comment syntax instead of detecting it
    -i, --in-place        rewrite each FILE instead of writing to stdout
    -k, --keep-lines      preserve line numbering (leave blank lines behind)
    -b, --keep-blank      keep lines that held nothing but a comment
    -m, --markers         keep comment markers when printing comments
    -D, --docstrings      treat leading triple-quoted strings as comments
    -S, --no-shebang      allow a leading `#!` line to be treated as a comment
    -n, --no-trim         do not trim whitespace left behind by a removed comment
        --stats           print per-file counts to stderr
    -l, --list            list the supported comment syntaxes
    -h, --help            print this help
    -V, --version         print version

EXAMPLES:
    comex src/main.rs                  # code without comments
    comex -c README.md                 # the HTML comments hidden in a README
    cat app.py | comex -c -m           # comments, markers intact
    comex -i -s hash deploy.sh         # rewrite in place, no detection
    comex -d unknown_file              # what does comex think this is?
";

fn main() -> ExitCode {
    match run() {
        Ok(code) => code,
        Err(e) => {
            eprintln!("comex: {e}");
            ExitCode::FAILURE
        }
    }
}

#[derive(Default)]
struct Args {
    files: Vec<String>,
    comments: bool,
    detect: bool,
    in_place: bool,
    stats: bool,
    syntax: Option<Dialect>,
    opts_keep_lines: bool,
    opts_keep_blank: bool,
    opts_markers: bool,
    opts_docstrings: bool,
    opts_no_shebang: bool,
    opts_no_trim: bool,
}

fn run() -> Result<ExitCode, String> {
    let mut a = Args::default();
    let mut argv = std::env::args().skip(1);
    let mut only_files = false;

    while let Some(arg) = argv.next() {
        if only_files || arg == "-" || !arg.starts_with('-') {
            a.files.push(arg);
            continue;
        }
        match arg.as_str() {
            "--" => only_files = true,
            "-h" | "--help" => {
                print!("{USAGE}");
                return Ok(ExitCode::SUCCESS);
            }
            "-V" | "--version" => {
                println!("comex {}", env!("CARGO_PKG_VERSION"));
                return Ok(ExitCode::SUCCESS);
            }
            "-l" | "--list" => {
                for d in Dialect::ALL {
                    println!("{:<9} {}", d.name(), d.describe());
                }
                return Ok(ExitCode::SUCCESS);
            }
            "-c" | "--comments" => a.comments = true,
            "-d" | "--detect" => a.detect = true,
            "-i" | "--in-place" => a.in_place = true,
            "-k" | "--keep-lines" => a.opts_keep_lines = true,
            "-b" | "--keep-blank" => a.opts_keep_blank = true,
            "-m" | "--markers" => a.opts_markers = true,
            "-D" | "--docstrings" => a.opts_docstrings = true,
            "-S" | "--no-shebang" => a.opts_no_shebang = true,
            "-n" | "--no-trim" => a.opts_no_trim = true,
            "--stats" => a.stats = true,
            "-s" | "--syntax" => {
                let name = argv.next().ok_or("--syntax needs a value (try --list)")?;
                a.syntax = Some(
                    Dialect::from_name(&name)
                        .ok_or_else(|| format!("unknown syntax `{name}` (try --list)"))?,
                );
            }
            other => {
                // Support `-s=hash`, `--syntax=hash` and bundled short flags (`-cm`).
                if let Some(name) = other
                    .strip_prefix("--syntax=")
                    .or(other.strip_prefix("-s="))
                {
                    a.syntax = Some(
                        Dialect::from_name(name)
                            .ok_or_else(|| format!("unknown syntax `{name}` (try --list)"))?,
                    );
                } else if !other.starts_with("--") && other.len() > 2 {
                    for c in other[1..].chars() {
                        expand_short(&mut a, c)?;
                    }
                } else {
                    return Err(format!("unknown option `{other}` (try --help)"));
                }
            }
        }
    }

    if a.in_place && a.files.is_empty() {
        return Err("--in-place needs at least one FILE".into());
    }
    if a.in_place && a.detect {
        return Err("--in-place and --detect do not go together".into());
    }

    let opts = Options {
        preserve_lines: a.opts_keep_lines,
        keep_blank_lines: a.opts_keep_blank,
        trim_trailing_whitespace: !a.opts_no_trim,
        keep_shebang: !a.opts_no_shebang,
        docstrings: a.opts_docstrings,
        strip_markers: !a.opts_markers,
        dedent: true,
    };

    let targets: Vec<String> = if a.files.is_empty() {
        vec!["-".to_string()]
    } else {
        a.files.clone()
    };

    let stdout = std::io::stdout();
    let mut out = std::io::BufWriter::new(stdout.lock());
    let mut failed = false;

    for path in &targets {
        let src = match read_input(path) {
            Ok(s) => s,
            Err(e) => {
                eprintln!("comex: {path}: {e}");
                failed = true;
                continue;
            }
        };

        let detection = comex::detect(&src);
        let syntax = match a.syntax {
            Some(d) => d.syntax(),
            None => detection.syntax(),
        };

        if a.detect {
            report_detection(&mut out, path, &targets, &detection).map_err(io_err)?;
            continue;
        }

        let result = if a.comments {
            comex::extract_comments_with(&src, &syntax, &opts)
        } else {
            comex::strip_comments_with(&src, &syntax, &opts)
        };

        if a.stats {
            let n = comex::comments_with(&src, &syntax, &opts).len();
            let saved = src.len().saturating_sub(result.len());
            eprintln!(
                "comex: {}: syntax={} confidence={:.2} comments={} bytes={}->{} (-{})",
                display_path(path),
                syntax.dialect.name(),
                detection.confidence,
                n,
                src.len(),
                result.len(),
                saved
            );
        }

        if a.in_place {
            if let Err(e) = std::fs::write(path, result.as_bytes()) {
                eprintln!("comex: {path}: {e}");
                failed = true;
            }
        } else {
            out.write_all(result.as_bytes()).map_err(io_err)?;
        }
    }

    out.flush().map_err(io_err)?;
    Ok(if failed {
        ExitCode::FAILURE
    } else {
        ExitCode::SUCCESS
    })
}

fn expand_short(a: &mut Args, c: char) -> Result<(), String> {
    match c {
        'c' => a.comments = true,
        'd' => a.detect = true,
        'i' => a.in_place = true,
        'k' => a.opts_keep_lines = true,
        'b' => a.opts_keep_blank = true,
        'm' => a.opts_markers = true,
        'D' => a.opts_docstrings = true,
        'S' => a.opts_no_shebang = true,
        'n' => a.opts_no_trim = true,
        _ => return Err(format!("unknown flag `-{c}` (try --help)")),
    }
    Ok(())
}

fn report_detection(
    out: &mut impl Write,
    path: &str,
    targets: &[String],
    d: &Detection,
) -> std::io::Result<()> {
    let prefix = if targets.len() > 1 {
        format!("{}: ", display_path(path))
    } else {
        String::new()
    };
    writeln!(
        out,
        "{prefix}{} (confidence {:.2}) - {}",
        d.dialect.name(),
        d.confidence,
        d.dialect.describe()
    )?;
    let top: Vec<String> = d
        .scores
        .iter()
        .take(3)
        .filter(|(_, s)| *s > 0)
        .map(|(dl, s)| format!("{}={s}", dl.name()))
        .collect();
    if !top.is_empty() {
        writeln!(out, "{prefix}scores: {}", top.join(" "))?;
    }
    Ok(())
}

fn read_input(path: &str) -> Result<String, String> {
    let bytes = if path == "-" {
        let mut buf = Vec::new();
        std::io::stdin()
            .read_to_end(&mut buf)
            .map_err(|e| e.to_string())?;
        buf
    } else {
        std::fs::read(path).map_err(|e| e.to_string())?
    };
    String::from_utf8(bytes).map_err(|_| "not valid UTF-8".to_string())
}

fn display_path(path: &str) -> &str {
    if path == "-" {
        "<stdin>"
    } else {
        path
    }
}

fn io_err(e: std::io::Error) -> String {
    // A closed pipe (`comex big.c | head`) is a normal way for this program to end.
    if e.kind() == std::io::ErrorKind::BrokenPipe {
        std::process::exit(0);
    }
    e.to_string()
}