Morse (Rust)

Utilidad de línea de comandos en Rust que convierte texto (incluyendo algunos signos de puntuación y vocales acentuadas) a código Morse; puede reproducirlo como audio (beeps), imprimirlo en consola y/o exportarlo a un archivo.

Índice

1. Objetivo del proyecto
2. Características actuales
3. Instalación y compilación
4. Uso rápido
5. Interfaz de línea de comandos (flags y argumentos)
6. Ejemplos prácticos
7. Reglas de temporización Morse implementadas
8. Normalización de caracteres y alcance soportado
9. Mapeo Morse completo (letras, números y puntuación)
10. Arquitectura y explicación del código
11. Flujo interno de ejecución
12. Tests
13. Errores y códigos de salida
14. Personalización / extensión
15. Licencia

1. Objetivo del proyecto

Proporcionar una herramienta sencilla y transparente para convertir texto a Morse respetando intervalos estándar, con opciones de velocidad, frecuencia de tono, salida silenciosa y exportación.

2. Características actuales

• Conversión de texto a Morse con separación de palabras mediante /.
• Reproducción audible de puntos y rayas usando la crate actually_beep.
• Ajuste de duración base (unidad) y frecuencia del tono por CLI.
• Modo solo impresión (sin sonido).
• Exportación opcional a archivo.
• Normalización básica de vocales acentuadas y Ñ.
• Soporte de letras A–Z, dígitos 0–9 y signos de puntuación frecuentes (. , ? ! : ; ( ) " ' - / @ = & +).
• Tests unitarios para validar el mapeo y la normalización.

3. Instalación y compilación

Requisitos: Rust estable y Cargo.

git clone <URL_DEL_REPO> morse
cd morse
cargo build --release

Ejecutable resultante:

• Linux/macOS: target/release/morse
• Windows: target\release\morse.exe

Modo desarrollo rápido (debug):

cargo run -- "Texto de prueba"

4. Uso rápido

Ejecutar sin argumentos (pide texto por stdin):

cargo run
Enter text to convert to Morse code: Hola mundo 123

Ejecutar con texto directo y solo imprimir:

cargo run -- --print-only "SOS ayuda"

5. Interfaz de línea de comandos

Sintaxis general:

morse [OPCIONES] [text]

Argumento posicional:

• text: (opcional) Texto a convertir. Si se omite, se solicitará por stdin.

Opciones:

Flag	Largo	Descripción	Valor por defecto
-u	--unit	Duración (ms) de la unidad básica (punto).	200
-f	--freq	Frecuencia del tono.	600
	--print-only	No reproducir sonido; solo mostrar Morse.	false
	--out	Escribir la secuencia Morse en un archivo.	(ninguno)
	--help	Mostrar ayuda.	-

Notas:

• Las palabras se separan con / en la salida textual.
• Entre símbolos de una letra se añade un espacio interno para legibilidad al imprimir.

6. Ejemplos prácticos

Imprimir y sonar (valores por defecto):

./morse "Hola 2025"

Solo imprimir sin sonido:

./morse --print-only "CQ DX"

Reducir velocidad (unidad 120 ms) y elevar frecuencia (750 Hz):

./morse -u 120 -f 750 "SOS"

Exportar a archivo además de sonar:

./morse --out salida.txt "mensaje prueba"

Pipeline (generar Morse y usar otra herramienta):

./morse --print-only "Prueba" | grep .

7. Reglas de temporización Morse implementadas

La unidad (unit) define la base en milisegundos.

• Punto: 1 unidad de sonido.
• Raya: 3 unidades de sonido.
• Silencio entre símbolos dentro de la letra: 1 unidad (implementado tras cada punto/raya).
• Silencio entre letras: 3 unidades.
• Silencio entre palabras: 7 unidades (cuando se detecta / o espacio original).

8. Normalización de caracteres

Reglas aplicadas (función normalize_char):

• Convierte a mayúsculas (Unicode). Ejemplo: ü → Ü.
• Vocales acentuadas y variantes se reducen: Á À Ä Â Ã → A (similar para E, I, O, U).
• Ñ → N.
• Cualquier carácter no soportado y no blanco se ignora silenciosamente.

9. Mapeo Morse completo soportado

Letras y números:

A .-   B -...  C -.-.  D -..  E .    F ..-.  G --.  H ....  I ..  J .---
K -.-  L .-..  M --    N -.   O ---  P .--.  Q --.- R .-.   S ... T -
U ..-  V ...-  W .--   X -..- Y -.-- Z --..

1 .---- 2 ..--- 3 ...-- 4 ....- 5 .....
6 -.... 7 --... 8 ---.. 9 ----. 0 -----

Puntuación y símbolos:

. .-.-.-   , --..--   ? ..--..   ! -.-.--   : ---...   ; -.-.-.
( -.--.    ) -.--.-   " .-..-.   ' .----.   - -....-   / -..-.
@ .--.-.   = -...-    & .-...    + .-.-.

10. Arquitectura y explicación del código

Archivos principales:

• src/main.rs: Entrada del programa, parseo de CLI, construcción de secuencia Morse, reproducción y exportación.
• src/morse.rs: Módulo con el HashMap<char, &str> y la función de normalización.
• src/lib.rs: Re-exporta funciones para permitir que los tests accedan al módulo.
• tests/morse_mapping.rs: Pruebas unitarias del mapeo y normalización.

Componentes clave:

1. build_cli(): Define la interfaz (usa clap).
2. normalize_char(c): Normaliza acentos y mayúsculas.
3. initialize_hashmap(): Crea el diccionario de conversión.
4. morse_for_text(text): Genera la representación textual final (usa / para palabras).
5. play_morse(sequence, cfg): Recorre la secuencia y reproduce audio respetando los tiempos.
6. PlayerCfg: Configuración de ejecución (frecuencia, unidad, modo silencioso, archivo de salida).

11. Flujo interno de ejecución

1. Parseo de argumentos (frecuencia, unidad, flags, texto posicional).
2. Lectura por stdin si no se pasó texto posicional.
3. Normalización carácter a carácter y consulta al HashMap.
4. Construcción de cadena Morse (separadores espacios y /).
5. Impresión en consola (si --print-only o --out).
6. Escritura a archivo (si --out).
7. Reproducción acústica (omitida si --print-only).

12. Tests

Ejecutar:

cargo test

Cobertura actual (conceptual):

• Verificación de mapeo básico (letras, números, puntuación seleccionada).
• Verificación de normalización (acentos y Ñ).

13. Errores y códigos de salida

• Entrada vacía: mensaje de error a stderr y exit(1).
• Fallos en beeps: no aborta; registra beep failed en stderr.
• Error al escribir archivo (--out): mensaje en stderr y continúa.

14. Personalización / extensión

• Añadir símbolo: editar initialize_hashmap() e introducir morse_map.insert('X', "-..-");.
• Cambiar lógica de separación: modificar morse_for_text (por ejemplo, para no usar /).
• Integrar otra librería de audio: reemplazar llamadas a beep_with_hz_and_millis.
• Ajustar tiempos: pasar otro valor a --unit o cambiar por defecto en CLI.

15. Licencia

Incluye un archivo LICENSE (por ejemplo MIT) y actualiza esta sección. Mientras no exista, se considera sin licencia explícita (no recomendado para uso productivo externo).

---

Hecho en Rust 🦀 para demostración educativa de procesamiento simple y temporización Morse.

English Quick Summary

Rust CLI tool that converts (normalized) text to Morse, plays it (beeps), prints it, and/or writes it to a file. Adjustable unit timing (ms) and tone frequency, print-only mode, basic accent normalization, punctuation support, and minimal tests. See sections above for full mapping and timing rules.