minishell/docs/guia_obligatoria_es.md

# Minishell - Guia de estructura y pasos (parte obligatoria)

Objetivo de este documento
- Proponer una estructura de archivos y datos.
- Describir el proceso paso a paso como tutorial.
- Servir de guion para defensa (explicaciones claras y ordenadas).

Este documento no implementa nada. Solo define el plan y el por que.

---

## 1. Vision general del flujo

El shell se puede explicar como una tuberia de fases:
1. Lectura interactiva (prompt + historial).
2. Tokenizacion (lexing) con comillas y metacaracteres.
3. Parseo (construccion de comandos, redirecciones, pipes).
4. Expansion de variables ($VAR y $?).
5. Preparacion de ejecucion (resolucion de rutas, heredoc).
6. Ejecucion (builtins o execve) con pipes y redirecciones.
7. Gestion de exit status y señales.

Esta separacion permite explicar en defensa cada pieza por separado y justificar
las decisiones tecnicas.

---

## 2. Propuesta de estructuras de datos

Estas estructuras son solo guia. Adapta nombres a tu estilo y Norminette.

### 2.1 Token (lexer)
Representa una unidad del input (palabra, pipe, redireccion, etc.).

- enum e_tokentype
  - TOK_WORD
  - TOK_PIPE
  - TOK_REDIR_IN (<)
  - TOK_REDIR_OUT (>)
  - TOK_REDIR_APPEND (>>)
  - TOK_HEREDOC (<<)

- struct s_token
  - char *text
  - t_tokentype type
  - struct s_token *next

Uso en defensa: el lexer separa el input en unidades, respetando comillas.

### 2.2 Redireccion
Guarda los datos de redireccion por comando.

- enum e_redirtype
  - REDIR_IN
  - REDIR_OUT
  - REDIR_APPEND
  - REDIR_HEREDOC

- struct s_redir
  - t_redirtype type
  - char *target
  - int fd
  - struct s_redir *next

Notas:
- target es el filename o delimitador de heredoc.
- fd se resuelve en fase de preparacion (open o pipe temporal).

### 2.3 Comando

- struct s_command
  - char **argv
  - int argc
  - char *path
  - t_redir *redirs

### 2.4 Pipeline
Una lista de comandos en orden, unidos por pipes.

- struct s_pipeline
  - t_command **cmds
  - size_t count


---

## 3. Lexer: reglas y pasos

Reglas clave del subject:
- No interpretar comillas sin cerrar.
- Comilla simple: no se expanden variables ni metacaracteres.
- Comilla doble: se expanden variables, pero se respetan caracteres normales.
- Metacaracteres: |, <, >, <<, >> separan tokens.

Pasos recomendados:
1. Recorrer la linea caracter a caracter.
2. Mantener estado: in_single, in_double.
3. Cuando no estas en comillas, detectar metacaracteres y cortar tokens.
4. Construir TOK_WORD con el texto exacto (sin eliminar comillas aun).
5. Si llegas a fin de linea con in_single o in_double activo, error de parseo.

Explicacion para defensa:
- El lexer no sabe de ejecucion, solo separa en tokens validos.
- El manejo de comillas se hace aqui para respetar la sintaxis del shell.

---

## 4. Parser: construccion de comandos

Objetivo: transformar tokens en una estructura ejecutable.

Pasos:
1. Recorrer lista de tokens.
2. Cada TOK_PIPE cierra un comando actual y abre el siguiente.
3. TOK_WORD se agrega a argv.
4. TOK_REDIR_* consume el siguiente token (debe ser TOK_WORD) como target.
5. Construir lista de redirecciones para cada comando.
6. Validar errores: pipe inicial/final, redireccion sin target, etc.

Explicacion para defensa:
- El parser aplica reglas de orden y construye una estructura clara.
- Separar argv y redirecciones evita mezclar logica en executor.

---

## 5. Expansion de variables

Reglas:
- $VAR se sustituye por getenv/tabla interna.
- $? se sustituye por el exit_status anterior.
- En comilla simple no se expande.
- En comilla doble si se expande.

Proceso recomendado:
1. Durante tokenizacion, guardar el texto con sus comillas o bien
   marcar segmentos con estado de comillas.
2. En expansion, recorrer cada palabra y reemplazar $...
3. Si variable no existe, reemplazar por string vacio.
4. Eliminar comillas despues de la expansion.

Explicacion para defensa:
- La expansion es una fase separada para no complicar el parser.
- $?, variable especial, refleja el estado de la ultima ejecucion.

