Capítulo 11: Módulos
Organizando bio_toolkit: un proyecto bioinformático en varios archivos
A estas alturas, los programas de ejemplo rondan las 100 o 200 líneas y ya empiezan a doler en un solo main.rs. Este capítulo es la transición de “scripts” a proyecto: dividir el código en módulos con responsabilidades claras, controlar qué se expone y qué se esconde, y documentar para tu yo futuro (y para quien use tu herramienta). De regalo: la estructura que montemos aquí es la base directa del analizador del capítulo 15.
11.1 El árbol de módulos
Todo programa Rust tiene una raíz: main.rs en un ejecutable, lib.rs en una librería. Los módulos cuelgan de esa raíz y pueden anidarse. La forma más compacta de verlos es declararlos inline:
mod analisis {
pub fn contenido_gc(dna: &str) -> f64 {
let gc = dna.bytes().filter(|b| *b == b'G' || *b == b'C').count();
gc as f64 / dna.len() as f64 * 100.0
}
}
fn main() {
println!("GC: {:.1}%", analisis::contenido_gc("ATGGCCTTTTAA"));
}
// GC: 41.7%El módulo analisis agrupa la función, y se accede con la ruta analisis::contenido_gc. En un proyecto real, los módulos viven en sus propios archivos y forman un árbol:
flowchart TD
L["lib.rs — raíz del crate"] --> S["secuencia.rs"]
L --> F["fasta.rs"]
L --> T["traductor.rs"]
S --> S1["struct Dna + métodos"]
F --> F1["parsear(texto)"]
T --> T1["tabla de codones + traducir"]
11.2 Privacidad: pub
Regla por defecto: todo lo declarado dentro de un módulo es privado. Solo la raíz (main/lib del crate) y el módulo mismo pueden usarlo. Para que algo trascienda su módulo, se marca pub:
mod analisis {
pub fn contenido_gc(dna: &str) -> f64 {
let gc = dna.bytes().filter(|b| *b == b'G' || *b == b'C').count();
gc as f64 / dna.len() as f64 * 100.0
}
fn redondear(x: f64) -> f64 {
(x * 10.0).round() / 10.0
}
}
fn main() {
println!("GC: {:.1}%", analisis::contenido_gc("ATGGCCTTTTAA"));
// println!("{:?}", analisis::redondear(41.66)); // ⛔ NO COMPILA
}
// GC: 41.7%redondear es un detalle interno: el mundo exterior no puede llamarla, y esa pared es lo que permite refactorizar el interior de un módulo sin miedo a romper a nadie. La palabra pub va también en structs, campos (pub id: String), enums y sus variantes. En proyectos grandes verás pub(crate): público dentro del crate, invisible para el exterior — el punto medio.
11.3 Rutas y use
Las rutas completas (crate::analisis::contenido_gc) funcionan siempre (crate:: significa “desde la raíz”), pero escribir todo el camino cansa. El use que ya veníamos usando importa nombres:
use std::collections::HashMap; // ruta absoluta de la biblioteca estándar
mod analisis {
pub fn contenido_gc(dna: &str) -> f64 {
let gc = dna.bytes().filter(|b| *b == b'G' || *b == b'C').count();
gc as f64 / dna.len() as f64 * 100.0
}
}
fn main() {
use analisis::contenido_gc; // importar desde tu propio módulo
println!("GC: {:.1}%", contenido_gc("ATGGCCTTTTAA"));
}
// GC: 41.7%Dos ayudas más: as renombora (use analisis::contenido_gc as gc; — útil para nombres largos o repetidos), y super:: referencia el módulo padre (desde un submódulo, super::contenido_gc). Si prefieres ver rutas relativas: self:: es el módulo actual.
11.4 Un módulo, un archivo
En proyectos reales, cada módulo migra a su archivo .rs. La convención moderna: en la raíz declaras mod secuencia; y el compilador busca src/secuencia.rs:
bio_toolkit/
├── Cargo.toml
└── src/
├── main.rs
├── lib.rs
├── secuencia.rs
└── fasta.rs
El contenido de cada archivo es exactamente lo que iba entre las llaves del mod. Montemos el proyecto completo — bio_toolkit, nuestra caja de herramientas bioinformática creciente:
src/lib.rs — la raíz de la librería, que solo declara y documenta:
//! bio_toolkit: herramientas de secuencias para el curso
//! "Rust para biólogos".
pub mod fasta;
pub mod secuencia;src/secuencia.rs — tipos y análisis de secuencias:
/// Una secuencia de ADN con identificador.
#[derive(Debug)]
pub struct Dna {
pub id: String,
pub bases: String,
}
impl Dna {
/// Crea una secuencia nueva a partir de datos prestados.
pub fn nueva(id: &str, bases: &str) -> Dna {
Dna { id: String::from(id), bases: String::from(bases) }
}
/// Longitud en pares de bases.
pub fn longitud(&self) -> usize {
self.bases.len()
}
/// Contenido de GC en porcentaje.
pub fn contenido_gc(&self) -> f64 {
let gc = self.bases.bytes().filter(|b| *b == b'G' || *b == b'C').count();
gc as f64 / self.bases.len() as f64 * 100.0
}
}src/fasta.rs — parseo de texto FASTA (puro: recibe &str, no toca archivos; esa parte llega en el capítulo 12):
/// Divide un texto FASTA en pares (id, secuencia).
/// El id es lo que sigue a '>' en cada encabezado.
pub fn parsear(texto: &str) -> Vec<(String, String)> {
let mut registros = Vec::new();
let mut id_actual = String::new();
let mut bases = String::new();
for linea in texto.lines() {
let linea = linea.trim();
if linea.is_empty() {
continue;
}
if let Some(encabezado) = linea.strip_prefix('>') {
if !id_actual.is_empty() {
registros.push((id_actual, bases));
}
id_actual = encabezado.split_whitespace().next().unwrap_or("").to_string();
bases = String::new();
} else {
bases.push_str(linea);
}
}
if !id_actual.is_empty() {
registros.push((id_actual, bases));
}
registros
}src/main.rs — el ejecutable, que consume la librería:
use bio_toolkit::fasta::parsear;
use bio_toolkit::secuencia::Dna;
fn main() {
let fasta_texto = ">genA mini-gen de ejemplo
ATGGCCTTTTAA
>genB fragmento GC alto
GCCGGCCTTAAGGC";
let registros = parsear(fasta_texto);
println!("{} registros en el archivo\n", registros.len());
for (id, bases) in ®istros {
let seq = Dna::nueva(id, bases);
println!("{}: {} pb, {:.1}% GC", seq.id, seq.longitud(), seq.contenido_gc());
}
}Ejecutado con cargo run:
2 registros en el archivo
genA: 12 pb, 41.7% GC
genB: 14 pb, 71.4% GC
Detalles que no deben pasar de largo: el texto FASTA va entre comillas y usa saltos de línea literales (Rust permite strings multilínea); strip_prefix('>') devuelve Option y con if let se lee como “si la línea empieza con >…”; y split_whitespace().next() toma solo la primera palabra del encabezado como id (la descripción completa puede seguir después).
11.5 ¿Por qué lib.rs y main.rs?
Podríamos meter todo en main.rs y acabar. La separación librería + ejecutable tiene dos ventajas científicas. Primera: los tests del capítulo 13 pueden importar bio_toolkit::fasta::parsear directamente y probar la lógica sin ejecutar el programa completo. Segunda: el día que quieras hacer otra herramienta (un visualizador, un servidor), reutiliza la librería sin copiar nada. La regla de oro que emerge: main.rs solo coordina (leer argumentos, llamar funciones, imprimir); la lógica vive en módulos. Un main.rs de 20 líneas que orquesta módulos de 200 es señal de salud; el inverso, de deuda.
11.6 Documentación ejecutable
Los comentarios /// antes de un elemento se llaman doc comments, y no son decoración: cargo doc --open compila un sitio web con tu API, y los ejemplos que incluyas en ellos se compilan y ejecutan como tests. Mira el estilo de secuencia.rs arriba: cada elemento público lleva su frase. Un doc comment con ejemplo se ve así:
/// Devuelve el contenido de GC en porcentaje.
///
/// # Ejemplo
/// ```
/// use bio_toolkit::secuencia::Dna;
/// let s = Dna::nueva("x", "GC");
/// assert_eq!(s.contenido_gc(), 100.0);
/// ```
pub fn contenido_gc(&self) -> f64 {El //! que abrió lib.rs documenta el módulo completo (nota la dirección de las barras: //! habla del archivo, /// del elemento siguiente). La documentación que se compila no se desactualiza: si cambias la función y olvidas el ejemplo, cargo test falla.
Ejercicios
Ejercicio 11.1 · Tu primer módulo
Crea el proyecto bio_toolkit y agrega el módulo traductor (en su propio archivo src/traductor.rs) con las funciones tabla_codones() y traducir() del capítulo 7, ambas pub. Decláralo en lib.rs y úsalo desde main.rs para traducir ATGGCCTTTTAA.
Solución
En src/lib.rs:
pub mod traductor;En src/traductor.rs:
use std::collections::HashMap;
/// Tabla de codones (subconjunto; completa en el cap. 7).
pub fn tabla_codones() -> HashMap<&'static str, char> {
HashMap::from([
("ATG", 'M'), ("GCC", 'A'), ("TTT", 'F'),
("TAA", '*'), ("TAG", '*'), ("TGA", '*'),
])
}
/// Traduce una secuencia de ADN a proteína (marco 0).
pub fn traducir(dna: &str) -> String {
let tabla = tabla_codones();
let mut proteina = String::new();
for i in (0..dna.len()).step_by(3) {
if i + 3 > dna.len() {
break;
}
let aa = tabla.get(&dna[i..i + 3]).copied().unwrap_or('X');
proteina.push(aa);
}
proteina
}En src/main.rs:
use bio_toolkit::traductor::traducir;
fn main() {
println!("Proteína: {}", traducir("ATGGCCTTTTAA"));
}
// Proteína: MAF*El use importa directamente la función desde el módulo compilado: el main ya no sabe (ni le importa) dónde vive la tabla de codones. Bienvenido al diseño modular: cada pieza se mueve, se prueba y se documenta por separado.
Ejercicio 11.2 · La pared de la privacidad
Mueve la función contenido_gc a un módulo analisis sin marcarla pub, e intenta llamarla desde main. Lee el error completo, explica qué te dice y corrígelo.
Solución
El error es del estilo:
error[E0603]: function `contenido_gc` is private
--> src/main.rs:4:38
|
4 | println!("{:.1}", analisis::contenido_gc("ATG"));
| ^^^^^^^^^^^^ function `contenido_gc` is private
Aparte de señalar la línea exacta, el error sugiere: “consider marking contenido_gc as pub”. El compilador interpreta el acceso denegado como una decisión de diseño que quizá olvidaste publicar — acertó. La corrección es pub fn contenido_gc(...) en el módulo. Lección: la privacidad no es un estorbo burocrático sino un contrato de superficie pública; cada pub que escribes es una promesa de API que mantendrás.
Ejercicio 11.3 · Importaciones con alias
En main.rs, importa el módulo secuencia con as seq y úsalo para crear dos Dna e imprimir un comparativo de longitudes y GC.
Solución
use bio_toolkit::secuencia as seq;
fn main() {
let a = seq::Dna::nueva("genA", "ATGGCCTTTTAA");
let b = seq::Dna::nueva("genB", "GCCGGCCTTAAGGC");
for s in [&a, &b] {
println!("{}: {} pb, {:.1}% GC", s.id, s.longitud(), s.contenido_gc());
}
let mas_larga = if a.longitud() >= b.longitud() { &a } else { &b };
println!("Más larga: {}", mas_larga.id);
}
// genA: 12 pb, 41.7% GC
// genB: 14 pb, 71.4% GC
// Más larga: genBuse ... as seq acorta el prefijo sin cambiar el módulo. El array [&a, &b] presta ambas secuencias para el bucle de reporte. Cuando tu API crezca (bio_toolkit::analisis_estadistico::diversidad), los alias dejarán de ser capricho y serán higiene.
Ejercicio 11.4 · Parsea un FASTA multilínea
Agrega a fasta.rs la función pub fn cantidad_registros(texto: &str) -> usize y prueba parsear con un FASTA cuya secuencia esté partida en dos líneas, verificando que las líneas se unen.
Solución
pub fn cantidad_registros(texto: &str) -> usize {
parsear(texto).len()
}Y la prueba en main.rs:
use bio_toolkit::fasta::{parsear, cantidad_registros};
fn main() {
let fasta = ">genA dividido en dos líneas
ATGGCC
TTTTAA";
println!("Registros: {}", cantidad_registros(fasta));
for (id, bases) in parsear(fasta) {
println!("{} -> {} pb: {}", id, bases.len(), bases);
}
}
// Registros: 1
// genA -> 12 pb: ATGGCCTTTTAALa clave del comportamiento está en parsear: las líneas de secuencia se concatenan con push_str hasta que aparece el siguiente > (o el final), así que un genoma real partido en 60 columnas de texto se reensambla solo. Ese es exactamente el formato en que los archivos FASTA llegan del mundo real — y en el capítulo 12 lo leeremos directo desde disco.
Ejercicio 11.5 · Documenta y genera tu sitio
Agrega doc comments /// a Dna::nueva, Dna::longitud y fasta::parsear, incluyendo en contenido_gc un bloque de ejemplo como el del capítulo. Ejecuta cargo doc --open y navega tu API; luego cargo test y observa que tu ejemplo se ejecutó como test.
Solución
Doc comments de ejemplo para secuencia.rs:
/// Crea una secuencia nueva a partir de datos prestados.
///
/// # Ejemplo
/// ```
/// use bio_toolkit::secuencia::Dna;
/// let s = Dna::nueva("genA", "ATG");
/// assert_eq!(s.longitud(), 3);
/// ```
pub fn nueva(id: &str, bases: &str) -> Dna {
Dna { id: String::from(id), bases: String::from(bases) }
}Tras cargo doc --open, el navegador muestra el sitio generado con tu módulo, sus funciones y los ejemplos renderizados como bloques de código. Tras cargo test, entre los resultados aparece la línea Doc-tests bio_toolkit con tu ejemplo contado como test: documentación que se verifica sola. Los grandes crates del ecosistema (incluido el bio que conocerás en el capítulo 14) se documentan exactamente así.
