DEV Community: Ilean Monterrubio Jr

Patrones embebidos comunes: búfer circular

Ilean Monterrubio Jr — Fri, 31 Jul 2026 00:00:00 +0000

Esta es la primera parte de una nueva serie donde vuelvo a explorar los patrones embebidos más comunes, empezando por el búfer circular (ring buffer). Es uno de esos patrones que se usan en la comunicación serial para asegurarnos de no perder ni una trama de datos, y además es un bloque de construcción para otros patrones que veremos más adelante.

El código fuente completo y probado vive en el repositorio complementario: ileanmjr88/tetzontli. Cada patrón de esta serie es su propio módulo con una suite completa de pruebas en GoogleTest, así que puedes clonarlo y ejecutar las pruebas tú mismo.

Concepto básico

El búfer circular usa dos índices, head y tail. Para agregar datos hacemos put de un byte en head e incrementamos head en uno. Para quitar datos hacemos get de un byte en tail e incrementamos tail en uno. Ambos índices solo avanzan hacia adelante: tail persigue a head por todo el búfer.

Este patrón se puede implementar con una lista enlazada o con un arreglo (array) de longitud fija. La lista enlazada suena tentadora, pero en un sistema embebido no quieres asignación dinámica de memoria. En una computadora moderna con gigabytes de memoria, llamar a malloc no es problema. En un microcontrolador tienes kilobytes, y tres problemas más grandes: el heap se fragmenta en un dispositivo que funciona durante meses, el tiempo que tarda una asignación no es determinista, y muchas veces necesitas agregar datos desde dentro de una interrupción, donde no te puedes dar el lujo de ninguna de las dos cosas. Un arreglo fijo evita todo eso, porque el espacio queda garantizado en tiempo de compilación.

Ese espacio garantizado es justo lo que le da tiempo al consumidor: los bytes que llegan más rápido de lo que los puedes procesar se quedan seguros en el búfer hasta que llegues a ellos, en lugar de perderse.

Dar la vuelta dentro del arreglo

Un arreglo no da la vuelta. Cuando llegas al final e intentas pasarte, no regresa al inicio. Te sales del espacio asignado, lo que puede provocar un fallo de segmentación, devolverte un puntero NULL o entregarte basura.

La intuición

La forma intuitiva de regresar al inicio es el operador módulo %, que devuelve el residuo de una división.

Array of length/capacity: 10

Formula: index % capacity -> array index

- index 0: 0 % 10 = 0
- index 1: 1 % 10 = 1
- index 4: 4 % 10 = 4
- index 10: 10 % 10 = 0
- index 11: 11 % 10 = 1

El módulo nos deja tratar el arreglo fijo como un anillo, lo que lo hace ideal para un búfer circular. Funciona bien en una computadora moderna con varios núcleos, frecuencias altas y una unidad de división por hardware. Pero el módulo tiene una desventaja: requiere división, y muchos microcontroladores no tienen división por hardware. El compilador la emula por software, que es lento, y pagamos ese costo con cada byte que pasa por el búfer.

Optimizando con una máscara de bits

Hay una forma más rápida de hacer exactamente lo mismo que el operador módulo, con una restricción: la longitud del arreglo debe ser una potencia de dos. Esa restricción es la llave que nos permite recrear el módulo con una sola operación a nivel de bits. La fórmula es index = head & mask, donde mask = capacity - 1. Repasemos las matemáticas.

Array of length/capacity: 8 (power of two)

mask = 8 - 1 = 7 = 0b0111

- index 0: 0b0000 & 0b0111 = 0
- index 1: 0b0001 & 0b0111 = 1
- index 2: 0b0010 & 0b0111 = 2
- index 8: 0b1000 & 0b0111 = 0
- index 10: 0b1010 & 0b0111 = 2
- index 14: 0b1110 & 0b0111 = 6

Fíjate que son las mismas respuestas que daría el módulo: 8 % 8 = 0, 10 % 8 = 2, 14 % 8 = 6. No es coincidencia. La máscara 0b0111 conserva solo los tres bits más bajos y limpia todo lo que está arriba, y los tres bits más bajos de cualquier número son exactamente ese número módulo 8. Quedarte con los bits bajos es sacar el residuo. Como la capacidad es potencia de dos, capacity - 1 es una secuencia limpia de unos, y eso es lo que hace que el AND coincida perfectamente con el módulo. Intenta esto con un número que no sea potencia de dos y se cae todo: 11 & 9 = 9, pero 11 % 10 = 1.

Implementación

La estructura del búfer circular

Creamos un struct para mantener juntos todos los datos. Esto nos facilita la vida, porque con un solo puntero a la estructura podemos acceder a buffer, capacity, mask, head y tail. También hace que los datos sean fáciles de pasar por puntero a cualquier función que necesite agregar o leer de él.

// modules/ring_buffer/ring_buffer.h
typedef struct {
  uint8_t *buffer;
  size_t capacity;
  size_t mask;
  volatile size_t head;
  volatile size_t tail;
} ring_buffer_t;

Como puedes ver, el struct usa varios tipos distintos, y cada uno es deliberado.

uint8_t: el búfer guarda bytes crudos. Sea cual sea la fuente, datos seriales de UART, I2C o cualquier otra cosa, llegan como octetos, así que un arreglo de bytes es el almacenamiento natural para la cola.
size_t: capacity, mask, head y tail son todos size_t. Es un tipo sin signo del tamaño de la plataforma (normalmente un alias de unsigned int o unsigned long), lo que mantiene la aritmética de índices portable entre compiladores y evita problemas de desbordamiento con signo. Que sea sin signo importa más adelante, cuando dependemos de que head - tail dé la vuelta limpiamente.
volatile: head y tail están marcados como volatile para que el compilador siempre los lea de memoria en lugar de guardarse una copia vieja en un registro. El productor y el consumidor pueden ejecutarse en contextos distintos (por ejemplo, una ISR llenando el búfer mientras el bucle principal lo vacía), así que un valor guardado en un registro podría perderse la actualización del otro lado. Ojo: volatile solo garantiza que la lectura ocurra, no hace que el acceso sea atómico ni seguro entre hilos. Veremos por qué este diseño es seguro de todos modos en la sección sobre interrupciones.

Las funciones de inicialización y de potencia de dos

Empecemos con init y su ayudante is_power_of_two. La función init prepara la estructura de datos, y la verificación de potencia de dos es el primer filtro: si quien la llama pide una capacidad que no es potencia de dos, la rechazamos, porque todo el esquema de enmascarado depende de eso. Arranquemos con el ayudante.

// modules/ring_buffer/ring_buffer.c
static bool is_power_of_two(size_t x) {
  return x != 0u && (x & (x - 1u)) == 0u;
}

Esta implementación hace lo siguiente:

x != 0u: verifica que x no sea 0.
(x & (x - 1u)) == 0u: esta es la parte que verifica que haya un solo bit encendido. Una potencia de dos tiene exactamente un bit encendido. Restarle uno apaga ese bit y enciende todos los que están debajo, así que x y x - 1 no comparten ningún bit y el AND da cero. Toma x = 8: 8 - 1 = 7, y 0b1000 & 0b0111 = 0. Ahora toma un número que no sea potencia de dos, x = 12: 12 - 1 = 11, y 0b1100 & 0b1011 = 0b1000, que no es cero. Ese bit que sobra delata que x tenía más de un bit encendido.

Si ambas condiciones se cumplen, entonces x es potencia de dos, así que la función devuelve true si y solo si x es potencia de dos. Ahora pasemos a la función ring_buffer_init.

// modules/ring_buffer/ring_buffer.c
bool ring_buffer_init(ring_buffer_t *rb, uint8_t *storage, size_t capacity) {
  if (rb == NULL || storage == NULL || !is_power_of_two(capacity)) {
    return false;
  }

  rb->buffer = storage;
  rb->capacity = capacity;
  rb->mask = capacity - 1u;
  rb->head = 0u;
  rb->tail = 0u;
  return true;
}

init valida primero sus entradas: un puntero nulo al struct, un storage nulo, o una capacidad que no sea potencia de dos hacen que se salga y devuelva false. Una vez que pasan las verificaciones, arma el struct, precalcula mask = capacity - 1 para que put y get nunca tengan que recalcularlo, y pone ambos índices en cero.

Fíjate que init no asigna nada. Quien la llama nos entrega el arreglo storage, así que el búfer puede vivir en memoria estática o en la pila. Este es el principio de no usar malloc que mencionamos antes, hecho concreto: no hay ni un malloc a la vista, y el espacio quedó garantizado en el momento en que el llamador declaró el arreglo.

Las funciones put y get

Estas funciones ponen y sacan un solo byte a la vez. Las limitamos a un byte porque a veces un solo byte es todo lo que necesitamos, y porque las funciones write y read de la siguiente sección están construidas encima de ellas. Empecemos con ring_buffer_put:

// modules/ring_buffer/ring_buffer.c
bool ring_buffer_put(ring_buffer_t *rb, uint8_t byte) {
  if (rb == NULL || ring_buffer_is_full(rb)) {
    return false;
  }
  rb->buffer[rb->head & rb->mask] = byte;
  rb->head++;
  return true;
}

La función empieza validando que rb no sea NULL, y luego llama al ayudante ring_buffer_is_full. Si el búfer está lleno salimos temprano y devolvemos false, avisándole al llamador que no se guardó ningún byte. Veremos cómo funciona is_full en la siguiente sección. Si hay espacio, hacemos la escritura, y aquí es donde rinde frutos la sección anterior: rb->head & rb->mask calcula el índice del arreglo con el AND a nivel de bits, envolviendo el head de avance libre de regreso a una ranura válida. Escribimos el byte ahí, y luego incrementamos head en uno para que el siguiente put caiga en la ranura que sigue. Fíjate en el orden: primero escribimos la ranura, después avanzamos head. Ese orden importa para la seguridad con interrupciones, y llegaremos a eso más adelante. Ahora veamos ring_buffer_get:

// modules/ring_buffer/ring_buffer.c
bool ring_buffer_get(ring_buffer_t *rb, uint8_t *out) {
  if (rb == NULL || out == NULL || ring_buffer_is_empty(rb)) {
    return false;
  }
  *out = rb->buffer[rb->tail & rb->mask];
  rb->tail++;
  return true;
}

Esta función también empieza validando que rb no sea NULL, y luego verifica que out tampoco lo sea. Ese es el puntero donde se guarda el byte que leemos, que es la forma en que get le devuelve datos al llamador dejando libre su valor de retorno bool para reportar éxito o fracaso. Por último llama al ayudante ring_buffer_is_empty. Si el búfer está vacío salimos temprano y devolvemos false, avisándole al llamador que no se leyó ningún byte. Veremos cómo funciona is_empty en la siguiente sección. Si no está vacío, hacemos la lectura, y otra vez la sección anterior rinde frutos: rb->tail & rb->mask calcula el índice del arreglo con el AND a nivel de bits, envolviendo el tail de avance libre en una ranura válida. Leemos el byte e incrementamos tail en uno. Fíjate que get nunca borra nada. Lee el byte y mueve tail hacia adelante, y esa ranura cuenta como libre en el momento en que tail pasa por encima de ella. Los índices por sí solos deciden qué son datos y qué es espacio libre.

Las funciones is_empty, is_full y count

Estos tres ayudantes, is_empty, is_full y count, son en los que se apoyan put y get para decidir si pueden seguir adelante. Aquí es donde los índices de avance libre por fin se ganan su lugar. Empecemos con ring_buffer_is_empty:

// modules/ring_buffer/ring_buffer.c
bool ring_buffer_is_empty(const ring_buffer_t *rb) {
  return rb->head == rb->tail;
}

El búfer está vacío cuando head y tail tienen el mismo valor. Tiene sentido: tail persigue a head, y cuando lo alcanza por completo ya no queda nada por leer. Aquí está la parte sutil. En muchos diseños de búfer circular los índices se envuelven de regreso al rango válido, y entonces head == tail es ambiguo, porque significa tanto completamente vacío como completamente lleno, y no puedes distinguir cuál. Como nuestros índices avanzan libres y nunca se envuelven, head == tail solo puede significar vacío. En un momento veremos cómo se maneja el caso lleno sin esa ambigüedad.

Sigue ring_buffer_count, que es el corazón de todo esto:

// modules/ring_buffer/ring_buffer.c
size_t ring_buffer_count(const ring_buffer_t *rb) {
  return rb->head - rb->tail;
}

Ambos índices solo aumentan. Cada put incrementa head, cada get incrementa tail, y ninguno se envuelve. Así que head siempre va adelante de tail por exactamente la cantidad de bytes que se han escrito pero todavía no se han leído, que es el nivel de llenado. La diferencia head - tail es la cuenta.

Lo bonito es lo que pasa cuando head finalmente se desborda. size_t tiene un máximo, y después de suficientes bytes head lo rebasa y da la vuelta hacia cero. Podrías esperar que head - tail se rompa en ese punto, pero no pasa. La resta sin signo da la vuelta igual que la suma sin signo, así que la diferencia sigue siendo correcta incluso a través del desbordamiento. Justo por esto head y tail son sin signo, y por esto el búfer puede funcionar indefinidamente sin ningún manejo especial para el desbordamiento.

Por último, ring_buffer_is_full:

// modules/ring_buffer/ring_buffer.c
bool ring_buffer_is_full(const ring_buffer_t *rb) {
  return ring_buffer_count(rb) == rb->capacity;
}

Una vez que tenemos count, lo de lleno es trivial: el búfer está lleno cuando contiene capacity bytes. Sin desperdiciar una ranura, sin un contador aparte que mantener sincronizado, sin ambigüedad con el caso vacío. Los índices de avance libre nos dan vacío (head == tail), lleno (count == capacity) y todo lo que hay en medio, todo a partir de dos números que solo cuentan hacia arriba.

Las funciones write y read

Estas funciones escriben y leen más de un byte a la vez. Empecemos con ring_buffer_write:

// modules/ring_buffer/ring_buffer.c
size_t ring_buffer_write(ring_buffer_t *rb, const uint8_t *data, size_t len) {
  if (rb == NULL || data == NULL) {
    return 0u;
  }
  size_t written = 0u;
  while (written < len && ring_buffer_put(rb, data[written])) {
    written++;
  }
  return written;
}

Esta función devuelve la cantidad de bytes que realmente se escribieron, que puede ser menor a la que se pidió. Devuelve 0 en la salida temprana, cuando el búfer circular rb o el puntero de origen data son NULL. Si no, inicializamos written para llevar la cuenta de cuántos bytes hemos copiado de data al búfer. El ciclo se ejecuta con dos condiciones unidas por &&: written < len nos impide leer más allá del final de la entrada, y ring_buffer_put devuelve false en cuanto el búfer se llena. Mientras ambas se cumplan, seguimos copiando bytes e incrementando written. El ciclo se detiene en cuanto una de las dos falla, ya sea porque se nos acabó la entrada o porque se nos acabó el espacio. La cuenta que devolvemos le dice al llamador exactamente cuánto entró: todo, una parte, o cero si el búfer ya estaba lleno.

