ripgrep-api

Coder-friendly Rust API wrapper around ripgrep's core crates.

Install

Crates.io:

ripgrep-api = "0.1"

Git dependency (current repo):

ripgrep-api = { git = "https://github.com/AlextheYounga/ripgrep-api.git" }

Quickstart

use ripgrep_api::SearchBuilder;

let matches: Vec<_> = SearchBuilder::new("todo")
    .path(".")
    .glob("**/*.rs")
    .smart_case()
    .context(2)
    .build()?
    .collect();

for mat in matches {
    println!("{}:{}:{}", mat.path.display(), mat.line.unwrap_or(0), mat.text);
}
# Ok::<(), ripgrep_api::SearchError>(())

Streaming callbacks

use ripgrep_api::{Match, SearchBuilder};

let root = ".";
SearchBuilder::new("alpha")
    .path(root)
    .for_each(|mat: &Match| {
        println!("{}:{}", mat.path.display(), mat.line.unwrap_or(0));
        true
    })?;
# Ok::<(), ripgrep_api::SearchError>(())

In-memory search

use ripgrep_api::SearchBuilder;

let haystack = b"zero\nmatch\nthree\n";
let matches = SearchBuilder::new("match")
    .search_slice(haystack)?;

assert_eq!(matches.len(), 1);
# Ok::<(), ripgrep_api::SearchError>(())

PCRE2 (feature flag)

# #[cfg(feature = "pcre2")]
# {
use ripgrep_api::SearchBuilder;

let matches = SearchBuilder::new(r"(foo)(bar)\1")
    .pcre2()
    .search_slice(b"foobarfoo")?;

assert_eq!(matches.len(), 1);
# Ok::<(), ripgrep_api::SearchError>(())
# }

Enable the feature in Cargo:

ripgrep-api = { version = "0.1", features = ["pcre2"] }

Performance knobs

use ripgrep_api::SearchBuilder;
use grep_searcher::MmapChoice;

let matches = SearchBuilder::new("alpha")
    .path(".")
    .threads(4)
    .memory_map(unsafe { MmapChoice::auto() })
    .heap_limit(64 * 1024)
    .build()?
    .collect::<Vec<_>>();
# Ok::<(), ripgrep_api::SearchError>(())

Custom file types and overrides

use ripgrep_api::SearchBuilder;

let matches = SearchBuilder::new("alpha")
    .path(".")
    .type_add("notes", "*.note")
    .type_("notes")
    .glob("!ignored.note")
    .build()?
    .collect::<Vec<_>>();
# Ok::<(), ripgrep_api::SearchError>(())

Limiting total results

limit(n) caps the total number of results across all files — the API equivalent of rg ... | head -n. The search short-circuits once the limit is reached, so it stays efficient on large codebases.

use ripgrep_api::SearchBuilder;

let first_five: Vec<_> = SearchBuilder::new("TODO")
    .path(".")
    .glob("**/*.rs")
    .limit(5)
    .build()?
    .collect();

assert!(first_five.len() <= 5);
# Ok::<(), ripgrep_api::SearchError>(())

This is different from max_count(n), which limits matches per file. You can combine them: max_count(1).limit(10) returns at most 10 results, with at most 1 from any single file.

Walk-only file listing

use ripgrep_api::SearchBuilder;

let files = SearchBuilder::new("irrelevant")
    .path(".")
    .glob("**/*.rs")
    .walk_files()?;

assert!(!files.is_empty());
# Ok::<(), ripgrep_api::SearchError>(())

rg flag -> API method