---

## 6. Redirecciones y heredoc

Redirecciones basicas:
- <: open(file, O_RDONLY)
- >: open(file, O_WRONLY | O_CREAT | O_TRUNC)
- >>: open(file, O_WRONLY | O_CREAT | O_APPEND)

Heredoc (<<):
1. Leer lineas hasta delimitador exacto.
2. Guardar el contenido en un pipe o fichero temporal.
3. Usar el extremo de lectura como STDIN del comando.
4. No guardar el contenido en historial.

Explicacion para defensa:
- Las redirecciones se resuelven antes de ejecutar el proceso.
- Heredoc es una fuente especial de entrada.

---

## 7. Resolucion de comandos y PATH

Reglas:
- Si argv[0] es una ruta absoluta o relativa (/, ./, ../), usarla tal cual.
- Si no, buscar en PATH separando por ':'.
- Si es builtin, no se necesita path real.

Proceso:
1. Detectar builtin.
2. Si no builtin y no es ruta, recorrer PATH y usar access().
3. Guardar path en t_command->path.

---

## 8. Ejecucion

Caso 1: comando unico builtin
- Ejecutar en el proceso padre para que pueda modificar estado del shell
  (ej: cd, export, unset, exit).

Caso 2: pipeline o comando externo
- Usar fork + execve.
- Crear pipes entre comandos.
- Aplicar redirecciones antes de ejecutar.

Proceso para pipeline:
1. Para cada comando, crear pipe si hay siguiente.
2. fork.
3. En child: dup2 para redirecciones y pipes, luego ejecutar.
4. En parent: cerrar FDs innecesarios y seguir.
5. Esperar procesos, guardar exit status del ultimo comando.

Explicacion para defensa:
- Las pipes conectan stdout del comando i con stdin del comando i+1.
- Los builtins dentro de pipeline se ejecutan en child.

---

## 9. Builtins obligatorios

- echo con -n
- cd (ruta relativa o absoluta)
- pwd
- export (sin opciones)
- unset (sin opciones)
- env (sin opciones o argumentos)
- exit

Notas de defensa:
- export/unset trabajan sobre la tabla de variables del shell.
- env imprime variables de entorno.
- exit debe actualizar exit_status y terminar el loop principal.

---

## 10. Senales

Requisitos interactivos:
- ctrl-C: imprime nueva linea y muestra prompt.
- ctrl-D: termina el shell.
- ctrl-\: no hace nada.

Regla del subject:
- Solo una variable global para indicar la senal recibida.

Proceso:
1. Definir una variable global int g_signal.
2. Configurar handlers con sigaction.
3. En handler: actualizar g_signal y escribir un '\n' si procede.
4. En el loop principal: si g_signal indica SIGINT, resetear lineas de readline.

---

## 11. Manejo de errores y salida

- Mostrar errores con perror o mensajes consistentes.
- Si parseo falla, no ejecutar nada.
- Mantener exit_status actualizado.

Explicacion en defensa:
- Un shell robusto evita ejecutar comandos parcialmente parseados.
- exit_status es clave para $?.

---

## 12. Checklist para defensa (guion rapido)

1. Explico el flujo completo: lectura -> lexer -> parser -> expansion -> exec.
2. Explico como manejo comillas y metacaracteres.
3. Explico como construyo argv y redirecciones.
4. Explico expansion de $VAR y $?.
5. Explico pipes y redirecciones con dup2.
6. Explico por que los builtins se ejecutan en parent o child.
7. Explico manejo de senales y la variable global unica.
8. Explico exit_status y comportamiento de $?.

---

## 13. Sugerencia de estructura de archivos

- include/
  - minishell.h
  - core.h (estructuras globales y estado)
  - parser.h (tokens, parser)
  - executor.h
  - builtins.h

- src/
  - core/ (init, signals, util)
  - parser/ (lexer.c, parser.c, expand.c)
  - executor/ (executor.c, redirs.c)
  - builtins/ (echo, cd, pwd, exit, env, export, unset)
  - variables/ (environment.c)
  - minishell.c (loop principal)
  - main.c

Esto es solo una guia; no es obligatorio seguirla al pie de la letra.

---

## 14. Consejos para la defensa

- Usa bash como referencia de comportamiento.
- Demuestra un par de ejemplos: pipe, redireccion y expansion.
- Si algo falla, explica que el parser previene ejecucion parcial.
- Recalca el manejo correcto de ctrl-C y ctrl-\.