Sigue ring_buffer_read:

// modules/ring_buffer/ring_buffer.c
size_t ring_buffer_read(ring_buffer_t *rb, uint8_t *out, size_t len) {
  if (rb == NULL || out == NULL) {
    return 0u;
  }
  size_t count = 0u;
  while (count < len && ring_buffer_get(rb, &out[count])) {
    count++;
  }
  return count;
}

Esta función también devuelve la cantidad de bytes que realmente se leyeron, que puede ser menor a la que se pidió. Devuelve 0 en la salida temprana, cuando el búfer circular rb o el puntero de destino out son NULL. Si no, inicializamos count para llevar la cuenta de cuántos bytes hemos leído del búfer hacia out. El ciclo se ejecuta con dos condiciones unidas por &&: count < len nos impide escribir más allá del final de la salida, y ring_buffer_get devuelve false en cuanto el búfer se vacía. Mientras ambas se cumplan, seguimos leyendo bytes e incrementando count. El ciclo se detiene en cuanto una de las dos falla, ya sea porque el búfer del llamador se llenó o porque el búfer circular se quedó seco. La cuenta que devolvemos le dice al llamador exactamente cuántos bytes recibió.

Seguridad con la rutina de servicio de interrupción (ISR)

Para quienes van empezando en embebidos, puede que no sea obvio por qué se considera seguro este diseño, ni cuáles son sus aplicaciones típicas. El uso principal de un búfer circular, como mencionamos antes, es la comunicación serial. Toma el ejemplo de dos microcontroladores hablando entre sí, cada uno ejecutando su propio firmware hecho a la medida de su tarea. No sabemos cuándo va a necesitar enviar datos ninguno de los dos, así que para asegurarnos de no perder un solo byte, montamos la ruta de recepción de datos (RX) usando la rutina de servicio de interrupción (Interrupt Service Routine, ISR) del microcontrolador. En cuanto llega el inicio de una transmisión, la ISR toma el control y captura cada byte.

Este es el lado productor del búfer. La ISR llama a put por cada byte que recibe. En otro lado, el bucle principal es el consumidor, llamando a get cuando tiene chance de procesar lo que llegó. Los dos se ejecutan en contextos distintos, y aquí está el detalle: la ISR puede dispararse en cualquier momento, entre cualesquiera dos instrucciones que esté ejecutando el bucle principal. Así que la pregunta justa es: si la interrupción cae a la mitad de un get, ¿pueden pisarse entre sí y corromper el búfer?

La respuesta es no, y la razón es que cada índice tiene exactamente un escritor. put es la única función que escribe head, y solo se ejecuta en la ISR. get es la única función que escribe tail, y solo se ejecuta en el bucle principal. Ninguno de los dos lados escribe el índice del otro. El productor lee tail para saber si el búfer está lleno, y el consumidor lee head para saber si está vacío, pero leer es seguro. Como ningún índice tiene dos escritores compitiendo por cambiarlo, no hay nada que corromper, y no necesitamos deshabilitar interrupciones ni recurrir a un candado. A esto se refiere la gente cuando habla de un solo productor y un solo consumidor, o SPSC por sus siglas en inglés.

Esa regla de un solo escritor también es el límite. En el momento en que tengas dos cosas llamando a put, o dos cosas llamando a get, la garantía se acaba y necesitas sincronización de verdad. Este búfer es seguro para exactamente un productor y un consumidor, ni uno más.

Hay un detalle más que lo hace funcionar, y es el orden que señalamos allá en put:

rb->buffer[rb->head & rb->mask] = byte; // 1. write the data
rb->head++; // 2. then publish it

Primero escribimos el byte en la ranura, y después incrementamos head. Ese orden no es accidente. head es la señal que le dice al consumidor que hay un byte nuevo disponible. Si incrementáramos head primero y el tiempo de la interrupción se acomodara mal, el consumidor podría ver el nuevo head, ir a leer esa ranura y sacar un byte que en realidad todavía no habíamos escrito. Al escribir la ranura antes de avanzar head, garantizamos que en el instante en que el consumidor puede ver el byte, el byte de verdad ya está ahí. La actualización del índice publica los datos, así que va al final. get hace el espejo: primero leemos el byte y después avanzamos tail, así nunca marcamos una ranura como libre antes de habernos llevado su contenido.

Un par de advertencias honestas para quien las quiera. Primero, volatile nos da visibilidad, no atomicidad. Este diseño asume que leer o escribir head y tail sucede en una sola operación de máquina ininterrumpible, lo cual es cierto cuando son del tamaño de palabra en el objetivo. En un MCU de 8 bits, donde size_t abarca varios bytes, la actualización de un índice podría partirse en varias instrucciones y quedar rota por una interrupción, y tendrías que tomarlo en cuenta. Segundo, en un microcontrolador de un solo núcleo con una ISR, volatile más el orden de escribir y luego publicar es suficiente. En un sistema multinúcleo con ordenamiento de memoria débil recurrirías a operaciones atómicas con semántica explícita de adquisición y liberación, para garantizar que la escritura de la ranura se vea antes que la del índice. Para el caso clásico de ISR y bucle principal, que es para el que está hecho este búfer, estamos en terreno firme.

Cierre

Eso es un búfer circular completo y funcional en un par de cientos de líneas de C. No hace asignación dinámica, da la vuelta con un solo AND a nivel de bits en lugar de una división, distingue lleno de vacío sin desperdiciar una ranura ni llevar un contador aparte, y es seguro llenarlo desde una interrupción mientras lo vaciamos desde el bucle principal. Para una estructura tan pequeña, trae metida una cantidad sorprendente de sutilezas.

Vale la pena ser honesto sobre lo que este diseño no hace, porque cada una de estas cosas es un intercambio deliberado, no un descuido:

La capacidad debe ser potencia de dos. Este es el precio de cambiar el módulo por una máscara. Si necesitas guardar exactamente 100 bytes, redondeas a 128 y desperdicias un poco de espacio. En un sistema embebido casi siempre es un intercambio que conviene.
Solo un productor y un consumidor. Un escritor por índice es lo que lo hace libre de candados. Dos ISR escribiendo, o dos contextos leyendo, y necesitas sincronización de verdad.
No hay modo de sobrescribir lo más viejo. Cuando el búfer está lleno, put rechaza el byte nuevo en lugar de descartar el más viejo. Algunas aplicaciones quieren lo contrario, conservar las muestras más recientes y tirar las viejas. Esa es una variante razonable, solo que no es esta.
Solo bytes. Este búfer guarda uint8_t. Guardar elementos más anchos, o structs arbitrarios, implica generalizar el tamaño del elemento, lo que cambia la aritmética de índices y el almacenamiento.

Ninguna de estas limitaciones es difícil de levantar. Son las preguntas que salen naturalmente, y varias de ellas se convierten en sus propios patrones más adelante en esta serie.

Y hablando de eso, el búfer circular es un cimiento, no un destino. Aparece por debajo de varios de los patrones que faltan: una cola de eventos es un búfer circular de mensajes en lugar de bytes, un filtro de promedio móvil es un búfer circular de muestras, y el despachador de comandos que construiremos lee su entrada directamente de uno. Lo que sigue en la serie es el pool de memoria. El búfer circular nos dio almacenamiento fijo para bytes; el pool de memoria nos da almacenamiento fijo para objetos, y es lo que permite que una cola de eventos guarde structs en lugar de datos crudos. Nos vemos ahí.

Common Embedded Patterns: Ring Buffer

Ilean Monterrubio Jr — Fri, 31 Jul 2026 00:00:00 +0000

This is the first part of a new series where I'll re-explore common embedded patterns, starting with the ring buffer. It's one of those patterns used in serial communication to make sure no frame of data is lost, and it's also a building block for other patterns we'll cover later.

The complete, tested source lives in the companion repo: ileanmjr88/tetzontli. Each pattern in this series is its own module with a full GoogleTest suite, so you can clone it and run the tests yourself.

Basic Concept

The ring buffer uses two indices, head and tail. To add data we put a byte at head and increment head by one. To remove data we get a byte from tail and increment tail by one. Both indices only move forward, the tail chases the head around the buffer.

This pattern can be implemented with a linked list or a fixed-length array. A linked list might be tempting, but on an embedded system you don't want dynamic allocation. On a modern computer with gigabytes of memory, calling malloc is a non-issue. On a microcontroller you have kilobytes, and three bigger problems: the heap fragments over a device that runs for months, allocation timing is non-deterministic, and you often need to add data from inside an interrupt where you can't afford either. A fixed array sidesteps all of it, the space is guaranteed at compile time.

That guaranteed space is what buys the consumer time: bytes arriving faster than you can process them sit safely in the buffer until you get to them, instead of being lost.

Wrapping around the array

An array does not loop. When you reach the end and try to go past it, it doesn't wrap around. You run beyond the allocated space, which can cause a segmentation fault, return a NULL pointer, or hand you garbage data.

Intuition

The intuitive way to loop back around is the modulo operator %, which returns the remainder after division.

Array of length/capacity: 10

Formula: index % capacity -> array index

- index 0: 0 % 10 = 0
- index 1: 1 % 10 = 1
- index 4: 4 % 10 = 4
- index 10: 10 % 10 = 0
- index 11: 11 % 10 = 1

Modulo lets us treat the fixed array as a ring, which makes it a great fit for a ring buffer. It works fine on a modern computer with multiple cores, high clock speeds, and a hardware divide unit. But modulo has a drawback. It requires division, and many microcontrollers have no hardware divide. The compiler emulates it in software, which is slow, and we pay that cost on every byte we move through the buffer.

Optimizing with a bitmask

There's a faster way to do exactly what the modulo operator does, with one restriction: the array length must be a power of two. That restriction is the key that lets us recreate modulo with a single bitwise operation. The formula is index = head & mask, where mask = capacity - 1. Let's walk through the math.

Array of length/capacity: 8 (power of two)

mask = 8 - 1 = 7 = 0b0111

- index 0: 0b0000 & 0b0111 = 0
- index 1: 0b0001 & 0b0111 = 1
- index 2: 0b0010 & 0b0111 = 2
- index 8: 0b1000 & 0b0111 = 0
- index 10: 0b1010 & 0b0111 = 2
- index 14: 0b1110 & 0b0111 = 6

Notice these are the same answers modulo would give: 8 % 8 = 0, 10 % 8 = 2, 14 % 8 = 6. That's not a coincidence. The mask 0b0111 keeps only the lowest three bits and clears everything above, and the lowest three bits of any number are exactly that number modulo 8. Keeping the low bits is taking the remainder. Because the capacity is a power of two, capacity - 1 is a clean run of ones, which is what makes the AND line up perfectly with modulo. Try this with a non power of two and it falls apart: 11 & 9 = 9, but 11 % 10 = 1.

Implementation

Ring buffer structure

We create a struct to keep all the data types together. This makes life easy, because with a single pointer to the data structure we can access: buffer, capacity, mask, head, and tail. It also makes the data easy to pass by pointer for any function that needs to add and read from it.

// modules/ring_buffer/ring_buffer.h
typedef struct {
  uint8_t *buffer;
  size_t capacity;
  size_t mask;
  volatile size_t head;
  volatile size_t tail;
} ring_buffer_t;

As you can see the struct uses a few different types, and each one is deliberate.

uint8_t: the buffer stores raw bytes. Whatever the source is, serial data from UART, I2C, or anything else, it arrives as octets, so a byte array is the natural storage for the queue.
size_t: capacity, mask, head, and tail are all size_t. It's an unsigned type sized to the platform (usually an alias for unsigned int or unsigned long), which keeps the index math portable across compilers and avoids signed-overflow issues. The unsignedness matters later, when we rely on head - tail wrapping cleanly.
volatile: head and tail are marked volatile so the compiler always reads them from memory instead of caching a stale copy in a register. The producer and consumer can run in different execution contexts (for example, an ISR filling the buffer while the main loop drains it), so a value cached in a register could miss the other side's update. Note that volatile only guarantees the read happens, it does not make the access atomic or thread-safe. We'll cover why this design is safe anyway in the section on interrupts.

Initialization and power of two functions

Let's start with init and its helper is_power_of_two. The init function sets up the data structure, and the power-of-two check is the first gate: if the caller asks for a capacity that isn't a power of two, we refuse, because the whole masking scheme depends on it. We'll start with the helper.

// modules/ring_buffer/ring_buffer.c
static bool is_power_of_two(size_t x) {
  return x != 0u && (x & (x - 1u)) == 0u;
}

This implementation does the following:

x != 0u: checks if x is not 0.
(x & (x - 1u)) == 0u: this is the part that checks for a single set bit. A power of two has exactly one bit set. Subtracting one flips that bit off and turns every bit below it on, so x and x - 1 share no bits and the AND comes out zero. Take x = 8: 8 - 1 = 7, and 0b1000 & 0b0111 = 0. Now take a number that isn't a power of two, x = 12: 12 - 1 = 11, and 0b1100 & 0b1011 = 0b1000, which is not zero. The leftover bit is the tell that x had more than one bit set. If both conditions are true then x is a power of two, so the function returns true if and only if x is a power of two. Now let's turn to the ring_buffer_init function.

// modules/ring_buffer/ring_buffer.c
bool ring_buffer_init(ring_buffer_t *rb, uint8_t *storage, size_t capacity) {
  if (rb == NULL || storage == NULL || !is_power_of_two(capacity)) {
    return false;
  }

  rb->buffer = storage;
  rb->capacity = capacity;
  rb->mask = capacity - 1u;
  rb->head = 0u;
  rb->tail = 0u;
  return true;
}

init validates its inputs first: a null struct pointer, null storage, or a capacity that isn't a power of two all cause it to bail out and return false. Once the checks pass, it wires up the struct, precomputes mask = capacity - 1 so put and get never have to recompute it, and zeroes both indices.

Notice init doesn't allocate anything. The caller hands us the storage array, so the buffer can live in static or stack memory. This is the no-malloc principle from earlier, made concrete: there's no malloc in sight, and the space was guaranteed the moment the caller declared the array.

Put and get functions

These functions put and get a single byte at a time. We scope them to one byte because sometimes a single byte is all we need, and because the next section's write and read functions are built on top of them. Let's start with ring_buffer_put:

// modules/ring_buffer/ring_buffer.c
bool ring_buffer_put(ring_buffer_t *rb, uint8_t byte) {
  if (rb == NULL || ring_buffer_is_full(rb)) {
    return false;
  }
  rb->buffer[rb->head & rb->mask] = byte;
  rb->head++;
  return true;
}

