Blocchi (.lnb)

Un bundle di Blocchi è una cartella il cui nome termina in .lnb, trattata come un unico elemento nell'albero (doppio clic apre). Ogni blocco è un file reale su disco; l'ordine vive in un blocks.json nella radice del bundle. Funziona come un quaderno: celle impilate di codice o testo. Un notebook Jupyter entra da qui: clic destro su un .ipynb nell'albero e scegli Importa come Blocchi (.lnb). Ogni cella diventa un file reale — versionabile e letto dalla ricerca —, e il .ipynb resta dov'era, perché importare non è convertire. Gli output salvati nel notebook non arrivano: eseguire la cella qui genera il risultato vero, con istante e comando. Se il blocks.json è illeggibile (un conflitto di Git o una scrittura interrotta), il quaderno avvisa e non lo riscrive: l'ordine, la connessione e la sessione tornano a essere salvati solo dopo che lo hai corretto.

Celle, barra del quaderno e scorciatoie

Ogni cella ha un nome, un pulsante di tipo (markdown, python, javascript, sql, shell, powershell, bat, r, julia, http, ia, mermaid, latex e quelli di testo) e pulsanti per copiare, inserire (clic: sotto; la freccetta: sopra e duplica), eliminare, spostare su e giù ed eseguire (la freccetta offre Esegui fino a qui). La cella nuova eredita il tipo della vicina. Il pulsante a destra comprime la cella, lasciando solo la prima riga nell'intestazione, e il contatore [n] dice l'ordine in cui le celle sono state eseguite in questa sessione. Crea un quaderno dall'albero (Nuovo) o in File → Nuovo.

La barra del quaderno, in alto, agisce sull'intero quaderno: Esegui tutto esegue le celle di codice in ordine; Interrompi ferma quella in corso e svuota la coda (l'esecuzione va nella cronologia con uscita -1); Pulisci output chiude i pannelli senza cancellare nulla; il menu Altro esporta il quaderno e cancella la cronologia. La chiave timeoutSec del blocks.json dà un tempo limite per cella (0, il valore predefinito, è senza limite).

Scorciatoie, con il focus nella cella: Ctrl+Invio esegue e resta; Shift+Invio esegue e passa alla successiva (sull'ultima, ne crea una nuova); Alt+Invio esegue e inserisce una cella subito sotto. In una cella di testo, eseguire significa renderizzare: si apre renderizzata quando ha contenuto, e un doppio clic (o Invio su di essa) torna a modificare.

Risultato salvato, allegati e cronologia

Il risultato resta salvato (come in un quaderno di laboratorio): al termine, ogni esecuzione diventa un file .md dentro saida/<cella>/, nel bundle stesso — con l'istante, il codice di uscita, la durata, il comando e l'output. Essendo Markdown, si può leggere in qualsiasi editor, versionare in Git insieme al quaderno e recuperare con la ricerca nelle note. Riaprire il bundle riporta la striscia Ultima esecuzione sopra il pannello: cliccala per vedere il risultato senza eseguire di nuovo.

Allegati: ogni esecuzione riceve una cartella propria, accanto al .md, e il suo percorso arriva al programma nella variabile d'ambiente LN_RUN_DIR. Ciò che la cella scrive lì — un grafico matplotlib, un CSV — appare sotto l'output (le immagini disegnate, il resto come link alla cartella) e viene elencato nel file della cronologia. Un output che è già Markdown (la tabella di una SELECT, la risposta dell'IA, un diagramma) si apre renderizzato; il pulsante Testo/Renderizza della striscia alterna.

Cronologia: il pulsante Cronologia accanto a quella striscia elenca le esecuzioni precedenti di quella cella (istante e codice di uscita) — utile per confrontare ciò che la stessa cella ha restituito nel tempo. Conserviamo le 10 più recenti per cella; per cambiare, modifica la chiave historyLimit nel blocks.json del bundle (0 disattiva il salvataggio, e con esso gli allegati). Un output molto grande viene tagliato (il file dice truncated: true). Rinominare la cella o cambiarne il tipo porta con sé la cronologia; eliminare la cella manda la cronologia nel Cestino.

Sessione persistente

Per impostazione predefinita ogni cella è un processo nuovo: ciò che una definisce, la successiva non lo vede. Con la sessione persistente attiva (pulsante Sessione della barra; la chiave session del blocks.json), le celle Python, JavaScript, shell e PowerShell girano in un processo che resta vivo tra le esecuzioni — variabili, funzioni e import di una cella valgono nelle successive, come in Jupyter. In Python, le figure matplotlib aperte alla fine della cella vengono salvate da sole nella cartella degli allegati. Riavvia sessione dimentica tutto; anche Interrompi, perché interrompere significa terminare il processo. In JavaScript, dichiara con var (o senza dichiarazione): let, const e class al livello superiore non possono essere dichiarati di nuovo — nemmeno rieseguendo la stessa cella.

Celle SQL

Senza una connessione indicata, la cella sql gira nel DuckDB del quaderno stesso (in memoria): le tabelle create in una cella valgono nelle successive, e read_csv('dati/vendite.csv') legge i file della cartella del quaderno — tieni i dati in una sottocartella, perché ogni file sciolto nella cartella del quaderno è una cella. Per un database vero, punta il quaderno a una connessione .lnc dalla striscia di connessione (elenca le connessioni dello spazio di lavoro): le celle passano a girare nel database, con la stessa connessione del pannello Connessioni — password ricordata, tunnel SSH, rilettura del .lnc e la conferma di produzione prima di qualsiasi scrittura. Il risultato di una SELECT diventa una tabella nel file di output; INSERT/UPDATE e simili riportano quante righe sono cambiate, e un errore interrompe lo script e registra l'istruzione fallita. Portiamo fino a 100 righe per query (sqlMaxRows nel blocks.json; il file avvisa quando ce ne sono altre).

@set nome = valore definisce una variabile con ambito di quaderno, e :nome (o ?) è un parametro chiesto all'esecuzione, come nell'editor SQL. L'ultima SELECT scrive anche resultado.csv nella cartella degli allegati (le stesse righe della tabella, fino a sqlMaxRows), e le celle successive ricevono il percorso in LN_LAST_SQL — in Python, pd.read_csv(os.environ["LN_LAST_SQL"]). La connessione resta nel blocks.json come percorso relativo; un .lnc tenuto dentro il bundle conta come configurazione, non diventa cella.

HTTP, IA, Mermaid e LaTeX

Quattro tipi girano dentro LightNote stesso, senza interprete: la cella http è un test .lnh eseguito dallo stesso esecutore del tester di API (il rapporto va nella cronologia; l'ambiente è quello indicato dalla chiave httpEnv del blocks.json, e un file che la richiesta invia deve stare dentro lo spazio di lavoro); la cella ai manda il prompt all'assistente predefinito con il contesto del quaderno — il codice delle celle precedenti e l'ultimo output di ciascuna, tranne le celle http, che possono contenere credenziali —, e la risposta arriva renderizzata; le celle mermaid e latex disegnano il diagramma o la formula in un'immagine negli allegati. Interrompi annulla le prime due.

Esportare il quaderno

Il menu Altro della barra esporta l'intero quaderno: come Markdown (le celle di testo in linea, il codice in recinti con il linguaggio, l'ultimo output subito sotto e le immagini collegate) o come notebook Jupyter (.ipynb, con l'ultimo output di ogni cella e le immagini incorporate; una cella di un altro linguaggio porta il segno che VS Code legge). È una copia da condividere — il quaderno resta la cartella.