serial.h

/**
 * @file serial.h
 * @brief Interfaccia per la gestione dell'I/O su UART con comportamento da terminale
 *
 * Questo file header fornisce le dichiarazioni delle funzioni per la stampa,
 * la lettura formattata e la gestione dell'input da UART con funzioni avanzate
 * di editing linea e visualizzazione simile a un terminale.
 */

#ifndef INC_SERIAL_H_
#define INC_SERIAL_H_

#include "usart.h"
#include "string.h"
#include "stdio.h"
#include "stdarg.h"

/**
 * @brief Stampa una stringa su UART
 *
 * Questa funzione invia una stringa tramite UART, senza aggiungere newline.
 *
 * @param message Stringa da stampare
 */
void serial_print(char *message);

/**
 * @brief Stampa una nuova riga su UART ("\r\n")
 *
 * Invia un carattere di ritorno a capo seguito da newline, simile alla
 * stampa di una nuova riga in un terminale.
 */
void serial_newline(void);

/**
 * @brief Stampa una stringa seguita da una nuova riga
 *
 * Questa funzione invia una stringa tramite UART, seguita automaticamente
 * da un ritorno a capo (`\r\n`).
 *
 * @param message Stringa da stampare
 */
void serial_println(char *message);

/**
 * @brief Stampa una stringa formattata su UART (come printf)
 *
 * Questa funzione invia una stringa formattata tramite UART, simile
 * alla funzione `printf`.
 *
 * @param format Formato della stringa
 * @param ... Argomenti da formattare
 * @return Numero di caratteri scritti
 */
int serial_printf(const char *format, ...);

/**
 * @brief Stampa una stringa formattata seguita da una nuova riga
 *
 * Questa funzione invia una stringa formattata tramite UART, seguita
 * automaticamente da un ritorno a capo (`\r\n`), simile a `printf`.
 *
 * @param format Formato della stringa
 * @param ... Argomenti da formattare
 * @return Numero di caratteri scritti
 */
int serial_printfln(const char *format, ...);

/**
 * @brief Legge una riga da UART con supporto a frecce sinistra/destra e backspace
 *
 * Questa funzione permette la lettura di una riga con un buffer di input,
 * supportando la gestione del backspace per rimuovere i caratteri e
 * la gestione di un terminale che simula il comportamento di frecce sinistra e destra.
 *
 * @param buffer Buffer dove salvare la stringa
 * @param length Lunghezza massima del buffer (incluso null terminator)
 */
void serial_readline(char *buffer, int length);

/**
 * @brief Versione personalizzata di scanf che legge da UART
 *
 * Questa funzione legge una riga tramite `serial_readline()` e converte
 * il formato dell'input con `sscanf()`, simile a come farebbe `scanf()`.
 *
 * @param format Stringa di formato come in scanf
 * @param ... Argomenti variabili da riempire
 * @return Numero di elementi letti con successo
 */
int serial_scanf(const char *format, ...);

/**
 * @brief Pulisce lo schermo del terminale
 *
 * Invia una sequenza di escape per pulire lo schermo del terminale
 * tramite UART, se supportato dal terminale stesso.
 */
void serial_clear(void);

#endif /* INC_SERIAL_H_ */