The function starts by validating that rb isn't NULL, then calls the helper ring_buffer_is_full. If the buffer is full we exit early and return false, telling the caller no byte was stored. We'll see how is_full works in the next section. If there's room, we do the actual write, and this is where the previous section pays off: rb->head & rb->mask computes the array index using the bitwise AND, wrapping the free-running head back into a valid slot. We write the byte there, then increment head by one so the next put lands in the following slot. Notice the order: we write the slot first, then advance head. That ordering matters for interrupt safety, which we'll get to later. Now let's take a look at ring_buffer_get:

// modules/ring_buffer/ring_buffer.c
bool ring_buffer_get(ring_buffer_t *rb, uint8_t *out) {
  if (rb == NULL || out == NULL || ring_buffer_is_empty(rb)) {
    return false;
  }
  *out = rb->buffer[rb->tail & rb->mask];
  rb->tail++;
  return true;
}

The function also starts by validating that rb isn't NULL, then checks that out isn't NULL. This is the pointer where the byte we read gets stored, which is how get hands data back to the caller while keeping its bool return free to report success or failure. Finally it calls the helper ring_buffer_is_empty. If the buffer is empty we exit early and return false, telling the caller no byte was read. We'll see how is_empty works in the next section. If it's not empty, we do the read, and again the previous section pays off: rb->tail & rb->mask computes the array index with the bitwise AND, wrapping the free-running tail into a valid slot. We read the byte, then increment tail by one. Notice get never erases anything. It reads the byte and moves tail forward, and that slot counts as free again the moment tail passes it. The indices alone decide what's data and what's free space.

Is empty, is full, and count

These three helpers, is_empty, is_full, and count, are what put and get lean on to decide whether they can proceed. This is where the free-running indices finally earn their keep. Let's start with ring_buffer_is_empty:

// modules/ring_buffer/ring_buffer.c
bool ring_buffer_is_empty(const ring_buffer_t *rb) {
  return rb->head == rb->tail;
}

The buffer is empty when head and tail hold the same value. That makes sense: tail chases head, and when it catches all the way up there's nothing left to read. Here's the subtle part. In a lot of ring buffer designs the indices get wrapped back into range, and then head == tail is ambiguous, it means both completely empty and completely full, and you can't tell which. Because our indices run free and never wrap, head == tail can only ever mean empty. We'll see in a moment how full is handled without that ambiguity.

Next, ring_buffer_count, which is the heart of it:

// modules/ring_buffer/ring_buffer.c
size_t ring_buffer_count(const ring_buffer_t *rb) {
  return rb->head - rb->tail;
}

Both indices only ever increase. Every put bumps head, every get bumps tail, and neither wraps. So head is always ahead of tail by exactly the number of bytes that have been written but not yet read, which is the fill level. The difference head - tail is the count.

The nice part is what happens when head eventually overflows. size_t has a maximum, and after enough bytes head wraps past it back toward zero. You might expect head - tail to break at that point, but it doesn't. Unsigned subtraction wraps the same way unsigned addition does, so the difference stays correct even across the overflow. This is exactly why head and tail are unsigned, and it's why the buffer can run indefinitely without any special handling for the wraparound.

Finally, ring_buffer_is_full:

// modules/ring_buffer/ring_buffer.c
bool ring_buffer_is_full(const ring_buffer_t *rb) {
  return ring_buffer_count(rb) == rb->capacity;
}

Once we have count, full is trivial: the buffer is full when it holds capacity bytes. No wasted slot, no separate counter to keep in sync, no ambiguity with the empty case. The free-running indices give us empty (head == tail), full (count == capacity), and everything in between, all from two numbers that only count upward.

Write and read functions

These functions write and read more than a single byte of data at a time. Let's start with ring_buffer_write:

// modules/ring_buffer/ring_buffer.c
size_t ring_buffer_write(ring_buffer_t *rb, const uint8_t *data, size_t len) {
  if (rb == NULL || data == NULL) {
    return 0u;
  }
  size_t written = 0u;
  while (written < len && ring_buffer_put(rb, data[written])) {
    written++;
  }
  return written;
}

This function returns the number of bytes actually written, which may be fewer than requested. It returns 0 on the early exit when either the ring buffer rb or the source pointer data is NULL. Otherwise we initialize written to track how many bytes we've copied from data into the buffer. The loop runs on two conditions joined by &&: written < len keeps us from reading past the end of the input, and ring_buffer_put returns false the moment the buffer is full. As long as both hold, we keep copying bytes and incrementing written. The loop stops as soon as either one fails, whether we ran out of input or ran out of room. The count we return tells the caller exactly how much made it in: all of it, part of it, or zero if the buffer was already full.

Next, ring_buffer_read:

// modules/ring_buffer/ring_buffer.c
size_t ring_buffer_read(ring_buffer_t *rb, uint8_t *out, size_t len) {
  if (rb == NULL || out == NULL) {
    return 0u;
  }
  size_t count = 0u;
  while (count < len && ring_buffer_get(rb, &out[count])) {
    count++;
  }
  return count;
}

This function also returns the number of bytes actually read, which may be fewer than requested. It returns 0 on the early exit when either the ring buffer rb or the destination pointer out is NULL. Otherwise we initialize count to track how many bytes we've read from the buffer into out. The loop runs on two conditions joined by &&: count < len keeps us from writing past the end of the output, and ring_buffer_get returns false the moment the buffer is empty. As long as both hold, we keep reading bytes and incrementing count. The loop stops as soon as either one fails, whether the caller's buffer is full or the ring buffer ran dry. The count we return tells the caller exactly how many bytes they got.

Safety with the Interrupt Service Routine (ISR)

For those new to embedded, it might not be obvious why this design is considered safe, or what its typical applications are. The primary use for a ring buffer, as we mentioned earlier, is serial communication. Take the example of two microcontrollers talking to each other, each running its own firmware tailored to its own task. We don't know when either one will need to send data, so to make sure we don't miss a single byte, we set up the data receive (RX) path using the microcontroller's Interrupt Service Routine (ISR). As soon as the start of a transmission arrives, the ISR takes over and captures each byte.

This is the producer side of the buffer. The ISR calls put for every byte it receives. Somewhere else, the main loop is the consumer, calling get when it gets around to processing what came in. The two run in different execution contexts, and here's the catch: the ISR can fire at any moment, between any two instructions the main loop is running. So the fair question is, if the interrupt lands in the middle of a get, can the two step on each other and corrupt the buffer?

The answer is no, and the reason is that each index has exactly one writer. put is the only function that writes head, and it only ever runs in the ISR. get is the only function that writes tail, and it only ever runs in the main loop. Neither side writes the other's index. The producer reads tail to check whether the buffer is full, and the consumer reads head to check whether it's empty, but reading is safe. Since no index has two writers racing to change it, there's nothing to corrupt, and we don't need to disable interrupts or reach for a lock. This is what people mean by single-producer, single-consumer, or SPSC.

That single-writer rule is also the boundary. The moment you have two things calling put, or two things calling get, the guarantee is gone and you need real synchronization. This buffer is safe for exactly one producer and one consumer, no more.

One more detail makes it work, and it's the ordering we flagged back in put:

rb->buffer[rb->head & rb->mask] = byte; // 1. write the data
rb->head++; // 2. then publish it

We write the byte into the slot first, then increment head. That order is not an accident. head is the signal that tells the consumer a new byte is available. If we bumped head first and the interrupt timing worked out badly, the consumer could see the new head, go read that slot, and pull out a byte we hadn't actually written yet. By writing the slot before advancing head, we guarantee that the instant the consumer can see the byte, the byte is really there. The index update publishes the data, so it comes last. get mirrors this: we read the byte out first, then advance tail, so we never mark a slot free before we've taken its contents.

A couple of honest caveats for the readers who want them. First, volatile gets us visibility, not atomicity. This design assumes reading or writing head and tail happens in a single, uninterruptible machine operation, which is true when they're word-sized on the target. On an 8-bit MCU where size_t spans multiple bytes, an index update could be split across instructions and torn by an interrupt, and you'd need to account for that. Second, on a single-core microcontroller with an ISR, volatile plus the write-then-publish ordering is enough. On a multi-core system with weak memory ordering you'd reach for atomics with explicit acquire and release semantics to guarantee the slot write is seen before the index write. For the classic ISR-and-main-loop case this buffer is built for, we're on solid ground.

Wrap-up

That's a complete, working ring buffer in a couple hundred lines of C. It does no dynamic allocation, wraps with a single bitwise AND instead of a division, tells full from empty without wasting a slot or keeping a separate counter, and it's safe to fill from an interrupt while draining it from the main loop. For a structure this small, there's a surprising amount of nuance packed in.

It's worth being honest about what this design does not do, because every one of these is a deliberate trade, not an oversight:

Capacity must be a power of two. This is the price of replacing modulo with a mask. If you need to hold exactly 100 bytes you round up to 128 and waste a little space. On an embedded system that's almost always a trade worth making.
Single producer, single consumer only. One writer per index is what makes it lock-free. Two ISRs writing, or two contexts reading, and you need real synchronization.
No overwrite-oldest mode. When the buffer is full, put refuses the new byte rather than discarding the oldest one. Some applications want the opposite (keep the newest samples, drop the stale ones). That's a reasonable variant, just not this one.
Bytes only. This buffer stores uint8_t. Storing wider elements, or arbitrary structs, means generalizing the element size, which changes the index math and the storage. None of these are hard to lift. They're the natural next questions, and a few of them turn into their own patterns later in this series.

Speaking of which, the ring buffer is a foundation, not a destination. It shows up underneath several of the patterns still to come: an event queue is a ring buffer of messages instead of bytes, a moving-average filter is a ring buffer of samples, and the command dispatcher we'll build reads its input straight out of one. Next in the series we'll tackle the memory pool. The ring buffer gave us fixed storage for bytes; the memory pool gives us fixed storage for objects, and it's what lets an event queue hold structs instead of raw data. See you there.

Compendium: Reproducible Developer Environments in One Config

Ilean Monterrubio Jr — Mon, 18 May 2026 00:00:00 +0000

Why I Built It

Earlier this year I kept coming back to a project that had been on the back burner for a while. The original idea was an IDE with a built-in way to configure development environments, but the more I researched, the clearer it got that I was looking at a multi-year build. Not wanting to wait that long to ship something useful, I narrowed in on the feature I cared about most: the ability to configure and set up a development environment easily, without the IDE wrapped around it.

Throughout my career, setting up toolchains and development environments has always been a painful experience: embedded cross-compilers that only build cleanly on the maintainer's exact OS version, READMEs that promise five minutes and take three days. I've also spent weeks building containers to wall off the development environment, only to watch the image balloon every time another tool got added. The documentation goes stale almost as fast as it gets written, because the tools moved on and nobody updated it.

Why C and C++ First

For Compendium's first iteration I wanted to focus on the language where the setup pain runs deepest: C and C++. Every scripting language already has a version manager that works well enough. nvm handles Node, pyenv handles Python, asdf and mise cover most of the rest. None of them seriously handle GCC, clang, or arm-none-eabi-gcc. Embedded toolchains in particular are where I lose the most time, between USB drivers, OpenOCD configs, and compiler versions that have to match the linker script the project was tested against. Starting there meant solving the hardest case first. Adding Go, Python, and Node on top of that architecture turned out to be the easy part.

v0.1.1 Ships Today

v0.1.1 ships today. The CLI is a single Go binary, the config is a single TOML file, and everything installs under ~/.local/compendium/ without sudo. Rather than recap the docs here, I'll point you at them: compendium.ilean.me has the quick start, the full tool list, the config reference, and per-language guides for C/C++, Go, Python, Node, and embedded.

Tech Stack

CLI : Go (single static binary, no runtime dependencies)
Configuration : TOML
Registry : JSON manifests, hosted on GitHub
Platforms : macOS (Apple Silicon, Intel), Linux (x86_64, arm64)
License : GPL v3 (CLI), CC0 (registry)

Roadmap

v0.2 broadens C/C++ build system support to Autotools, adds Java and Rust, completes the embedded cross-compiler set with Xtensa for ESP32, and wires up the custom git hook runner. v0.3 introduces a Compendium-native C/C++ package manager. The full roadmap lives in the docs. If you want to follow along, contribute, or request a tool for the registry, GitHub issues and discussions are open.

Project Links

Compendium: entornos de desarrollo reproducibles en una sola configuración

Ilean Monterrubio Jr — Mon, 18 May 2026 00:00:00 +0000

Por qué lo construí

A principios de este año seguía volviendo a un proyecto que llevaba un buen rato en pausa. La idea original era un IDE con una forma integrada de configurar entornos de desarrollo, pero entre más investigaba, más claro me quedaba que estaba frente a un desarrollo de varios años. Como no quería esperar tanto para lanzar algo útil, me enfoqué en la funcionalidad que más me importaba: poder configurar y preparar un entorno de desarrollo con facilidad, sin el IDE alrededor.

A lo largo de mi carrera, configurar toolchains y entornos de desarrollo siempre ha sido una experiencia dolorosa: compiladores cruzados de embebidos que solo compilan limpiamente en la versión exacta del sistema operativo del mantenedor, READMEs que prometen cinco minutos y toman tres días. También he pasado semanas construyendo contenedores para aislar el entorno de desarrollo, solo para ver cómo la imagen se inflaba cada vez que se agregaba otra herramienta. La documentación queda obsoleta casi tan rápido como se escribe, porque las herramientas avanzaron y nadie la actualizó.

Por qué primero C y C++

Para la primera iteración de Compendium quise enfocarme en el lenguaje donde el dolor de la configuración es más profundo: C y C++. Todos los lenguajes de scripting ya tienen un gestor de versiones que funciona lo suficientemente bien. nvm maneja Node, pyenv maneja Python, asdf y mise cubren casi todo lo demás. Ninguno de ellos maneja en serio GCC, clang o arm-none-eabi-gcc. Los toolchains de embebidos en particular son donde más tiempo pierdo, entre drivers USB, configuraciones de OpenOCD y versiones de compilador que tienen que coincidir con el linker script contra el que se probó el proyecto. Empezar ahí significaba resolver primero el caso más difícil. Agregar Go, Python y Node sobre esa arquitectura resultó ser la parte fácil.

La v0.1.1 se lanza hoy

La v0.1.1 se lanza hoy. La CLI es un único binario de Go, la configuración es un único archivo TOML y todo se instala en ~/.local/compendium/ sin sudo. En lugar de repetir la documentación aquí, te dirijo a ella: compendium.ilean.me tiene la guía de inicio rápido, la lista completa de herramientas, la referencia de configuración y guías por lenguaje para C/C++, Go, Python, Node y embebidos.

