skimmd 0.4.1

Read markdown with speed and precision.
Documentation
//! `skimmd` — command-line entry point.
//!
//! Two modes (spec §2):
//! * TOC mode — `skimmd [FILE]` prints the structure table.
//!   (FILE omitted or `-` reads from standard input.)
//! * Range mode — `skimmd FILE RANGE...` prints the requested line ranges,
//!   with data-URL image payloads elided by default (`--raw` for verbatim).
//!
//! Exit codes (spec §9): 0 success; 1 the request could not be satisfied
//! (file / range / stdout errors); 2 clap usage errors (handled by clap).

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

use clap::Parser;
use skimmd::elide::elide_data_urls;
use skimmd::format::{render, render_filtered};
use skimmd::lines::{LineMap, LoadErr, io_reason, load_stdin, load_text};
use skimmd::ranges;
use skimmd::toc::{build_toc, filter_rows};

/// skimmd: TOC and line-range view of a single Markdown file.
#[derive(Parser)]
#[command(
    version,
    about = "Print a Markdown file's structure as a TOC (line numbers and sizes), or read line ranges.",
    after_help = "RANGE grammar: N-M or N- (N- = through the last line). \
        Ranges are comma- and/or space-separated, e.g. 1-5,9-12 or 1-5 9-12. \
        With no ranges, the TOC is printed. \
        Omit FILE (or use -) to read from standard input. \
        Range mode elides data-URL image payloads to `data:…` by default; \
        --raw emits lines verbatim. "
)]
struct Cli {
    /// Filter TOC rows by substring (TOC mode only, ignored in range mode).
    /// |-separated substrings; keep a row if any occurs in its heading or section
    /// body. Case- and whitespace-insensitive, and substring (not whole-word)
    /// matching, so "foo" also matches "food".
    #[arg(short = 'f', long = "filter", value_name = "SUBSTRING")]
    filter: Option<String>,

    /// Range mode: emit lines verbatim, without data-URL elision. Ignored in
    /// TOC mode.
    #[arg(long)]
    raw: bool,

    /// Path to a Markdown file, or `-` for stdin. Omitted (or `-`) reads from stdin.
    #[arg(required = false)]
    file: Option<String>,

    /// Zero or more line ranges. Any range switches to range mode.
    #[arg(value_name = "RANGE")]
    ranges: Vec<String>,
}

fn main() -> ExitCode {
    let cli = Cli::parse(); // clap prints usage and exits 2 on usage errors.

    // Omitted FILE (or "-") reads from standard input.
    let (label, res) = match &cli.file {
        Some(f) if f != "-" => (f.as_str(), load_text(std::path::Path::new(f))),
        _ => ("<stdin>", load_stdin()),
    };
    let text = match res {
        Ok(t) => t,
        Err(LoadErr::Io(e)) => die(&format!("{label}: {}", io_reason(&e))),
        Err(LoadErr::NotUtf8) => die(&format!("{label}: not valid UTF-8")),
    };
    let lm = LineMap::new(text);

    if cli.ranges.is_empty() {
        toc_mode(&lm, cli.filter.as_deref())
    } else {
        range_mode(&lm, &cli.ranges, cli.raw)
    }
}

/// TOC mode: compute rows, optionally filter them with `-f` (which also adds a
/// `matches` count column), and render.
fn toc_mode(lm: &LineMap, filter: Option<&str>) -> ExitCode {
    let rows = build_toc(lm);
    let out = match filter {
        Some(kw) => render_filtered(&filter_rows(lm, &rows, kw)),
        None => render(&rows),
    };
    write_stdout(&out)
}

/// Range mode: parse/validate/normalize all ranges **before any output**, then
/// write each merged range's bytes in order, with no separators. Unless
/// `raw`, each span passes through the data-URL elision transform first
/// (applied per span; elision state does not cross range gaps).
fn range_mode(lm: &LineMap, specs: &[String], raw: bool) -> ExitCode {
    let merged = match ranges::parse(specs, lm.n()) {
        Ok(m) => m,
        Err(e) => die(&e.message()),
    };
    let mut out = String::new();
    for r in &merged {
        let span = lm.span(r.start, r.end);
        if raw {
            out.push_str(span);
        } else {
            out.push_str(&elide_data_urls(span));
        }
    }
    write_stdout(&out)
}

/// Write `out` to stdout via a BufWriter (flushed once). `EPIPE` is a clean
/// exit 0 with no message; any other write error is exit 1 (spec §8.4/§9).
fn write_stdout(out: &str) -> ExitCode {
    let stdout = std::io::stdout();
    let mut w = BufWriter::new(stdout);
    match w.write_all(out.as_bytes()).and_then(|_| w.flush()) {
        Ok(()) => ExitCode::SUCCESS,
        Err(e) if e.kind() == std::io::ErrorKind::BrokenPipe => ExitCode::SUCCESS,
        Err(e) => die(&format!("error writing to stdout: {e}")),
    }
}

/// Print `skimmd: {msg}` to stderr and exit 1.
#[cold]
fn die(msg: &str) -> ! {
    eprintln!("skimmd: {msg}");
    std::process::exit(1);
}