Leggere l’output in queste pagine
La maggior parte delle pagine di questa sezione ti mostra l’output oltre all’input: un file che la build ha scritto sotto dist/, il testo che la build ha stampato nel tuo terminale, o ciò che uno strumento come tofu ha stampato quando lo hai eseguito su ciò che la build ha scritto.
Quei blocchi sono copiati da un’esecuzione reale, non scritti a mano. Esegui tu stesso la build dell’esempio e potrai confrontare il tuo output con la pagina riga per riga.
Quel confronto è il motivo per cui l’output è qui. Diverse di queste pagine ti chiedono di cambiare una riga e ripetere la build, oppure di eliminare un file renderizzato ed eseguire di nuovo lo strumento, e poi di leggere la differenza. Vale la pena di seguire un’istruzione del genere solo se il blocco con cui fai il confronto è esatto — altrimenti non hai modo di distinguere una differenza che la pagina intendeva farti trovare da una che semplicemente non ha mai menzionato.
Quindi un blocco che mostra l’output si trova sempre in uno di due stati, e mai in una via di mezzo.
Completo
Il blocco mostra per intero ciò che la pagina ha nominato. Quando il testo introduttivo dice il servizio web, ogni riga di quel servizio è presente. Quando nomina un file, è presente l’intero file.
Un estratto, segnato nel punto dell’omissione
L’output reale è spesso lungo, e stamparlo tutto seppellirebbe l’unica riga che una pagina sta insegnando. Dove delle righe sono omesse, il blocco lo dice, su una riga a sé, nel punto in cui sono state omesse:
[… omitted: what was left out]Ecco come si presenta nell’uso. Questo è un piano per l’esempio terraform-declared-sensitivity, in cui ciò che si vuole mostrare riguarda un solo attributo:
# module.store.terraform_data.reference will be created + resource "terraform_data" "reference" { [… omitted: an id attribute, reported as known only after apply] + input = (sensitive value) [… omitted: an output attribute, reported as known only after apply] + triggers_replace = [ + "app-artifacts", + "AKIAEXAMPLE0001", ] }Il tuo piano conterrà quei due attributi. Il marcatore è il modo in cui sai che vi appartengono — che sono righe che la pagina ha scelto di non ristampare, e non qualcosa che la tua build ha fatto diversamente. Un marcatore si trova in ogni punto in cui sono state tolte delle righe, così la loro posizione è leggibile quanto la loro assenza.
Il marcatore dice sempre che cosa è stato tolto, mai soltanto che qualcosa lo è stato. «Un attributo id, segnalato come noto solo dopo l’apply» ti dice abbastanza per riconoscere la riga quando la incontri; dei semplici puntini di sospensione no.
Le parentesi quadre sono intenzionali. Una riga che inizia con [… non è contenuto valido in YAML, HCL, JSON o in nessuno degli altri formati che queste pagine stampano, e nessuno degli strumenti mostrati qui ne stampa una. Quindi una riga del genere è sempre la pagina che parla, mai qualcosa prodotto dalla build — non può essere né scambiata per output né sfuggire a una lettura veloce.
Che cosa non è un’omissione
Quattro cose cambiano l’aspetto di un blocco senza tralasciare nulla, e nessuna di esse richiede un marcatore:
- Nominare una porzione più ristretta. Una pagina che dice «il servizio
web» e poi mostra quel servizio non ha tralasciato nulla di ciò che ha nominato. Il resto del file è al di fuori della porzione, non ne manca. - Indentazione. Un frammento estratto da una struttura profondamente annidata viene di solito mostrato a partire dal margine sinistro, così si legge da solo. Le righe sono quelle emesse; sono cambiati solo gli spazi iniziali.
- Una didascalia o una nota. Una riga
#che nomina il file da cui provengono le righe, o una breve nota accanto a un valore, è visibilmente la pagina che parla e non la build. - Un
#su ogni riga di un messaggio citato. Dove una pagina mostra in un unico blocco un comando e il messaggio che ha stampato, il messaggio è commentato così che l’intero blocco resti eseguibile. Una singola riga stampata lunga può essere spezzata su più righe#per restare leggibile a questa larghezza. In entrambi i casi le parole sono quelle stampate, nell’ordine in cui sono state stampate.
Il marcatore esiste per l’unico caso che altrimenti non potresti rilevare: righe che semplicemente non ci sono.
Un blocco che illustra anziché riprodurre
Alcune pagine qui sono percorsi guidati scritti anziché workspace di cui puoi eseguire la build, e una o due mostrano la struttura di un payload anziché una sua esecuzione particolare. Un blocco del genere non contiene alcuna promessa con cui tu possa fare un diff, quindi lo dice nelle parole che lo circondano — non prende mai silenziosamente il posto della cosa reale. Se un blocco non lo dice, è stato copiato da un’esecuzione e gli si applicano i due stati descritti sopra.
Se adatti una di queste pagine
Mantieni gli stessi due stati. Quando l’output cambia — perché hai modificato l’esempio, o perché una versione più recente lo renderizza diversamente — sostituisci il blocco a partire da un’esecuzione reale anziché modificarlo a mano, e segna le righe che tralasci. Un blocco modificato per sembrare corretto è proprio ciò che questa convenzione intende evitare, perché si legge esattamente come un blocco che è stato verificato.