Stack tecnológico

CLI : Go (un único binario estático, sin dependencias en tiempo de ejecución)
Configuración : TOML
Registro : manifiestos JSON, alojados en GitHub
Plataformas : macOS (Apple Silicon, Intel), Linux (x86_64, arm64)
Licencia : GPL v3 (CLI), CC0 (registro)

Hoja de ruta

La v0.2 amplía el soporte de sistemas de build de C/C++ a Autotools, agrega Java y Rust, completa el conjunto de compiladores cruzados para embebidos con Xtensa para el ESP32 y conecta el ejecutor de git hooks personalizados. La v0.3 introduce un gestor de paquetes de C/C++ nativo de Compendium. La hoja de ruta completa vive en la documentación. Si quieres seguir el avance, contribuir o solicitar una herramienta para el registro, los issues y las discusiones de GitHub están abiertos.

Enlaces del proyecto

How I Built a Low-Friction Blog Pipeline

Ilean Monterrubio Jr — Mon, 27 Apr 2026 00:00:00 +0000

Why Build a Pipeline?

I wanted to grow my online presence, a dedicated corner of the internet to showcase my projects and skills, point people to my GitHub, LinkedIn, and socials, and share my thoughts on things I was building or learning. Simple enough goal. The execution, though, turned out to be a learning process.

My first attempt at blogging was manual and messy. Write a post, publish it somewhere, copy it somewhere else, and hope people find it. I had set up the Dev.to RSS feed fetching early on, but that was about it. There was no real visibility into whether anyone was reading, and no reason to keep going. Unsurprisingly, I took a year-long gap between posts, not because I stopped having things to say, but because the friction was too high and life got in the way. When I started a new job, I focused on learning my new responsibilities and let the blog quietly go dormant.

When I came back to it, I wanted to do things differently. The goal was simple: write once, publish everywhere, no copy-pasting across platforms, no manual distribution, and some way to know if the work was actually reaching anyone. The RSS feed was already there but the imports were messy. The frontmatter in my blog posts didn't match the RSS schema, so every import came in inconsistent and making changes or adding new frontmatter fields meant manually fixing every post. What I did this time was get my Astro frontmatter to match the RSS schema properly, so imports were clean and uniform from the start. Now it was about connecting the remaining pieces into a proper pipeline.

The Stack

Astro Before launching my personal site, I had tried to build it with Next.js a year earlier. I didn't fully understand it at the time and kept running into hydration issues. At a local Code and Coffee meetup, I asked one of the attendees for advice and he pointed me to Astro. Within days of going through a tutorial, I had my site live for the first time. I paired it with Tailwind CSS to make theming easy to maintain and update down the road.

Pexels Every post needs a cover image. Pexels is my go-to for finding images, royalty-free stock photos and videos shared by creators. High quality, free to use, and no licensing headaches.

Dev.to This came much later in the process. After some digging I discovered that Astro can generate an rss.xml feed if set up correctly, and Dev.to can periodically pull from that feed to automatically import new posts. All I need to do is keep my frontmatter in sync with what Dev.to expects from the feed, no manual copying.

Umami I wanted visibility into who was actually reading. After some research I landed on Umami: privacy-friendly, no cookie banners, and a free hobby tier that covers up to 3 websites.

Mastodon After Twitter was acquired I decided to leave and delete my profile. Mastodon turned out to be a great fit, especially for the tech community, and the fediverse has a different energy that I appreciate.

LinkedIn Where I manually share each post to take advantage of how LinkedIn's algorithm circulates content to your network and extended network for a few days after publishing.

Setting Up Astro

Each blog post is written in Markdown format, which Astro handles exceptionally well out of the box. One of the keys to making everything work smoothly is Astro's content collections configuration, this is how you tell Astro the shape of your content so it can validate and query it consistently. For this project I have Markdown files for blog entries and JSON files to define my projects. The Astro content collections documentation is worth reading carefully to understand how to define your schema.

Before looking at the frontmatter, it helps to see the schema that enforces it. This lives in src/content.config.ts and uses Astro's content collections with Zod validation. If a frontmatter field is missing or the wrong type, Astro will throw an error at build time rather than silently generating a broken RSS feed:

import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.date(),
    author: z.string(),
    image: z.string(),
    categories: z.array(z.string()),
  }),
});

export const collections = { blog };

Each blog post starts with a frontmatter block that drives everything downstream, from the RSS feed to Dev.to imports:

---
title: "Building a Terminal Text Editor: The View (Part 3)"
description: "In Part 3 of building wordNebula, I cover the View layer, why I chose FTXUI over ncurses..."
pubDate: 2026-04-05
author: "Ilean Monterrubio Jr"
image: '/src/content/images/pexels-markus-winkler-1430818-4065400.jpg'
categories:
  - 'cpp'
  - 'terminal'
  - 'architecture'
  - 'programming'
---

Keeping this frontmatter consistent and aligned with the RSS schema is what makes the rest of the pipeline work without any manual cleanup. This also makes the rss.xml.ts configuration straightforward to set up. All it needs to do is read the frontmatter content and it will generate the rss.xml file at build time.

Here is what a basic rss.xml.ts file looks like:

import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';

export async function GET(context) {
  const posts = await getCollection('blog');
  return rss({
    title: 'Your Blog Name',
    description: 'Your blog description',
    site: context.site,
    items: posts.map((post) => ({
      title: post.data.title,
      pubDate: post.data.pubDate,
      description: post.data.description,
      author: post.data.author,
      categories: post.data.categories,
      link: `/blog/${post.id}/`,
    })),
  });
}

The fields in the items map directly to the frontmatter fields you define. As long as the frontmatter is consistent, the RSS output will be clean and Dev.to will be able to import it without any issues. For additional information visit the Astro RSS documentation.

Auto-Importing to Dev.to via RSS

For this part you will need a Dev.to account. Once your website is live and the RSS feed URL is active, navigate to your Dev.to dashboard. On the left-hand sidebar you will find RSS Import Feeds.

From there, click + Add a Feed Source to expand the form. Enter your rss.xml URL in the RSS Feed URL field. A couple of settings worth paying attention to:

Mark the RSS source as canonical URL by default: keep this checked. This is one of the most important settings in the whole pipeline. It tells Dev.to that your personal site is the original source of the content, which means search engines will credit your site and not the Dev.to version. Get this wrong and Dev.to can end up outranking your own site for your own writing. Always leave this on.
Replace self-referential links with DEV Community-specific links: leave this unchecked unless you are migrating your entire blog to Dev.to permanently.

Once you click Add Feed Source , Dev.to will periodically check your feed and pull in any new posts. Imported posts land as drafts , so before publishing you will want to review each one and add a series name if it is part of a multi-part post, pick tags that match popular Dev.to tags for discoverability (for example: cpp, terminal, architecture, programming), and add a cover image sourced from Pexels. When you are ready to go live, open the post editor and flip published to true in the Dev.to frontmatter at the top of the post.

Mastodon Verification and Author Attribution

I wanted to establish a presence on Mastodon, and it turns out Astro makes it easy to connect your blog to the fediverse with just two small additions.

Verification with rel="me"

Mastodon uses the rel="me" link standard to verify that you own a website. Adding it to your Astro layout head tag gives you the green checkmark on your Mastodon profile:

<link rel="me" href="https://mastodon.social/@yourusername" />

Author Attribution with fediverse:creator

The fediverse:creator meta tag is a newer addition that connects your blog posts to your Mastodon identity. When someone shares one of your posts on Mastodon, it automatically credits your account:

<meta name="fediverse:creator" content="@yourusername@mastodon.social" />

Add this to your blog post layout so it only appears on post pages rather than every page on the site. Together these two tags make your blog a proper fediverse citizen, verified, attributable, and discoverable by the tech community that has made Mastodon their home.

Adding Privacy-Friendly Analytics with Umami

When I started getting posts out I wanted to know if anyone was actually reading them. Google Analytics was the obvious choice but it felt like overkill, heavy, cookie-dependent, and requiring a consent banner just to get started. After some digging I found Umami, a lightweight privacy-friendly alternative that ticked every box. The free hobby tier covers up to 3 websites, 100K events per month, and 6 months of data retention. No cookies, no consent banners, no tracking across sites.

Setup is straightforward. Once you create your Umami account and add your site, you get a script tag to drop into your Astro layout file:

<script
  defer
  src="https://cloud.umami.is/script.js"
  data-website-id="your-website-id">
</script>

Add this to your main Layout.astro file and it will be included on every page automatically. I also added a small notice in the footer to let visitors know the site uses privacy-friendly analytics with no cookies or personal data collected, a small but honest touch that sets the right expectations.

The Umami dashboard covers all the basics: visitors, page views, referrers, locations, devices, and bounce rate. It is everything you need to understand how your content is performing without compromising your readers' privacy.

The Publishing Workflow

I typically write about something I worked on professionally, a personal project, or a topic I consider myself an expert in. Here is the end-to-end process I follow from idea to published post:

1. Write the draft in Notion I started out using Google Docs but since returning to the blog I migrated to Notion. It handles code blocks and tables properly and exports to Markdown in a way that actually translates correctly, which makes the next step much smoother.

2. Generate the Astro-ready Markdown file with frontmatter Once the draft is ready I convert it into a Markdown file with the correct frontmatter fields — title, description, pubDate, author, image, and categories — making sure everything aligns with the RSS schema.

3. Deploy to ilean.me on Sunday morning Sunday is my publishing day. I push the new post and deploy the site.

4. Dev.to picks up via RSS Dev.to periodically polls the RSS feed URL, so the post will appear as a draft in my Dev.to dashboard within a few hours depending on when it last checked.

5. Post on Mastodon the same day I share the post on Mastodon with hashtags, typically the same ones used in the post frontmatter for consistency.

6. Schedule LinkedIn for Monday morning LinkedIn has a post scheduling feature which has been a game changer. I schedule it to go live Monday morning at 8-9 AM, when recruiters and professionals are most active, letting LinkedIn's algorithm circulate it to my network and extended network over the following days.

7. Review and publish the Dev.to draft Once it lands in Dev.to I review it, add a series name if it is part of a multi-part post, set the tags, add a cover image from Pexels, and flip published to true.

Results So Far

I revived the blog in February and March of 2026. On Dev.to, in February the most views I received in a single day was 16. Since then that number has climbed to 36 views in a single day. As of April 25th 2026 Dev.to shows 435 total views, though down 24% compared to the previous 7 days, a good reminder that consistency matters.

On ilean.me, Umami shows 48 unique visitors so far. What surprised me was the geographic spread. A large portion of visitors are coming from Asia, which makes sense given that embedded systems and C++ are a common stack there. The majority are from the US, with California showing up frequently, which tracks given the tech industry concentration there.

The numbers are small but the trend is encouraging. Search engine traffic compounds over time; every post indexed is another entry point for someone to find your work. The goal was never overnight virality, it was to slowly and consistently build an online presence, and the data shows that is exactly what is happening.

What I'd Do Differently

A few honest lessons from getting this pipeline up and running.

Double check your publication dates. One post did not show up on Dev.to on time and after some digging I realized the date in the frontmatter was off by a day. Dev.to pulls from the RSS feed based on the pubDate field, so if that is wrong the post gets skipped or delayed. Always verify the date before deploying.

Be patient with the RSS fetch timing. Dev.to does not poll your feed instantly. Depending on when it last checked, it could take several hours for a new post to appear as a draft. Do not panic and assume something is broken; just give it time.

Filter out your own visits. Early on I got excited seeing a visitor from Houston in Umami before realizing it was just me clicking my own links. The free Umami tier does not have a built-in way to exclude your own IP, so just keep that in mind when reading your early numbers and take them with a grain of salt.

Find your community. One thing I want to do going forward is find Houston based tech Discord servers with software engineers and developers to share my content in. Posting in relevant communities can accelerate growth in a way that passive RSS and social posts alone cannot.

Do not check analytics too often. It is tempting at the start but the numbers move slowly and checking constantly just creates unnecessary anxiety. Set a cadence, maybe once a week, and focus on writing the next post instead.

The whole point of building this pipeline was to remove friction, and it worked. There is no year-long gap waiting to happen again; there is just the next post.

Cómo construí un pipeline de blog sin fricciones

Ilean Monterrubio Jr — Mon, 27 Apr 2026 00:00:00 +0000

¿Por qué construir un pipeline?

Quería hacer crecer mi presencia en línea: un rincón propio de internet para mostrar mis proyectos y habilidades, dirigir a la gente a mi GitHub, LinkedIn y redes sociales, y compartir mis ideas sobre lo que estaba construyendo o aprendiendo. Un objetivo bastante sencillo. La ejecución, sin embargo, resultó ser todo un proceso de aprendizaje.

Mi primer intento de bloguear fue manual y desordenado. Escribir una entrada, publicarla en algún lado, copiarla a otro y esperar que la gente la encontrara. Había configurado la obtención del feed RSS de Dev.to desde el principio, pero hasta ahí llegaba. No había una visibilidad real de si alguien estaba leyendo, ni una razón para seguir. Como era de esperarse, dejé pasar un año entero entre entradas, no porque dejara de tener cosas que decir, sino porque la fricción era demasiado alta y la vida se atravesó. Cuando empecé un nuevo trabajo, me concentré en aprender mis nuevas responsabilidades y dejé que el blog quedara en silencio.

Cuando volví a retomarlo, quería hacer las cosas de otra manera. El objetivo era simple: escribir una vez, publicar en todas partes, sin copiar y pegar entre plataformas, sin distribución manual, y con alguna forma de saber si el trabajo realmente llegaba a alguien. El feed RSS ya estaba ahí, pero las importaciones eran un desorden. El frontmatter de mis entradas no coincidía con el esquema del RSS, así que cada importación llegaba inconsistente, y hacer cambios o agregar nuevos campos al frontmatter significaba corregir cada entrada a mano. Esta vez lo que hice fue lograr que el frontmatter de Astro coincidiera correctamente con el esquema del RSS, para que las importaciones fueran limpias y uniformes desde el inicio. Ahora se trataba de conectar las piezas restantes en un pipeline en forma.

El stack

Astro Antes de lanzar mi sitio personal, había intentado construirlo con Next.js un año antes. En ese momento no lo entendía del todo y me topaba constantemente con problemas de hidratación. En un meetup local de Code and Coffee le pedí consejo a uno de los asistentes y me recomendó Astro. A los pocos días de seguir un tutorial, tenía mi sitio en vivo por primera vez. Lo combiné con Tailwind CSS para que el manejo de temas fuera fácil de mantener y actualizar más adelante.

