FerrousPath

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::parse acepta cualquier IntoIterator<Item = String>. En producción le pasas std::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. main decide cómo presentarlos.
  • search es 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:

  1. Usa clap. Sustituye el analizador escrito a mano por #[derive(Parser)] y obtén gratis --help, --version y la validación.
  2. Expresiones regulares. Añade el crate regex y una opción -E. Compila la Regex una sola vez, fuera del bucle.
  3. Lectura en flujo. read_to_string carga el archivo entero. Cambia a BufReader::lines() para que un log de 10 GB no necesite 10 GB de memoria. ¿Cómo cambia eso Match<'a>?
  4. Entrada estándar. Cuando no se dé ningún archivo, o el archivo sea -, lee de stdin. Abstrae el origen con Box<dyn BufRead> o con un genérico R: BufRead.
  5. Búsqueda recursiva. Añade -r con el crate walkdir (o ignore, que respeta .gitignore).
  6. Color. Resalta la coincidencia cuando stdout sea una terminal (std::io::IsTerminal).
  7. Mide el rendimiento frente a grep y ripgrep con 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 'a en una firma y cuándo la elisión lo pone por ti.
  • Elegir entre Box, Rc, RefCell y 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 From para 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. 1.¿Por qué poner la lógica de búsqueda en lib.rs y mantener main.rs pequeño?

  2. 2.¿Dónde debe imprimir los mensajes de error una CLI bien hecha?

  3. 3.¿Por qué search devuelve Vec<Match<'a>> tomando prestado del contenido en lugar de ser dueña de Strings?

¿Has terminado la lección y los ejercicios?