Nivel 2 · Practicante· Lección 8 de 8 · 45 min
Proyecto: una herramienta de búsqueda para la línea de comandos
Reúne todo el nivel 2 — construye un pequeño grep con un núcleo en forma de biblioteca, manejo de errores limpio, pruebas y un diseño de API idiomático.
Ya sabes lo suficiente para construir una herramienta real. Este proyecto es un pequeño grep: busca un patrón en archivos e imprime las líneas que coinciden. Constrúyelo en tu máquina: crea el proyecto con cargo new minigrep y sigue los pasos.
Diseño
minigrep/
├── Cargo.toml
├── src/
│ ├── main.rs // análisis de argumentos, E/S, códigos de salida
│ └── lib.rs // Config, search, Match — puro y comprobable
└── tests/
└── cli.rs
Objetivos: minigrep [-i] [-n] PATRÓN ARCHIVO..., con código de salida 0 si algo coincidió, 1 si nada coincidió y 2 en caso de error: la misma convención que grep.
El núcleo de la biblioteca
Todo el núcleo se ejecuta en el Playground, así que puedes experimentar antes de crear archivos:
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Config {
pub pattern: String,
pub paths: Vec<String>,
pub ignore_case: bool,
pub line_numbers: bool,
}
#[derive(Debug, PartialEq, Eq)]
pub enum ConfigError {
MissingPattern,
MissingPath,
UnknownFlag(String),
}
impl std::fmt::Display for ConfigError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
ConfigError::MissingPattern => write!(f, "missing PATTERN"),
ConfigError::MissingPath => write!(f, "missing FILE"),
ConfigError::UnknownFlag(flag) => write!(f, "unknown flag `{flag}`"),
}
}
}
impl std::error::Error for ConfigError {}
impl Config {
/// Construye una configuración a partir de los argumentos (sin el nombre del programa).
pub fn parse<I>(args: I) -> Result<Config, ConfigError>
where
I: IntoIterator<Item = String>,
{
let mut ignore_case = false;
let mut line_numbers = false;
let mut positional = Vec::new();
for arg in args {
match arg.as_str() {
"-i" | "--ignore-case" => ignore_case = true,
"-n" | "--line-number" => line_numbers = true,
flag if flag.starts_with('-') && flag.len() > 1 => {
return Err(ConfigError::UnknownFlag(arg));
}
_ => positional.push(arg),
}
}
let mut positional = positional.into_iter();
let pattern = positional.next().ok_or(ConfigError::MissingPattern)?;
let paths: Vec<String> = positional.collect();
if paths.is_empty() {
return Err(ConfigError::MissingPath);
}
Ok(Config { pattern, paths, ignore_case, line_numbers })
}
}
/// Una línea coincidente. Toma prestado del texto en el que se busca.
#[derive(Debug, PartialEq, Eq)]
pub struct Match<'a> {
pub line_number: usize,
pub line: &'a str,
}
/// Devuelve todas las líneas de `contents` que contienen `pattern`.
pub fn search<'a>(pattern: &str, contents: &'a str, ignore_case: bool) -> Vec<Match<'a>> {
let needle = if ignore_case { pattern.to_lowercase() } else { pattern.to_string() };
contents
.lines()
.enumerate()
.filter(|(_, line)| {
if ignore_case {
line.to_lowercase().contains(&needle)
} else {
line.contains(&needle)
}
})
.map(|(i, line)| Match { line_number: i + 1, line })
.collect()
}
fn main() {
let poem = "I'm nobody! Who are you?\nAre you nobody, too?\nThen there's a pair of us - don't tell!";
let config = Config::parse(["-i", "-n", "ARE", "poem.txt"].map(String::from)).unwrap();
for m in search(&config.pattern, poem, config.ignore_case) {
println!("{}:{}", m.line_number, m.line);
}
println!("{:?}", Config::parse(["--wat".to_string()]));
}
Detalles de diseño en los que merece la pena fijarse:
Config::parseacepta cualquierIntoIterator<Item = String>. En producción le pasasstd::env::args().skip(1); en las pruebas le pasas un array. No hay estado global, así que es trivial de probar.- Los errores son un enum pequeño, no cadenas.
maindecide cómo presentarlos. searches una función pura que va del texto a las coincidencias. No hace E/S y devuelve slices prestados, así que no se copia nada.
El binario
// src/main.rs
use std::process::ExitCode;
use std::{env, fs};
use minigrep::{search, Config};
fn main() -> ExitCode {
let config = match Config::parse(env::args().skip(1)) {
Ok(c) => c,
Err(e) => {
eprintln!("minigrep: {e}");
eprintln!("usage: minigrep [-i] [-n] PATTERN FILE...");
return ExitCode::from(2);
}
};
let mut found = false;
let mut failed = false;
let many = config.paths.len() > 1;
for path in &config.paths {
let contents = match fs::read_to_string(path) {
Ok(c) => c,
Err(e) => {
eprintln!("minigrep: {path}: {e}");
failed = true;
continue;
}
};
for m in search(&config.pattern, &contents, config.ignore_case) {
found = true;
if many {
print!("{path}:");
}
if config.line_numbers {
print!("{}:", m.line_number);
}
println!("{}", m.line);
}
}
if failed {
ExitCode::from(2)
} else if found {
ExitCode::SUCCESS
} else {
ExitCode::from(1)
}
}
Un archivo ilegible no impide que se busque en los demás: se informa del error por stderr y el bucle continúa.
Pruebas
Las pruebas unitarias van al final de lib.rs:
#[cfg(test)]
mod tests {
use super::*;
fn args(list: &[&str]) -> Vec<String> {
list.iter().map(|s| s.to_string()).collect()
}
#[test]
fn parses_flags_in_any_position() {
let c = Config::parse(args(&["needle", "-i", "a.txt", "-n", "b.txt"])).unwrap();
assert!(c.ignore_case && c.line_numbers);
assert_eq!(c.paths, ["a.txt", "b.txt"]);
}
#[test]
fn rejects_unknown_flags() {
assert_eq!(
Config::parse(args(&["-x", "p", "f"])),
Err(ConfigError::UnknownFlag("-x".into()))
);
}
#[test]
fn case_sensitive_by_default() {
let text = "Rust\nrust\nTrust";
let lines: Vec<_> = search("rust", text, false).iter().map(|m| m.line_number).collect();
assert_eq!(lines, [2, 3]);
}
#[test]
fn case_insensitive_matches_all() {
assert_eq!(search("RUST", "Rust\nrust\nTrust", true).len(), 3);
}
}
Para las pruebas de extremo a extremo del binario compilado, el crate assert_cmd lo ejecuta y comprueba su salida y su código de salida.
Llévalo más lejos
Cada uno de estos puntos es un ejercicio que merece la pena:
- Usa
clap. Sustituye el analizador escrito a mano por#[derive(Parser)]y obtén gratis--help,--versiony la validación. - Expresiones regulares. Añade el crate
regexy una opción-E. Compila laRegexuna sola vez, fuera del bucle. - Lectura en flujo.
read_to_stringcarga el archivo entero. Cambia aBufReader::lines()para que un log de 10 GB no necesite 10 GB de memoria. ¿Cómo cambia esoMatch<'a>? - Entrada estándar. Cuando no se dé ningún archivo, o el archivo sea
-, lee de stdin. Abstrae el origen conBox<dyn BufRead>o con un genéricoR: BufRead. - Búsqueda recursiva. Añade
-rcon el cratewalkdir(oignore, que respeta.gitignore). - Color. Resalta la coincidencia cuando stdout sea una terminal (
std::io::IsTerminal). - Mide el rendimiento frente a
grepyripgrepcon un archivo grande. Después lee cómo consigue ripgrep su velocidad.
Punto de control del nivel 2
Estás listo para el nivel 3 si puedes:
- Escribir una función genérica con restricciones de trait y explicar qué hace con ella la monomorfización.
- Explicar qué significa
'aen una firma y cuándo la elisión lo pone por ti. - Elegir entre
Box,Rc,RefCelly la propiedad simple para una estructura de datos dada. - Expresar una transformación de datos como una cadena de iteradores.
- Diseñar un enum de error, implementar
Frompara sus orígenes y probar tanto el camino de éxito como el de fallo.
Comprueba lo que has entendido
Elige una respuesta para ver la explicación.
1.¿Por qué poner la lógica de búsqueda en
lib.rsy mantenermain.rspequeño?2.¿Dónde debe imprimir los mensajes de error una CLI bien hecha?
3.¿Por qué
searchdevuelveVec<Match<'a>>tomando prestado del contenido en lugar de ser dueña deStrings?