Pexels Cada entrada necesita una imagen de portada. Pexels es mi opción de cabecera para encontrar imágenes: fotos y videos de stock libres de regalías compartidos por creadores. De alta calidad, gratis y sin dolores de cabeza por licencias.

Dev.to Esto llegó mucho después en el proceso. Tras investigar un poco, descubrí que Astro puede generar un feed rss.xml si se configura correctamente, y que Dev.to puede consultar ese feed de forma periódica para importar automáticamente las nuevas entradas. Lo único que tengo que hacer es mantener mi frontmatter en sincronía con lo que Dev.to espera del feed, sin copiar nada a mano.

Umami Quería tener visibilidad de quién estaba leyendo realmente. Después de investigar, me decidí por Umami: respetuoso con la privacidad, sin banners de cookies y con un plan gratuito para aficionados que cubre hasta 3 sitios web.

Mastodon Después de que adquirieran Twitter, decidí irme y eliminar mi perfil. Mastodon resultó encajar muy bien, sobre todo para la comunidad tech, y el fediverso tiene una energía distinta que aprecio.

LinkedIn Donde comparto manualmente cada entrada para aprovechar cómo el algoritmo de LinkedIn hace circular el contenido por tu red y tu red extendida durante unos días después de publicar.

Configurando Astro

Cada entrada del blog está escrita en formato Markdown, que Astro maneja excepcionalmente bien desde el inicio. Una de las claves para que todo funcione sin problemas es la configuración de las content collections de Astro; así es como le dices a Astro la forma de tu contenido para que pueda validarlo y consultarlo de manera consistente. Para este proyecto tengo archivos Markdown para las entradas del blog y archivos JSON para definir mis proyectos. Vale la pena leer con atención la documentación de content collections de Astro para entender cómo definir tu esquema.

Antes de ver el frontmatter, ayuda conocer el esquema que lo hace cumplir. Vive en src/content.config.ts y usa las content collections de Astro con validación de Zod. Si falta un campo del frontmatter o es del tipo incorrecto, Astro lanzará un error en tiempo de compilación en lugar de generar en silencio un feed RSS roto:

import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.date(),
    author: z.string(),
    image: z.string(),
    categories: z.array(z.string()),
  }),
});

export const collections = { blog };

Cada entrada del blog comienza con un bloque de frontmatter que impulsa todo lo que viene después, desde el feed RSS hasta las importaciones a Dev.to:

---
title: "Building a Terminal Text Editor: The View (Part 3)"
description: "In Part 3 of building wordNebula, I cover the View layer, why I chose FTXUI over ncurses..."
pubDate: 2026-04-05
author: "Ilean Monterrubio Jr"
image: '/src/content/images/pexels-markus-winkler-1430818-4065400.jpg'
categories:
  - 'cpp'
  - 'terminal'
  - 'architecture'
  - 'programming'
---

Mantener este frontmatter consistente y alineado con el esquema del RSS es lo que hace que el resto del pipeline funcione sin ninguna limpieza manual. Esto también hace que la configuración de rss.xml.ts sea sencilla de armar. Lo único que necesita hacer es leer el contenido del frontmatter y generará el archivo rss.xml en tiempo de compilación.

Así se ve un archivo rss.xml.ts básico:

import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';

export async function GET(context) {
  const posts = await getCollection('blog');
  return rss({
    title: 'Your Blog Name',
    description: 'Your blog description',
    site: context.site,
    items: posts.map((post) => ({
      title: post.data.title,
      pubDate: post.data.pubDate,
      description: post.data.description,
      author: post.data.author,
      categories: post.data.categories,
      link: `/blog/${post.id}/`,
    })),
  });
}

Los campos del items se corresponden directamente con los campos del frontmatter que definas. Mientras el frontmatter sea consistente, la salida del RSS será limpia y Dev.to podrá importarlo sin ningún problema. Para más información, visita la documentación de RSS de Astro.

Importación automática a Dev.to vía RSS

Para esta parte necesitarás una cuenta de Dev.to. Una vez que tu sitio web esté en vivo y la URL del feed RSS esté activa, ve a tu panel de Dev.to. En la barra lateral izquierda encontrarás RSS Import Feeds.

Desde ahí, haz clic en + Add a Feed Source para desplegar el formulario. Ingresa la URL de tu rss.xml en el campo RSS Feed URL. Un par de ajustes a los que vale la pena prestar atención:

Mark the RSS source as canonical URL by default: déjalo activado. Este es uno de los ajustes más importantes de todo el pipeline. Le indica a Dev.to que tu sitio personal es la fuente original del contenido, lo que significa que los motores de búsqueda darán crédito a tu sitio y no a la versión de Dev.to. Si te equivocas en esto, Dev.to puede terminar posicionándose por encima de tu propio sitio con tus propios textos. Déjalo siempre activado.
Replace self-referential links with DEV Community-specific links: déjalo desactivado, a menos que estés migrando todo tu blog a Dev.to de forma permanente.

Una vez que hagas clic en Add Feed Source , Dev.to revisará tu feed periódicamente e importará cualquier entrada nueva. Las entradas importadas llegan como borradores , así que antes de publicar conviene revisar cada una y agregar un nombre de serie si forma parte de una entrada de varias partes, elegir etiquetas que coincidan con las etiquetas populares de Dev.to para que sea más fácil de descubrir (por ejemplo: cpp, terminal, architecture, programming) y agregar una imagen de portada tomada de Pexels. Cuando estés listo para publicar, abre el editor de la entrada y cambia published a true en el frontmatter de Dev.to al inicio de la entrada.

Verificación con Mastodon y atribución de autoría

Quería establecer una presencia en Mastodon, y resulta que Astro facilita conectar tu blog al fediverso con solo dos pequeñas adiciones.

Verificación con rel="me"

Mastodon usa el estándar de enlace rel="me" para verificar que eres dueño de un sitio web. Agregarlo a la etiqueta head de tu layout de Astro te da la palomita verde en tu perfil de Mastodon:

<link rel="me" href="https://mastodon.social/@yourusername" />

Atribución de autoría con fediverse:creator

La meta etiqueta fediverse:creator es una adición más reciente que conecta las entradas de tu blog con tu identidad de Mastodon. Cuando alguien comparte una de tus entradas en Mastodon, le da crédito a tu cuenta automáticamente:

<meta name="fediverse:creator" content="@yourusername@mastodon.social" />

Agrégalo al layout de tus entradas para que solo aparezca en las páginas de las entradas y no en todas las páginas del sitio. Juntas, estas dos etiquetas convierten a tu blog en un ciudadano del fediverso en forma: verificado, atribuible y fácil de descubrir por la comunidad tech que ha hecho de Mastodon su hogar.

Agregando analíticas respetuosas con la privacidad con Umami

Cuando empecé a sacar entradas, quería saber si alguien las estaba leyendo de verdad. Google Analytics era la opción obvia, pero se sentía excesivo: pesado, dependiente de cookies y que requería un banner de consentimiento solo para empezar. Tras investigar un poco encontré Umami, una alternativa ligera y respetuosa con la privacidad que cumplía con todo. El plan gratuito para aficionados cubre hasta 3 sitios web, 100 mil eventos al mes y 6 meses de retención de datos. Sin cookies, sin banners de consentimiento, sin rastreo entre sitios.

La configuración es sencilla. Una vez que creas tu cuenta de Umami y agregas tu sitio, obtienes una etiqueta de script para colocar en el archivo de layout de Astro:

<script
  defer
  src="https://cloud.umami.is/script.js"
  data-website-id="your-website-id">
</script>

Agrégalo a tu archivo principal Layout.astro y se incluirá automáticamente en cada página. También agregué un pequeño aviso en el pie de página para que los visitantes sepan que el sitio usa analíticas respetuosas con la privacidad, sin cookies ni recolección de datos personales; un detalle pequeño pero honesto que establece las expectativas correctas.

El panel de Umami cubre todo lo básico: visitantes, vistas de página, referencias, ubicaciones, dispositivos y tasa de rebote. Es todo lo que necesitas para entender cómo está funcionando tu contenido sin comprometer la privacidad de tus lectores.

El flujo de publicación

Normalmente escribo sobre algo en lo que trabajé profesionalmente, un proyecto personal o un tema en el que me considero experto. Este es el proceso de principio a fin que sigo desde la idea hasta la entrada publicada:

1. Escribir el borrador en Notion Empecé usando Google Docs, pero desde que retomé el blog me migré a Notion. Maneja bien los bloques de código y las tablas, y exporta a Markdown de una forma que realmente se traduce correctamente, lo que hace que el siguiente paso sea mucho más fluido.

2. Generar el archivo Markdown listo para Astro con frontmatter Una vez que el borrador está listo, lo convierto en un archivo Markdown con los campos de frontmatter correctos —title, description, pubDate, author, image y categories— asegurándome de que todo se alinee con el esquema del RSS.

3. Desplegar en ilean.me el domingo por la mañana El domingo es mi día de publicación. Subo la nueva entrada y despliego el sitio.

4. Dev.to la recoge vía RSS Dev.to consulta periódicamente la URL del feed RSS, así que la entrada aparecerá como borrador en mi panel de Dev.to en unas horas, dependiendo de cuándo revisó por última vez.

5. Publicar en Mastodon el mismo día Comparto la entrada en Mastodon con hashtags, normalmente los mismos que uso en el frontmatter de la entrada para mantener la consistencia.

6. Programar LinkedIn para el lunes por la mañana LinkedIn tiene una función para programar publicaciones que ha sido un cambio total. La programo para que salga el lunes por la mañana entre las 8 y 9 AM, cuando los reclutadores y profesionales están más activos, dejando que el algoritmo de LinkedIn la haga circular por mi red y mi red extendida durante los días siguientes.

7. Revisar y publicar el borrador de Dev.to Una vez que llega a Dev.to, lo reviso, agrego un nombre de serie si forma parte de una entrada de varias partes, configuro las etiquetas, agrego una imagen de portada de Pexels y cambio published a true.

Resultados hasta ahora

Reviví el blog en febrero y marzo de 2026. En Dev.to, en febrero la mayor cantidad de vistas que recibí en un solo día fue 16. Desde entonces ese número subió a 36 vistas en un solo día. Al 25 de abril de 2026, Dev.to muestra 435 vistas totales, aunque con una baja del 24 % respecto a los 7 días anteriores, un buen recordatorio de que la consistencia importa.

En ilean.me, Umami muestra 48 visitantes únicos hasta ahora. Lo que me sorprendió fue la distribución geográfica. Una buena parte de los visitantes viene de Asia, lo cual tiene sentido dado que los sistemas embebidos y C++ son un stack común allá. La mayoría viene de Estados Unidos, con California apareciendo con frecuencia, lo que cuadra dada la concentración de la industria tecnológica ahí.

Los números son pequeños, pero la tendencia es alentadora. El tráfico de los motores de búsqueda se acumula con el tiempo; cada entrada indexada es otro punto de entrada para que alguien encuentre tu trabajo. El objetivo nunca fue volverse viral de la noche a la mañana, sino construir una presencia en línea de forma lenta y constante, y los datos muestran que es exactamente lo que está pasando.

Qué haría diferente

Algunas lecciones honestas de poner este pipeline en marcha.

Verifica dos veces tus fechas de publicación. Una entrada no apareció a tiempo en Dev.to y, tras investigar un poco, me di cuenta de que la fecha en el frontmatter estaba desfasada por un día. Dev.to toma del feed RSS según el campo pubDate, así que si está mal, la entrada se omite o se retrasa. Verifica siempre la fecha antes de desplegar.

Ten paciencia con los tiempos de obtención del RSS. Dev.to no consulta tu feed al instante. Dependiendo de cuándo revisó por última vez, una entrada nueva puede tardar varias horas en aparecer como borrador. No entres en pánico ni asumas que algo está roto; solo dale tiempo.

Filtra tus propias visitas. Al principio me emocioné al ver un visitante de Houston en Umami, antes de darme cuenta de que era yo haciendo clic en mis propios enlaces. El plan gratuito de Umami no tiene una forma integrada de excluir tu propia IP, así que tenlo en cuenta al leer tus primeros números y tómalos con cautela.

Encuentra tu comunidad. Algo que quiero hacer de aquí en adelante es encontrar servidores de Discord tech de Houston con ingenieros de software y desarrolladores donde compartir mi contenido. Publicar en comunidades relevantes puede acelerar el crecimiento de una forma que el RSS pasivo y las publicaciones en redes por sí solos no pueden.

No revises las analíticas con demasiada frecuencia. Es tentador al principio, pero los números se mueven despacio y revisarlos constantemente solo genera ansiedad innecesaria. Establece una frecuencia, tal vez una vez por semana, y mejor concéntrate en escribir la siguiente entrada.

Todo el propósito de construir este pipeline era eliminar la fricción, y funcionó. Ya no hay un hueco de un año esperando a repetirse; solo está la siguiente entrada.

Building a Terminal Text Editor: The View (Part 3)

Ilean Monterrubio Jr — Mon, 06 Apr 2026 00:00:00 +0000

Recap

In Part 1, I talked about the origin of this project, the early architectural decisions, and why I picked the GapBuffer with IBuffer as the contract for all future buffer implementations. In Part 2, we got into the details of the Presenter, how it wires the components together, handles user input, manages state, and keeps the Model and View in sync. Now we can move on to the View.

What is the View?

The View is the component that the user interacts with directly. All user inputs are collected and passed to the Presenter, the View doesn't decide what to do with them. It is also responsible for rendering the text the user types, along with any warnings, statistics like word count, and whether the file is unsaved. The View doesn't calculate any of this, it just displays whatever the Presenter sends it. Another example of how all three parts of the Model-View-Presenter separate concerns.

Why FTXUI instead of ncurses

In the proof of concept testing, I used ncurses, the de facto standard library for building terminal interfaces. It worked well for the initial testing, and I see a lot of projects still using it; it's tried and true. While ncurses would have been a great choice, I did a bit more research and found FTXUI, a modern C++ library with components to build interactive terminal user interfaces. I wanted to leverage that it uses modern C++, matching the project's early defined specification of targeting C++20.

The IView Interface

While implementing the other components (Model and Presenter), I mocked up a thin interface for the View, IView. At first, it was only taking character input and not accounting for special characters, and it didn't handle rendering any data. The proof of concept View just took the input, sent it to the Presenter, which would send it to the buffer and log it so I could see the data was actually flowing through the system.

I was thinking of removing it, but after doing more research, I decided to expand the interface instead. Keeping IView as an abstract class means that if someone wants to write their own View for an OS that isn't supported by FTXUI, they can implement the interface and plug it in without touching the Presenter or Model.

class IView {
  public:
    virtual ~IView() = default;

    virtual void run(std::function<void(const InputEvent &)> onInput) = 0;
    virtual void render(const ViewState &state) = 0;
    virtual void exit() = 0;
    virtual std::pair<int, int> getTerminalSize() const = 0;
    virtual void showMessage(const std::string &message, bool isError = false) = 0;
};

A quick explanation, run() starts the event loop and takes a callback for handling input, this is what the Presenter calls in its main loop. render() takes the ViewState we saw in Part 2 and draws it to the screen. exit() and getTerminalSize() do what they say, and showMessage() is how the Presenter displays warnings like the "unsaved changes" prompt from the exit flow.

Rendering the UI

As we showed in Part 2, the ViewState struct defines the contract for how the Presenter sends data to the View:

struct ViewState {
    // Content
    std::string visibleText; // Text currently visible in viewport
    int cursorPosition; // Linear position of cursor in visibleText

    // Status bar information
    int wordCount; // Total word count (primary metric for writers)
    std::string filename; // Current file name (or "Untitled")
    bool isDirty; // Unsaved changes indicator

    // UI state
    std::string statusMessage; // Temporary status message (e.g., "Saved", "Error: ...")
    bool showHelp; // Whether to show help overlay
};

There are three major types of data in the ViewState contract: Content , which tells us the cursorPosition and the visibleText. Status bar information : wordCount, filename, and isDirty which indicates whether the file is unsaved. Finally, the UI state : statusMessage and showHelp.

One of the biggest challenges was how to deal with the cursor, how to move it, and be able to add more to the buffer when the cursor moves. One of the simplest solutions is to break the visibleText into three components: beforeCursor, cursor, and afterCursor.

ftxui::Element FtxuiView::renderEditor() {
    const auto &text = currentState.visibleText;
    const size_t pos = static_cast<size_t>(currentState.cursorPosition);

    auto before = ftxui::text(text.substr(0, pos));

    // Character at cursor with cyan background
    std::string cursorChar = pos < text.size() ? std::string(1, text[pos]) : " ";
    auto cursor = ftxui::text(cursorChar) | ftxui::bgcolor(ftxui::Color::Cyan) | ftxui::color(ftxui::Color::Black);

    auto after = pos + 1 < text.size() ? ftxui::text(text.substr(pos + 1)) : ftxui::text("");

    return ftxui::hbox({before, cursor, after});
}

The cursor is highlighted with a cyan background so the user can see where they are in the text. This challenge existed in both ncurses and FTXUI, neither library gives you a built-in cursor for a custom text editor. You have to simulate it yourself.

Translating Keyboard Input

The View is also responsible for translating raw keyboard events into the InputEvent structs that the Presenter understands. FTXUI has its own event system, so the View needs a translation layer between what FTXUI gives us and what our Presenter expects. The translateEvent() method handles this mapping:

InputEvent FtxuiView::translateEvent(const ftxui::Event &event) {
    if (event == ftxui::Event::ArrowLeft)
        return {InputEvent::Type::ARROW_LEFT};
    if (event == ftxui::Event::ArrowRight)
        return {InputEvent::Type::ARROW_RIGHT};
    if (event == ftxui::Event::Backspace)
        return {InputEvent::Type::BACKSPACE};
    if (event == ftxui::Event::Return)
        return {InputEvent::Type::ENTER};
    if (event == ftxui::Event::CtrlQ)
        return {InputEvent::Type::CTRL_Q};
    if (event == ftxui::Event::CtrlS)
        return {InputEvent::Type::CTRL_S};

    // Printable character
    if (event.is_character()) {
        InputEvent ie{InputEvent::Type::CHARACTER};
        ie.character = event.character()[0];
        return ie;
    }

    return {InputEvent::Type::UNKNOWN};
}

The pattern is straightforward, each FTXUI event maps to one of our InputEvent types. If it's a printable character, we extract the character value. If we don't recognize the event, it returns UNKNOWN and gets ignored. This is the same translation layer that would need to be reimplemented if someone wrote a new View using a different library, another benefit of the IView interface.

What the View Can Do So Far

The View works well for the current state of the project. It renders text as the user types, displays the status bar with the filename, word count, and unsaved changes indicator, captures all input events and routes them to the Presenter, and toggles the help overlay with F1. It is not perfect, newlines don't render yet and the arrow keys can't fully navigate up and down through the text. But for Phase 1, it does its job as the passive layer in the MVP pattern.

Wrapping Up the Series

This wraps up the three-part series on building wordNebula's Phase 1. Across these posts, we went from the origin of the project and why I chose Model-View-Presenter, through the Model with the GapBuffer and IBuffer interface, the Presenter that orchestrates everything and manages state, and finally the View that renders it all to the terminal.

Building each layer independently and connecting them through contracts like IBuffer and IView made the project manageable. I could work on one piece at a time without worrying about breaking the others. That separation is the whole point of MVP, and it paid off.

Phase 1 is complete but far from finished. There's more to build, but for now I'm stepping away to focus on other projects. If you want to explore the code, check out the project on GitHub.

Construyendo un editor de texto de terminal: la Vista (Parte 3)

Ilean Monterrubio Jr — Sun, 05 Apr 2026 00:00:00 +0000

Resumen

En la Parte 1 hablé del origen de este proyecto, las primeras decisiones de arquitectura y por qué elegí el GapBuffer con IBuffer como el contrato para todas las futuras implementaciones de búfer. En la Parte 2 entramos en los detalles del Presentador, cómo conecta los componentes, maneja la entrada del usuario, gestiona el estado y mantiene el Modelo y la Vista sincronizados. Ahora podemos pasar a la Vista.

¿Qué es la Vista?

La Vista es el componente con el que el usuario interactúa directamente. Todas las entradas del usuario se recopilan y se pasan al Presentador; la Vista no decide qué hacer con ellas. También es responsable de renderizar el texto que el usuario escribe, junto con cualquier advertencia, estadísticas como el conteo de palabras y si el archivo está sin guardar. La Vista no calcula nada de esto, solo muestra lo que el Presentador le envía. Otro ejemplo de cómo las tres partes de Modelo-Vista-Presentador separan las responsabilidades.

Por qué FTXUI en lugar de ncurses

En las pruebas de la prueba de concepto usé ncurses, la biblioteca estándar de facto para construir interfaces de terminal. Funcionó bien para las pruebas iniciales, y veo muchos proyectos que todavía la usan; es confiable y probada. Aunque ncurses habría sido una gran elección, investigué un poco más y encontré FTXUI, una biblioteca de C++ moderna con componentes para construir interfaces de usuario de terminal interactivas. Quería aprovechar que usa C++ moderno, en línea con la especificación que definí al inicio del proyecto de apuntar a C++20.

La interfaz IView

Mientras implementaba los otros componentes (el Modelo y el Presentador), armé una interfaz ligera para la Vista, IView. Al principio solo tomaba la entrada de caracteres y no contemplaba los caracteres especiales, ni se encargaba de renderizar dato alguno. La Vista de la prueba de concepto solo tomaba la entrada, la enviaba al Presentador, que la mandaba al búfer y la registraba para que yo pudiera ver que los datos realmente fluían por el sistema.

Pensaba en eliminarla, pero después de investigar más, decidí más bien expandir la interfaz. Mantener IView como una clase abstracta significa que, si alguien quiere escribir su propia Vista para un sistema operativo que FTXUI no soporta, puede implementar la interfaz y conectarla sin tocar el Presentador ni el Modelo.

class IView {
  public:
    virtual ~IView() = default;

    virtual void run(std::function<void(const InputEvent &)> onInput) = 0;
    virtual void render(const ViewState &state) = 0;
    virtual void exit() = 0;
    virtual std::pair<int, int> getTerminalSize() const = 0;
    virtual void showMessage(const std::string &message, bool isError = false) = 0;
};

Una explicación rápida: run() inicia el bucle de eventos y recibe un callback para manejar la entrada; esto es lo que el Presentador llama en su bucle principal. render() toma el ViewState que vimos en la Parte 2 y lo dibuja en la pantalla. exit() y getTerminalSize() hacen lo que dicen, y showMessage() es la forma en que el Presentador muestra advertencias como el aviso de "cambios sin guardar" del flujo de salida.

Renderizando la interfaz

Como mostramos en la Parte 2, la estructura ViewState define el contrato de cómo el Presentador envía datos a la Vista:

struct ViewState {
    // Content
    std::string visibleText; // Text currently visible in viewport
    int cursorPosition; // Linear position of cursor in visibleText

    // Status bar information
    int wordCount; // Total word count (primary metric for writers)
    std::string filename; // Current file name (or "Untitled")
    bool isDirty; // Unsaved changes indicator

    // UI state
    std::string statusMessage; // Temporary status message (e.g., "Saved", "Error: ...")
    bool showHelp; // Whether to show help overlay
};

Hay tres grandes tipos de datos en el contrato de ViewState: Contenido , que nos dice la cursorPosition y el visibleText. Información de la barra de estado : wordCount, filename e isDirty, que indica si el archivo está sin guardar. Por último, el estado de la interfaz : statusMessage y showHelp.

Uno de los mayores retos fue cómo lidiar con el cursor, cómo moverlo y poder agregar más al búfer cuando el cursor se mueve. Una de las soluciones más simples es dividir el visibleText en tres componentes: beforeCursor, cursor y afterCursor.

ftxui::Element FtxuiView::renderEditor() {
    const auto &text = currentState.visibleText;
    const size_t pos = static_cast<size_t>(currentState.cursorPosition);

    auto before = ftxui::text(text.substr(0, pos));

    // Character at cursor with cyan background
    std::string cursorChar = pos < text.size() ? std::string(1, text[pos]) : " ";
    auto cursor = ftxui::text(cursorChar) | ftxui::bgcolor(ftxui::Color::Cyan) | ftxui::color(ftxui::Color::Black);

    auto after = pos + 1 < text.size() ? ftxui::text(text.substr(pos + 1)) : ftxui::text("");

    return ftxui::hbox({before, cursor, after});
}

El cursor se resalta con un fondo cian para que el usuario pueda ver dónde está en el texto. Este reto existía tanto en ncurses como en FTXUI; ninguna biblioteca te da un cursor integrado para un editor de texto personalizado. Tienes que simularlo tú mismo.

Traduciendo la entrada del teclado

La Vista también es responsable de traducir los eventos crudos del teclado a las estructuras InputEvent que el Presentador entiende. FTXUI tiene su propio sistema de eventos, así que la Vista necesita una capa de traducción entre lo que FTXUI nos da y lo que nuestro Presentador espera. El método translateEvent() se encarga de este mapeo:

InputEvent FtxuiView::translateEvent(const ftxui::Event &event) {
    if (event == ftxui::Event::ArrowLeft)
        return {InputEvent::Type::ARROW_LEFT};
    if (event == ftxui::Event::ArrowRight)
        return {InputEvent::Type::ARROW_RIGHT};
    if (event == ftxui::Event::Backspace)
        return {InputEvent::Type::BACKSPACE};
    if (event == ftxui::Event::Return)
        return {InputEvent::Type::ENTER};
    if (event == ftxui::Event::CtrlQ)
        return {InputEvent::Type::CTRL_Q};
    if (event == ftxui::Event::CtrlS)
        return {InputEvent::Type::CTRL_S};

    // Printable character
    if (event.is_character()) {
        InputEvent ie{InputEvent::Type::CHARACTER};
        ie.character = event.character()[0];
        return ie;
    }

    return {InputEvent::Type::UNKNOWN};
}

El patrón es sencillo: cada evento de FTXUI se mapea a uno de nuestros tipos InputEvent. Si es un carácter imprimible, extraemos el valor del carácter. Si no reconocemos el evento, devuelve UNKNOWN y se ignora. Esta es la misma capa de traducción que habría que reimplementar si alguien escribiera una nueva Vista usando una biblioteca distinta, otro beneficio de la interfaz IView.

Lo que la Vista puede hacer hasta ahora

La Vista funciona bien para el estado actual del proyecto. Renderiza el texto conforme el usuario escribe, muestra la barra de estado con el nombre del archivo, el conteo de palabras y el indicador de cambios sin guardar, captura todos los eventos de entrada y los enruta al Presentador, y alterna la superposición de ayuda con F1. No es perfecta: los saltos de línea todavía no se renderizan y las teclas de flecha no pueden navegar del todo hacia arriba y hacia abajo por el texto. Pero para la Fase 1, cumple su trabajo como la capa pasiva del patrón MVP.

Cerrando la serie

Con esto cerramos la serie de tres partes sobre la construcción de la Fase 1 de wordNebula. A lo largo de estas entradas fuimos desde el origen del proyecto y por qué elegí Modelo-Vista-Presentador, pasando por el Modelo con el GapBuffer y la interfaz IBuffer, el Presentador que orquesta todo y gestiona el estado, y finalmente la Vista que lo renderiza todo en la terminal.

Construir cada capa de forma independiente y conectarlas mediante contratos como IBuffer e IView hizo que el proyecto fuera manejable. Podía trabajar en una pieza a la vez sin preocuparme por romper las demás. Esa separación es justamente el propósito de MVP, y valió la pena.

La Fase 1 está completa pero lejos de estar terminada. Hay más por construir, pero por ahora me alejo para enfocarme en otros proyectos. Si quieres explorar el código, échale un vistazo al proyecto en GitHub.

Building a Terminal Text Editor: The Presenter (Part 2)

Ilean Monterrubio Jr — Sun, 22 Mar 2026 00:00:00 +0000

Recap

In Part 1, I talked about the origin of this project and the early architectural decisions. After picking Model-View-Presenter, breaking up the project into Model, View, and Presenter felt like the natural path forward. We tackled the GapBuffer with IBuffer as the contract for all future buffer implementations. With the Model standing on its own, we can move on to the Presenter.

What is the Presenter?

We already hinted in Part 1 that the Presenter is the orchestrator — the one that handles all the application's "business" logic. It is responsible for keeping both the Model and the View up to date. The Presenter takes user input from the View and passes it to the Model, then pulls the updated data from the Model and sends it back to the View for rendering. All communication between the two goes through the Presenter.

Let's take the most common use case of a user pressing a single key stroke. In reality, they will be typing several in succession, and this process gets repeated constantly in the current implementation.

Step	From	To	What Happens
1	User (actor)	View	Presses key
2	View	Presenter	Passes the key event
3	Presenter	Model	Calls insertChar()
4	Presenter	Model	Requests updated text
5	Presenter	View	Sends text to render

We see the big role that the Presenter fills and we will explore how we created contracts between the components to ensure that data is passed correctly. For wordNebula, this also means the Presenter will be where future logic lives.

Wiring It Together

Since this project is using modern C++ I wanted to take advantage of smart pointers and leverage Resource Acquisition Is Initialization (RAII). This way we don't have to explicitly manage memory — this is standard practice in modern C++ for any systems project.

When starting to wire up the different components, including the mock View from the original testing I did before tackling the full project, I had to make some decisions on ownership. Here is how the three components get created in main:

const auto presenter = std::make_shared<WNebulaPresenter>();
const auto model = std::make_shared<WNebulaModel>();
const auto view = std::make_shared<FtxuiView>();

presenter->setup(view, model);
presenter->run();

All three are created as shared_ptr, but inside the Presenter they are stored differently:

std::weak_ptr<IView> view;
std::shared_ptr<WNebulaModel> model;

The Model stays as a shared_ptr because the Presenter needs to own it — it is the core data and must exist as long as the application is running. The View is stored as a weak_ptr to break a circular dependency. The Presenter needs the View to push updates, and the View needs the Presenter to send input. If both held shared_ptr to each other, neither would ever get cleaned up.

The trade-off with weak_ptr is that every time the Presenter needs to update the View, it has to convert it back to a shared_ptr temporarily by calling lock(). If the View still exists, lock() gives us a valid shared_ptr to work with. If it doesn't, we know the View is gone and can handle it gracefully. This happens inside updateView() every time the Presenter needs to render new data to the screen.

Handling User Input

In the exploratory testing, I only worried about character user input — it was just to test if I understood the architecture. For the real implementation, I needed to actually account for special keys: CTRL, BACKSPACE, DELETE, ARROW KEYS, ENTER, and so on.

To handle this cleanly, I created an InputEvent struct that translates raw keyboard input into semantic events:

struct InputEvent {
    enum class Type {
        CHARACTER,
        ARROW_LEFT, ARROW_RIGHT, ARROW_UP, ARROW_DOWN,
        CTRL_LEFT, CTRL_RIGHT, CTRL_UP, CTRL_DOWN,
        HOME, END,
        BACKSPACE, DELETE, ENTER,
        CTRL_S, CTRL_Q,
        ESCAPE,
        // ... other types
    };

    Type type;
    char character = '\0'; // Only valid for Type::CHARACTER
};

This way the Presenter doesn't care about terminal escape codes — it just receives an event type and acts on it. The handleInput method routes each event to the right operation:

void WNebulaPresenter::handleInput(const InputEvent &event) {
    switch (event.type) {
    case InputEvent::Type::CHARACTER:
        onInsert(event.character);
        break;
    case InputEvent::Type::BACKSPACE:
        onDelete();
        break;
    case InputEvent::Type::CTRL_LEFT:
        onCtrlLeft();
        break;
    case InputEvent::Type::CTRL_Q:
        onExit();
        break;
    // ... other cases
    }
}

Each operation follows the same pattern — delegate to the Model, mark dirty if needed, update the View:

void WNebulaPresenter::onInsert(char c) {
    model->insertChar(c);
    isDirty = true;
    updateView();
}

Viewport Management

One of the things I learned along the way, or had to really think about, was the viewport. So far, the initial testing was me writing simple sentences, not full blog entries or longer format text. The area of the terminal is finite, so determining what portion of the buffer to display and how to present it was a challenge.

The Presenter solves this by building a ViewState — a struct that packages everything the View needs to render:

struct ViewState {
    std::string visibleText;
    int cursorPosition;
    int wordCount;
    std::string filename;
    bool isDirty;
    bool showHelp;
};

Every time the Presenter updates the View, it pulls the current text and cursor position from the Model and sends it as a ViewState. The View doesn't know anything about the buffer — it just renders whatever state it receives. Here is the updateView() method that builds and sends that state:

void WNebulaPresenter::updateView() {
    if (auto v = view.lock()) {
        ViewState state{};
        state.visibleText = model->getText();
        state.cursorPosition = model->getCursorPosition();
        state.wordCount = model->getWordCount();
        state.filename = currentFilePath.empty() ? "Untitled" : currentFilePath;
        state.isDirty = isDirty;
        state.showHelp = showHelp;
        v->render(state);
    }
}

Notice the view.lock() — this is the weak_ptr conversion we talked about in the Wiring section. Every time the Presenter needs to update the View, it checks that the View still exists before sending data.

State Management

For managing state in this iteration of the project I kept it simple. The Presenter tracks a few boolean flags — isDirty to know when the file hasn't been saved, isRunning to control the main loop, showHelp to toggle the help overlay, and exitWarningShown for the quit confirmation.

The most interesting one is the exit flow. If you have unsaved changes and press Ctrl+Q, the Presenter warns you and makes you press it again to actually quit:

void WNebulaPresenter::onExit() {
    if (isDirty && !exitWarningShown) {
        exitWarningShown = true;
        if (auto v = view.lock()) {
            v->showMessage("Unsaved changes! Press Ctrl+Q again to quit.", true);
        }
        return;
    }
    isRunning = false;
    if (auto v = view.lock()) {
        v->exit();
    }
}

What the Presenter Can Do So Far

At this stage, the Presenter takes in all input events and determines if it is a special key or character, fully manages the state of the application and document, and keeps the Model and View in sync. It is the glue between the two, and because of MVP, it can be tested independently.

What's Next

In Part 3, I will talk about why I picked FTXUI instead of ncurses and what it offers out of the box that made the View layer easier to build. You can check out the project on GitHub.

Construyendo un editor de texto de terminal: el Presentador (Parte 2)

Ilean Monterrubio Jr — Sun, 22 Mar 2026 00:00:00 +0000

Resumen

En la Parte 1 hablé del origen de este proyecto y de las primeras decisiones de arquitectura. Después de elegir Modelo-Vista-Presentador, dividir el proyecto en Modelo, Vista y Presentador se sintió como el camino natural. Abordamos el GapBuffer con IBuffer como el contrato para todas las futuras implementaciones de búfer. Con el Modelo sosteniéndose por sí solo, podemos pasar al Presentador.

¿Qué es el Presentador?

Ya insinuamos en la Parte 1 que el Presentador es el orquestador: el que maneja toda la lógica de "negocio" de la aplicación. Es responsable de mantener actualizados tanto el Modelo como la Vista. El Presentador toma la entrada del usuario desde la Vista y se la pasa al Modelo, luego obtiene los datos actualizados del Modelo y los envía de vuelta a la Vista para renderizarlos. Toda la comunicación entre ambos pasa por el Presentador.

Tomemos el caso de uso más común: un usuario presionando una sola tecla. En realidad estará escribiendo varias en sucesión, y este proceso se repite constantemente en la implementación actual.

Paso	De	A	Qué ocurre
1	Usuario (actor)	Vista	Presiona una tecla
2	Vista	Presentador	Pasa el evento de tecla
3	Presentador	Modelo	Llama a insertChar()
4	Presentador	Modelo	Solicita el texto actualizado
5	Presentador	Vista	Envía el texto para renderizar

Vemos el gran papel que cumple el Presentador y exploraremos cómo creamos contratos entre los componentes para asegurar que los datos se pasen correctamente. Para wordNebula, esto también significa que el Presentador será donde viva la lógica futura.

Conectándolo todo

Como este proyecto usa C++ moderno, quise aprovechar los smart pointers y apoyarme en Resource Acquisition Is Initialization (RAII). De esta forma no tenemos que gestionar la memoria de forma explícita; es la práctica estándar en C++ moderno para cualquier proyecto de sistemas.

Al empezar a conectar los distintos componentes, incluyendo la Vista simulada de las pruebas originales que hice antes de abordar el proyecto completo, tuve que tomar algunas decisiones sobre la propiedad (ownership). Así se crean los tres componentes en main:

const auto presenter = std::make_shared<WNebulaPresenter>();
const auto model = std::make_shared<WNebulaModel>();
const auto view = std::make_shared<FtxuiView>();

presenter->setup(view, model);
presenter->run();

Los tres se crean como shared_ptr, pero dentro del Presentador se almacenan de forma diferente:

std::weak_ptr<IView> view;
std::shared_ptr<WNebulaModel> model;

El Modelo se queda como shared_ptr porque el Presentador necesita ser su dueño: son los datos centrales y deben existir mientras la aplicación esté corriendo. La Vista se almacena como weak_ptr para romper una dependencia circular. El Presentador necesita la Vista para enviar actualizaciones, y la Vista necesita al Presentador para enviar la entrada. Si ambos guardaran un shared_ptr el uno del otro, ninguno se liberaría jamás.

La contrapartida de weak_ptr es que cada vez que el Presentador necesita actualizar la Vista, tiene que convertirla temporalmente de vuelta a un shared_ptr llamando a lock(). Si la Vista todavía existe, lock() nos da un shared_ptr válido con el cual trabajar. Si no, sabemos que la Vista ya no está y podemos manejarlo de forma elegante. Esto ocurre dentro de updateView() cada vez que el Presentador necesita renderizar datos nuevos en la pantalla.

Manejando la entrada del usuario

En las pruebas exploratorias solo me preocupaba por la entrada de caracteres; era únicamente para comprobar si entendía la arquitectura. Para la implementación real, necesitaba realmente contemplar las teclas especiales: CTRL, BACKSPACE, DELETE, ARROW KEYS, ENTER, etc.

Para manejar esto de forma limpia, creé una estructura InputEvent que traduce la entrada cruda del teclado en eventos semánticos:

struct InputEvent {
    enum class Type {
        CHARACTER,
        ARROW_LEFT, ARROW_RIGHT, ARROW_UP, ARROW_DOWN,
        CTRL_LEFT, CTRL_RIGHT, CTRL_UP, CTRL_DOWN,
        HOME, END,
        BACKSPACE, DELETE, ENTER,
        CTRL_S, CTRL_Q,
        ESCAPE,
        // ... other types
    };

    Type type;
    char character = '\0'; // Only valid for Type::CHARACTER
};

De esta forma al Presentador no le importan los códigos de escape de la terminal: solo recibe un tipo de evento y actúa en consecuencia. El método handleInput enruta cada evento a la operación correcta:

void WNebulaPresenter::handleInput(const InputEvent &event) {
    switch (event.type) {
    case InputEvent::Type::CHARACTER:
        onInsert(event.character);
        break;
    case InputEvent::Type::BACKSPACE:
        onDelete();
        break;
    case InputEvent::Type::CTRL_LEFT:
        onCtrlLeft();
        break;
    case InputEvent::Type::CTRL_Q:
        onExit();
        break;
    // ... other cases
    }
}

Cada operación sigue el mismo patrón: delegar en el Modelo, marcar como modificado (dirty) si hace falta y actualizar la Vista:

void WNebulaPresenter::onInsert(char c) {
    model->insertChar(c);
    isDirty = true;
    updateView();
}

Gestión del viewport

Una de las cosas que aprendí en el camino, o sobre la que tuve que pensar de verdad, fue el viewport. Hasta ese momento, las pruebas iniciales consistían en que yo escribía frases sencillas, no entradas de blog completas ni texto de formato más largo. El área de la terminal es finita, así que determinar qué porción del búfer mostrar y cómo presentarla fue todo un reto.

El Presentador resuelve esto construyendo un ViewState: una estructura que empaqueta todo lo que la Vista necesita para renderizar:

struct ViewState {
    std::string visibleText;
    int cursorPosition;
    int wordCount;
    std::string filename;
    bool isDirty;
    bool showHelp;
};

Cada vez que el Presentador actualiza la Vista, obtiene el texto actual y la posición del cursor del Modelo y los envía como un ViewState. La Vista no sabe nada del búfer: solo renderiza cualquier estado que reciba. Aquí está el método updateView() que construye y envía ese estado:

void WNebulaPresenter::updateView() {
    if (auto v = view.lock()) {
        ViewState state{};
        state.visibleText = model->getText();
        state.cursorPosition = model->getCursorPosition();
        state.wordCount = model->getWordCount();
        state.filename = currentFilePath.empty() ? "Untitled" : currentFilePath;
        state.isDirty = isDirty;
        state.showHelp = showHelp;
        v->render(state);
    }
}

Fíjate en el view.lock(): es la conversión de weak_ptr de la que hablamos en la sección de conexión. Cada vez que el Presentador necesita actualizar la Vista, comprueba que la Vista todavía exista antes de enviar datos.

Gestión del estado

Para gestionar el estado en esta iteración del proyecto lo mantuve simple. El Presentador rastrea unas cuantas banderas booleanas: isDirty para saber cuándo el archivo no se ha guardado, isRunning para controlar el bucle principal, showHelp para alternar la superposición de ayuda y exitWarningShown para la confirmación de salida.

El más interesante es el flujo de salida. Si tienes cambios sin guardar y presionas Ctrl+Q, el Presentador te avisa y te hace presionarlo de nuevo para salir de verdad:

void WNebulaPresenter::onExit() {
    if (isDirty && !exitWarningShown) {
        exitWarningShown = true;
        if (auto v = view.lock()) {
            v->showMessage("Unsaved changes! Press Ctrl+Q again to quit.", true);
        }
        return;
    }
    isRunning = false;
    if (auto v = view.lock()) {
        v->exit();
    }
}

Lo que el Presentador puede hacer hasta ahora

En esta etapa, el Presentador recibe todos los eventos de entrada y determina si se trata de una tecla especial o un carácter, gestiona por completo el estado de la aplicación y del documento, y mantiene el Modelo y la Vista sincronizados. Es el pegamento entre ambos y, gracias a MVP, se puede probar de forma independiente.

Lo que sigue

En la Parte 3 hablaré de por qué elegí FTXUI en lugar de ncurses y de lo que ofrece de fábrica que hizo más fácil construir la capa de la Vista. Puedes ver el proyecto en GitHub.

Building a Terminal Text Editor: The Model (Part 1)

Ilean Monterrubio Jr — Sat, 07 Mar 2026 00:00:00 +0000

The Idea

The idea for wordNebula came from seeing an interview with George R.R. Martin, where he talks about how he writes his books on a really old computer because his preferred word processor can't run on anything new. After finding out that the program is called WordStar, and some minor Googling, I saw it was entirely terminal-based, and thought that idea was novel.

Growing up in the 90s, I went to an elementary school that gave us weekly computer lab time. I got the chance to use 5.25" floppy disks to play text-based games, and later learned to use the Macintosh computers and play the new versions of The Oregon Trail. So I can see how a writer can feel nostalgic and want to keep using a tool — if it's not broken, why change it?

I am also a software engineer who has used Vim and Neovim, and I see why they have such great appeal. Those tools keep improving and staying up to date, and they are great at being distraction-free, keeping the user's focus on the task at hand.

Why Build Another One?

Starting this project, I did a bit of research. Terminal word processors already exist. The open-source one I found is called WordGrinder — it has been around for a while and is written in C and Lua. It is a great project; check it out if you have the time. While terminal word processors are no longer popular, many writers still use them for the limited distraction and focus they offer.

Honestly, I just thought it was something cool to build, and I just wanted something to work on for me. The overall stretch goal is to make wordNebula a full writer's tool — it would format the output for the user based on a config file or similar setup. The idea is that playwrights and screenwriters could fully write without any distraction or worrying about formatting, and novelists could structure their work by chapter. But that is the future; for now, it is a portfolio project that lets me explore terminal UI development, data structures, and architecture patterns in C++.

Choosing an Architecture

For this project, I decided early on to use modern C++ targeting C++20. Before diving into implementation, my first architectural decision was choosing a pattern: Model-View-Controller (MVC), Model-View-Presenter (MVP), or the newer Model-View-ViewModel (MVVM).

Here is a quick comparison:

Aspect	Model-View-Controller	Model-View-Presenter	Model-View-ViewModel
Mediator	Controller	Presenter	ViewModel
View Role	Active, interacts with Model directly	Passive, passes data to Presenter	Passive, data is bound to ViewModel
Data Binding	Manual updates	Manual, Presenter sends to Model	Automatic via data binding
Testability	Low	Good	Best
Separation	Basic	Better	Best
Best For	Small projects	Medium to complex	Large, data-driven UIs

After researching these patterns and studying block diagrams, I picked Model-View-Presenter. The main reason is that it completely separates all three concerns:

The Model is the text buffer. Its only job is maintaining the buffer — storing text, tracking the cursor, and supporting insertions and deletions.
The View handles the UI layout, how the data is displayed, and capturing the user's key inputs, which it passes to the Presenter.
The Presenter is the orchestrator. It receives input from the View, passes text operations to the Model, then requests the updated data from the Model to refresh the View.

All communication flows through the Presenter. This is the main reason the architecture is testable — and while we all know unit tests aren't fun, we understand why they're important.

Getting My Hands Dirty

With the architecture decision made and the clean separation of concerns giving me the ability to work on different parts of the project independently, I started with a simple proof of concept. I implemented a basic Model text buffer that accepts keystrokes and prints to a log file. It wasn't perfect, but it got me to understand the basic structure and play a bit with MVP before committing to the full implementation.

For this I set up what I called a TextBuffer, which was just a string where I added things to it via a simple Presenter and View with ncurses. I had Copilot help me test it, and what I learned was that I should really start the project by implementing the Model first — it is such a critical part of the project, and it prompted me to do more research on how word processors handle their buffers.

The Model: Choosing a Data Structure

I started doing research on text buffers and saw some really appealing ones. One was the Gap Buffer, which I believe Emacs uses. Another was the Piece Table, used by Microsoft Word, and I found a blog from the VS Code team about their usage of it and their findings: Text Buffer Reimplementation.

After observing this and understanding the differences between them, I picked the Gap Buffer for the initial implementation. This decision became clear once I started to define the use cases — since this is a terminal-based UI, users probably won't be highlighting and removing large chunks of text, so undo and redo can be implemented much later. And also a key difference from any modern code editor: we don't need multiple cursors, only a single one where the user can add to the document.

The idea behind a Gap Buffer is straightforward. You have an array with a "gap" of empty space that follows the cursor around. When you type, you drop characters into the gap. When you move the cursor, the gap moves with it. Here is what that looks like:

Before: [H][e][l][l][o][___GAP___][W][o][r][l][d]
                        ^ cursor

Insert ',':
After: [H][e][l][l][o][,][__GAP__][W][o][r][l][d]
                           ^ cursor

The core of the insertion is simple — move the gap to the cursor, make room if needed, and drop the character in:

void GapBuffer::insertChar(char c) {
    moveGapToCursor();

    if (getGapSize() < 1) {
        expandGap();
    }

    buffer[gapStart] = c;
    gapStart++;
    cursor++;
}

It was also key to use interface abstract classes to make sure I could update the buffer if I ever make a new implementation. This was very important to me because moving into the future we might need flexibility — being able to add undo/redo, or add styling. I was so unsure early on that I thought having that flexibility was very important to have.

The IBuffer interface defines the full contract that any buffer must fulfill. Here is a trimmed version showing the method signatures:

class IBuffer {
  public:
    virtual ~IBuffer() = default;

    // Text Operations
    virtual void insertChar(char c) = 0;
    virtual void insertText(const std::string &text) = 0;
    virtual void deleteChar() = 0;
    virtual void deleteForward() = 0;

    // Text Access
    virtual std::string getText() const = 0;
    virtual std::string getTextRange(int start, int length) const = 0;
    virtual int getLength() const = 0;

    // Cursor Management
    virtual int getCursorPosition() const = 0;
    virtual void setCursorPosition(int position) = 0;
    virtual void moveCursor(int offset) = 0;

    // Smart Navigation
    virtual int findNextWordBoundary(int fromPos) const = 0;
    virtual int findPrevWordBoundary(int fromPos) const = 0;
    virtual int findNextParagraph(int fromPos) const = 0;
    virtual int findPrevParagraph(int fromPos) const = 0;

    // Statistics
    virtual int getWordCount() const = 0;
    virtual int getParagraphCount() const = 0;
};

With this interface, if I ever need to swap in a Piece Table for advanced undo/redo support down the road, I can do it without rewriting the Presenter or View. The full interface with detailed Doxygen documentation is in the repository.

What the Model Can Do So Far

The Model can fully add text at the cursor position, and the gap can grow dynamically. It supports full cursor navigation, text insertion and deletion, word count, and paragraph count. It also has a comprehensive test suite with Google Test. The Model stands on its own — it was built and tested before the Presenter or View ever existed.

What's Next

In Part 2 I will go over the Presenter, which takes the Model and orchestrates everything — coordinating between the buffer and the UI, and managing application state. The Presenter and View are already implemented; you can check out the project on GitHub.

Construyendo un editor de texto de terminal: el Modelo (Parte 1)

Ilean Monterrubio Jr — Sat, 07 Mar 2026 00:00:00 +0000

La idea

La idea de wordNebula surgió al ver una entrevista con George R.R. Martin, donde cuenta cómo escribe sus libros en una computadora muy vieja porque su procesador de texto preferido no corre en nada nuevo. Después de enterarme de que el programa se llama WordStar, y de googlear un poco, vi que era completamente basado en terminal, y me pareció una idea original.

Al crecer en los 90, fui a una primaria que nos daba tiempo semanal en el laboratorio de cómputo. Tuve la oportunidad de usar disquetes de 5.25" para jugar juegos basados en texto, y más adelante aprendí a usar las computadoras Macintosh y a jugar las nuevas versiones de The Oregon Trail. Así que entiendo cómo un escritor puede sentirse nostálgico y querer seguir usando una herramienta: si no está roto, ¿para qué cambiarlo?

También soy ingeniero de software y he usado Vim y Neovim, y entiendo por qué tienen tanto atractivo. Esas herramientas siguen mejorando y manteniéndose al día, y son excelentes para trabajar sin distracciones, manteniendo la atención del usuario en la tarea que tiene enfrente.

¿Por qué construir otro?

Al empezar este proyecto investigué un poco. Los procesadores de texto de terminal ya existen. El de código abierto que encontré se llama WordGrinder; lleva un buen tiempo por ahí y está escrito en C y Lua. Es un gran proyecto; échale un vistazo si tienes tiempo. Aunque los procesadores de texto de terminal ya no son populares, muchos escritores todavía los usan por la poca distracción y el enfoque que ofrecen.

Honestamente, solo me pareció algo padre de construir, y quería algo en lo que trabajar para mí. La meta ambiciosa a largo plazo es convertir a wordNebula en una herramienta completa para escritores: daría formato a la salida según un archivo de configuración o algo similar. La idea es que dramaturgos y guionistas pudieran escribir por completo sin ninguna distracción ni preocuparse por el formato, y que los novelistas pudieran estructurar su trabajo por capítulos. Pero eso es a futuro; por ahora es un proyecto de portafolio que me permite explorar el desarrollo de interfaces de terminal, las estructuras de datos y los patrones de arquitectura en C++.

Eligiendo una arquitectura

Para este proyecto decidí desde el principio usar C++ moderno apuntando a C++20. Antes de meterme de lleno en la implementación, mi primera decisión de arquitectura fue elegir un patrón: Modelo-Vista-Controlador (MVC), Modelo-Vista-Presentador (MVP) o el más nuevo Modelo-Vista-ViewModel (MVVM).

Aquí va una comparación rápida:

Aspecto	Modelo-Vista-Controlador	Modelo-Vista-Presentador	Modelo-Vista-ViewModel
Mediador	Controlador	Presentador	ViewModel
Rol de la Vista	Activa, interactúa directamente con el Modelo	Pasiva, pasa los datos al Presentador	Pasiva, los datos se enlazan al ViewModel
Enlace de datos	Actualizaciones manuales	Manual, el Presentador envía al Modelo	Automático mediante data binding
Testeabilidad	Baja	Buena	La mejor
Separación	Básica	Mejor	La mejor
Ideal para	Proyectos pequeños	De medianos a complejos	Interfaces grandes, orientadas a datos

Después de investigar estos patrones y estudiar diagramas de bloques, elegí Modelo-Vista-Presentador. La razón principal es que separa por completo las tres responsabilidades:

El Modelo es el búfer de texto. Su único trabajo es mantener el búfer: almacenar el texto, rastrear el cursor y permitir inserciones y eliminaciones.
La Vista se encarga del diseño de la interfaz, de cómo se muestran los datos y de capturar las teclas que presiona el usuario, las cuales pasa al Presentador.
El Presentador es el orquestador. Recibe la entrada de la Vista, pasa las operaciones de texto al Modelo y luego solicita los datos actualizados al Modelo para refrescar la Vista.

Toda la comunicación fluye a través del Presentador. Esta es la razón principal por la que la arquitectura es testeable, y aunque todos sabemos que las pruebas unitarias no son divertidas, entendemos por qué son importantes.

Manos a la obra

Con la decisión de arquitectura tomada y la separación limpia de responsabilidades dándome la posibilidad de trabajar en distintas partes del proyecto de forma independiente, empecé con una prueba de concepto sencilla. Implementé un búfer de texto básico del Modelo que acepta pulsaciones de teclas y las escribe en un archivo de registro. No era perfecto, pero me sirvió para entender la estructura básica y jugar un poco con MVP antes de comprometerme con la implementación completa.

Para esto armé lo que llamé un TextBuffer, que era simplemente una cadena a la que le agregaba cosas mediante un Presentador y una Vista sencillos con ncurses. Dejé que Copilot me ayudara a probarlo, y lo que aprendí fue que en realidad debía empezar el proyecto implementando primero el Modelo: es una parte tan crítica del proyecto que me llevó a investigar más sobre cómo los procesadores de texto manejan sus búferes.

El Modelo: eligiendo una estructura de datos

Empecé a investigar sobre búferes de texto y vi algunos muy atractivos. Uno era el Gap Buffer, que creo que usa Emacs. Otro era la Piece Table, que usa Microsoft Word, y encontré un blog del equipo de VS Code sobre su uso y sus hallazgos: Text Buffer Reimplementation.

Después de observar esto y entender las diferencias entre ellos, elegí el Gap Buffer para la implementación inicial. Esta decisión se aclaró en cuanto empecé a definir los casos de uso: como se trata de una interfaz basada en terminal, lo más probable es que los usuarios no estén seleccionando y eliminando grandes bloques de texto, así que deshacer y rehacer se pueden implementar mucho después. Y otra diferencia clave respecto a cualquier editor de código moderno: no necesitamos múltiples cursores, solo uno con el que el usuario pueda agregar al documento.

La idea detrás de un Gap Buffer es sencilla. Tienes un arreglo con un "hueco" (gap) de espacio vacío que sigue al cursor a todos lados. Cuando escribes, vas soltando caracteres en el hueco. Cuando mueves el cursor, el hueco se mueve con él. Así se ve:

Before: [H][e][l][l][o][___GAP___][W][o][r][l][d]
                        ^ cursor

Insert ',':
After: [H][e][l][l][o][,][__GAP__][W][o][r][l][d]
                           ^ cursor

El núcleo de la inserción es simple: mueve el hueco hacia el cursor, haz espacio si hace falta y suelta el carácter:

void GapBuffer::insertChar(char c) {
    moveGapToCursor();

    if (getGapSize() < 1) {
        expandGap();
    }

    buffer[gapStart] = c;
    gapStart++;
    cursor++;
}

También fue clave usar clases abstractas de interfaz para asegurarme de poder actualizar el búfer si alguna vez hago una nueva implementación. Esto fue muy importante para mí porque de cara al futuro podríamos necesitar flexibilidad: poder agregar deshacer/rehacer o agregar estilos. Al principio estaba tan inseguro que pensé que tener esa flexibilidad era muy importante.

La interfaz IBuffer define el contrato completo que cualquier búfer debe cumplir. Aquí va una versión recortada que muestra las firmas de los métodos:

class IBuffer {
  public:
    virtual ~IBuffer() = default;

    // Text Operations
    virtual void insertChar(char c) = 0;
    virtual void insertText(const std::string &text) = 0;
    virtual void deleteChar() = 0;
    virtual void deleteForward() = 0;

    // Text Access
    virtual std::string getText() const = 0;
    virtual std::string getTextRange(int start, int length) const = 0;
    virtual int getLength() const = 0;

    // Cursor Management
    virtual int getCursorPosition() const = 0;
    virtual void setCursorPosition(int position) = 0;
    virtual void moveCursor(int offset) = 0;

    // Smart Navigation
    virtual int findNextWordBoundary(int fromPos) const = 0;
    virtual int findPrevWordBoundary(int fromPos) const = 0;
    virtual int findNextParagraph(int fromPos) const = 0;
    virtual int findPrevParagraph(int fromPos) const = 0;

    // Statistics
    virtual int getWordCount() const = 0;
    virtual int getParagraphCount() const = 0;
};

Con esta interfaz, si alguna vez necesito cambiar a una Piece Table para soportar deshacer/rehacer avanzado más adelante, puedo hacerlo sin reescribir el Presentador ni la Vista. La interfaz completa con documentación detallada de Doxygen está en el repositorio.

Lo que el Modelo puede hacer hasta ahora

El Modelo puede agregar texto por completo en la posición del cursor, y el hueco puede crecer de forma dinámica. Soporta navegación completa del cursor, inserción y eliminación de texto, conteo de palabras y conteo de párrafos. También tiene un conjunto de pruebas exhaustivo con Google Test. El Modelo se sostiene por sí solo: se construyó y se probó antes de que el Presentador o la Vista siquiera existieran.

Lo que sigue

En la Parte 2 repasaré el Presentador, que toma el Modelo y orquesta todo: coordina entre el búfer y la interfaz, y gestiona el estado de la aplicación. El Presentador y la Vista ya están implementados; puedes ver el proyecto en GitHub.