Personalizzare i messaggi di Mercurial

Giulio@766: Giulio@777: Giulio@777: Personalizzare i messaggi di Mercurial Giulio@777: gpiancastelli@853: Mercurial vi offre un potente meccanismo basato sui template (letteralmente, modelli) per controllare il modo in cui visualizza le informazioni. Potete usare i template per generare una specifica presentazione dei risultati di un singolo comando, o per personalizzare l’intero aspetto dell’interfaccia web predefinita. Giulio@766: Giulio@766: Giulio@803: Usare gli stili di formattazione già pronti Giulio@803: Giulio@803: Mercurial include alcuni stili di formattazione che potete usare immediatamente. Uno stile è semplicemente un template già pronto che qualcuno ha scritto e installato in una posizione nota a Mercurial. Giulio@777: gpiancastelli@853: Prima di dare un’occhiata agli stili distribuiti con Mercurial, rivediamo il normale risultato di un suo comando. Giulio@766: Giulio@766: &interaction.template.simple.normal; Giulio@766: Giulio@777: Questo messaggio ci dà alcune informazioni, ma porta via molto spazio&emdash;cinque righe per ogni changeset. Lo stile compact riduce questo spazio a tre righe, presentate in maniera sparsa. Giulio@766: Giulio@766: &interaction.template.simple.compact; Giulio@766: gpiancastelli@853: Lo stile changelog ci dà un’idea di quale sia il potere espressivo del motore di template di Mercurial. Questo stile tenta di seguire le linee guida per la formattazione di un registro dei cambiamenti stabilite dal progetto GNU . Giulio@766: Giulio@766: &interaction.template.simple.changelog; Giulio@766: Giulio@803: Non vi sorprenderà sapere che lo stile di formattazione predefinito di Mercurial è chiamato default. Giulio@766: Giulio@766: Giulio@766: Impostare uno stile predefinito Giulio@766: Giulio@803: Potete modificare lo stile di formattazione che Mercurial userà per ogni comando aggiungendo al vostro file ~/.hgrc il nome dello stile che preferireste usare. Giulio@766: Giulio@766: [ui] Giulio@766: style = compact Giulio@766: Giulio@803: Se create un vostro stile, potete usarlo inserendo il percorso del vostro file di stile, oppure copiando il vostro file di stile in un luogo dove Mercurial possa trovarlo (tipicamente la sottodirectory templates della vostra directory di installazione di Mercurial). Giulio@766: Giulio@766: Giulio@766: Giulio@766: Giulio@766: Comandi che supportano stili e template Giulio@766: Giulio@777: Tutti i comandi Mercurial di tipo log vi permettono di usare stili e template: hg incoming, hg log, hg outgoing e hg tip. Giulio@777: gpiancastelli@840: Al momento di scrivere questo manuale, quelli elencati sono i comandi che finora supportano stili e template. Dato che questi sono i comandi più importanti per i quali è necessaria una formattazione personalizzabile, la comunità utenti di Mercurial non ha fatto molta pressione per aggiungere il supporto per stili e template ad altri comandi. Giulio@766: Giulio@766: Giulio@766: Giulio@766: Nozioni di base sui template Giulio@766: Giulio@777: Nella sua forma più semplice, un template Mercurial è un frammento di testo. Parte del testo non cambia mai, mentre altre parti vengono espanse, cioè sostituite con nuovo testo, quando è necessario. Giulio@777: gpiancastelli@853: Prima di continuare, diamo un’altra occhiata al semplice esempio del normale risultato di un comando Mercurial. Giulio@766: Giulio@766: &interaction.template.simple.normal; Giulio@766: Giulio@777: Ora, eseguiamo lo stesso comando, ma usando un template per cambiare il messaggio visualizzato. Giulio@766: Giulio@766: &interaction.template.simple.simplest; Giulio@766: gpiancastelli@853: Questo esempio illustra il template più semplice possibile, composto solo da un messaggio di testo statico stampato una volta per ogni changeset. L’opzione del comando hg log dice a Mercurial di usare il testo dato come template per stampare ogni changeset. gpiancastelli@853: gpiancastelli@853: Notate che la stringa di template appena usata termina con il testo \n. Questa è una sequenza di escape che dice a Mercurial di stampare una carattere di nuova riga alla fine di ogni elemento di template. Se omettete questa nuova riga, Mercurial mostrerà un messaggio di testo di seguito all’altro. Leggete la per maggiori dettagli sulle sequenze di escape. gpiancastelli@853: gpiancastelli@853: Un template che stampa una stringa di testo fissa tutte le volte non è molto utile, perciò proviamo qualcosa di un po’ più complesso. Giulio@766: Giulio@766: &interaction.template.simple.simplesub; Giulio@766: gpiancastelli@853: Come potete vedere, la stringa {desc} nel template è stata sostituita con la descrizione di ogni changeset nel messaggio. Ogni volta che Mercurial trova un testo racchiuso tra parentesi graffe ({ e }), proverà a sostituire le parentesi e il testo con l’espansione di qualunque cosa vi sia contenuta. Per stampare una parentesi graffa letterale dovete effettuarne l’escape, come descritto nella . Giulio@766: Giulio@766: Giulio@766: Giulio@766: Parole chiave comuni nei template Giulio@766: Giulio@766: Potete cominciare immediatamente a scrivere semplici template usando le seguenti parole chiave. Giulio@766: Giulio@766: gpiancastelli@853: author: stringa. Il nome non modificato dell’autore del changeset. Giulio@766: Giulio@803: branches: stringa. Il nome del ramo su cui il changeset è stato inserito. Sarà vuoto se il nome del ramo è default. Giulio@766: gpiancastelli@853: date: informazioni di data. La data in cui il changeset è stato inserito. Questa informazione non è rappresentata in maniera comprensibile, bensì dovete passarla attraverso un filtro per presentarla in maniera appropriata. Leggete la per maggiori informazioni sui filtri. La data viene espressa come una coppia di numeri. Il primo numero è una marcatura temporale che segue l’UTC Unix (e indica il numero di secondi trascorsi dal 1° gennaio 1970); il secondo è la differenza tra il fuso orario dell’autore del commit e l’UTC, espressa in secondi. Giulio@766: Giulio@766: desc: stringa. Il testo della descrizione del changeset. Giulio@766: Giulio@766: files: lista di stringhe. Tutti i file modificati, aggiunti, o rimossi da questo changeset. Giulio@766: Giulio@766: file_adds: lista di stringhe. I file aggiunti da questo changeset. Giulio@766: Giulio@766: file_dels: lista di stringhe. I file rimossi da questo changeset. Giulio@766: gpiancastelli@853: node: stringa. L’hash di identificazione del changeset, sotto forma di una stringa esadecimale di 40 caratteri. Giulio@766: Giulio@766: parents: lista di stringhe. I genitori del changeset. Giulio@766: Giulio@766: rev: intero. Il numero di revisione del changeset locale per il repository. Giulio@766: Giulio@766: tags: lista di stringhe. Qualsiasi etichetta associata al changeset. Giulio@766: Giulio@766: Giulio@766: Giulio@766: Alcuni semplici esperimenti ci mostreranno cosa aspettarci quando usiamo queste parole chiave. Potete vederne i risultati qui di seguito. Giulio@766: Giulio@766: &interaction.template.simple.keywords; Giulio@766: gpiancastelli@853: Come abbiamo notato prima, la parola chiave per la data non produce un risultato comprensibile, così dobbiamo trattarla in maniera speciale. Questo implica l’uso dei filtri, che verranno trattati in maniera più approfondita nella . Giulio@766: Giulio@766: &interaction.template.simple.datekeyword; Giulio@766: Giulio@766: Giulio@766: Giulio@766: Sequenze di escape Giulio@766: Giulio@777: Il motore di template di Mercurial riconosce le sequenze di escape più comunemente usate nelle stringhe. Quando trova un carattere di backslash (\), esamina il carattere successivo e rimpiazza i due caratteri con un unico sostituto, come descritto qui di seguito. Giulio@766: Giulio@766: gpiancastelli@840: \\: Giulio@813: backslash, \, corrispondente al codice ASCII 134. Giulio@813: Giulio@813: \n: nuova riga, codice ASCII 12. Giulio@813: Giulio@813: \r: ritorno a capo, codice ASCII 15. Giulio@813: Giulio@813: \t: tabulazione, codice ASCII 11. Giulio@813: Giulio@813: \v: tabulazione verticale, codice ASCII 13. Giulio@813: Giulio@813: \{: parentesi graffa aperta, {, codice ASCII 173. Giulio@813: Giulio@813: \}: parentesi graffa chusa, }, codice ASCII 175. Giulio@766: Giulio@766: gpiancastelli@853: Come appena indicato, se volete che l’espansione di un template contenga un carattere \, {, o { letterale, dovete effettuarne l’escape. Giulio@766: Giulio@766: Giulio@766: Giulio@766: Filtrare le parole chiave per modificarne i risultati Giulio@766: gpiancastelli@853: Alcuni dei risultati dell’espansione dei template non sono immediatamente facili da usare. Mercurial vi permette di specificare una catena opzionale di filtri per modificare il risultato dell’espansione di una parola chiave. Avete già visto in azione un filtro comune, isodate, usato precedentemente per rendere leggibile una data. gpiancastelli@853: gpiancastelli@853: Qui di seguito viene presentata una lista dei filtri più comunemente usati che Mercurial supporta. Mentre alcuni filtri possono essere applicati a qualunque testo, altri possono essere usati solo in circostanze specifiche. Il nome di ogni filtro è seguito prima da un’indicazione del contesto in cui può essere usato e poi da una descrizione dei suoi effetti. Giulio@766: Giulio@766: gpiancastelli@853: addbreaks: qualunque testo. Aggiunge un elemento XHTML <br/> prima della fine di ogni riga tranne l’ultima. Per esempio, foo\nbar diventa foo<br/>\nbar. gpiancastelli@853: gpiancastelli@853: age: parola chiave date. Rappresenta l’età della data, relativa all’ora corrente. Produce stringhe come 10 minuti. Giulio@766: Giulio@813: basename: qualunque testo, ma utile soprattutto per la parola chiave files e simili. Tratta il testo come un percorso e restituisce il nome di base. Per esempio, foo/bar/baz diventa baz. Giulio@777: Giulio@777: date: parola chiave date. Presenta una data in un formato simile al comando Unix date, ma includendo il fuso orario. Produce stringhe come Mon Sep 04 15:13:13 2006 -0700. Giulio@766: Giulio@813: domain: qualunque testo, ma utile soprattutto per la parola chiave author. Trova la prima stringa che somiglia a un indirizzo email e ne estrae il componente del dominio. Per esempio, Bryan O'Sullivan <bos@serpentine.com> diventa serpentine.com. Giulio@813: Giulio@813: email: qualunque testo, ma utile soprattutto per la parola chiave author. Estrae la prima stringa che somiglia a un indirizzo email. Per esempio, Bryan O'Sullivan <bos@serpentine.com> diventa bos@serpentine.com. Giulio@813: Giulio@813: escape: qualunque testo. Sostituisce i caratteri speciali XML/XHTML &, < e > con entità XML. Giulio@813: Giulio@813: fill68: qualunque testo. Manda a capo il testo per farlo stare in 68 colonne. Questo filtro è utile da applicare prima di combinarlo con il filtro tabindent, se volete che il testo non esca dai bordi di una finestra di 80 colonne con caratteri a spaziatura fissa. Giulio@813: Giulio@813: fill76: qualunque testo. Manda a capo il testo per farlo stare in 76 colonne. Giulio@813: Giulio@813: firstline: qualunque testo. Produce la prima riga del testo, senza alcun carattere di nuova riga alla fine. Giulio@766: Giulio@766: hgdate: parola chiave date. Rappresenta la data come una coppia di numeri leggibili. Produce una stringa come 1157407993 25200. Giulio@766: Giulio@766: isodate: parola chiave date. Rappresenta una data come stringa di testo in formato ISO 8601. Produce una stringa come 2006-09-04 15:13:13 -0700. Giulio@766: Giulio@813: obfuscate: qualunque testo, ma utile soprattutto per la parola chiave author. Riproduce il testo in ingresso rappresentandolo come una sequenza di entità XML. Questo è utile per impedire ad alcuni programmi particolarmente stupidi utilizzati dagli spammer per raccogliere indirizzi email di copiare i dati destinati a essere visualizzati su schermo. Giulio@813: Giulio@813: person: qualunque testo, ma utile soprattutto per la parola chiave author. Produce il testo che precede un indirizzo email. Per esempio, Bryan O'Sullivan <bos@serpentine.com> diventa Bryan O'Sullivan. Giulio@766: Giulio@766: rfc822date: parola chiave date. Rappresenta una data usando lo stesso formato impiegato nelle intestazioni email. Produce una stringa come Mon, 04 Sep 2006 15:13:13 -0700. Giulio@766: gpiancastelli@848: short: hash di changeset. Produce la forma breve di un hash di changeset, cioè una stringa esadecimale di 12 caratteri. Giulio@766: gpiancastelli@853: shortdate: parola chiave date. Rappresenta l’anno, il mese e il giorno della data. Produce una stringa come 2006-09-04. gpiancastelli@853: gpiancastelli@853: strip: qualunque testo. Rimuove lo spazio bianco all’inizio e alla fine di una stringa. Giulio@813: Giulio@813: tabindent: qualunque testo. Produce il testo, facendo cominciare ogni riga tranne la prima con un carattere di tabulazione. Giulio@813: gpiancastelli@853: urlescape: qualunque testo. Effettua l’escape di tutti i caratteri che sono considerati speciali dai riconoscitori di URL. Per esempio, foo bar diventa foo%20bar. gpiancastelli@853: gpiancastelli@853: user: qualunque testo, ma utile soprattutto per la parola chiave author. Restituisce la porzione dell’utente di un indirizzo email. Per esempio Bryan O'Sullivan <bos@serpentine.com> diventa bos. Giulio@766: Giulio@766: Giulio@766: Giulio@766: &interaction.template.simple.manyfilters; Giulio@766: Giulio@766: gpiancastelli@854: Se provate ad applicare un filtro a un frammento di dati che non può elaborare, Mercurial fallirà e stamperà un’eccezione Python. Per esempio, non è una buona idea provare a utilizzare il testo risultante dall’espansione della parola chiave desc con il filtro isodate. Giulio@766: Giulio@766: Giulio@766: Giulio@766: Combinare i filtri Giulio@766: Giulio@777: È facile combinare filtri per produrre un testo formattato nel modo che preferite. La seguente catena di filtri ripulisce una descrizione, poi si assicura che stia tranquillamente in 68 colonne, infine la indenta ulteriormente di 8 caratteri (almeno sui sistemi di tipo Unix, dove una tabulazione è convenzionalmente larga 8 caratteri). Giulio@766: Giulio@766: &interaction.template.simple.combine; Giulio@766: gpiancastelli@853: Notate l’uso di \t (un carattere di tabulazione) nel template per indentare la prima riga, necessario dato che tabindent indenta tutte le righe tranne la prima. gpiancastelli@853: gpiancastelli@853: Tenete a mente che l’ordine dei filtri in una catena è significativo. Il primo filtro viene applicato al risultato della parola chiave, il secondo al risultato del primo filtro, e così via. Per esempio, usare fill68|tabindent dà risultati molto diversi rispetto a tabindent|fill68. Giulio@766: Giulio@766: Giulio@766: Giulio@766: Giulio@777: Dai template agli stili Giulio@777: Giulio@803: Un template a riga di comando fornisce un modo semplice e veloce per formattare il risultato di un certo comando. Ma i template possono diventare prolissi, quindi è utile essere in grado di dare un nome a un template. Un file di stile è un template con un nome, memorizzato in un file. Giulio@777: gpiancastelli@853: Ma soprattutto, l’impiego di un file di stile sfrutta la potenza del motore di template di Mercurial in modi che non sono possibili usando l’opzione a riga di comando. Giulio@766: Giulio@766: Giulio@766: Il più semplice dei file di stile Giulio@766: Giulio@766: Il nostro semplice file di stile contiene solo una riga: Giulio@766: Giulio@766: &interaction.template.simple.rev; Giulio@766: Giulio@803: Questo dice a Mercurial: se stai stampando un changeset, usa il testo sulla destra come template. Giulio@766: Giulio@766: Giulio@766: Giulio@766: La sintassi dei file di stile Giulio@766: Giulio@766: Le regole della sintassi per un file di stile sono semplici. Giulio@766: Giulio@766: Giulio@766: Il file viene elaborato una riga alla volta. Giulio@766: gpiancastelli@853: Gli spazi bianchi all’inizio e alla fine di una riga vengono ignorati. Giulio@766: Giulio@766: Le righe vuote vengono saltate. Giulio@766: gpiancastelli@853: Se una riga comincia con un carattere # o ;, l’intera riga viene trattata come un commento e saltata come se fosse vuota. Giulio@766: Giulio@777: Una riga comincia con una parola chiave, che deve iniziare con un carattere alfabetico o di sottolineatura e successivamente può contenere qualsiasi carattere alfanumerico o di sottolineatura. (Nella notazione per le espressioni regolari, una parola chiave deve corrispondere a [A-Za-z_][A-Za-z0-9_]*.) Giulio@766: gpiancastelli@853: L’elemento successivo deve essere un carattere =, che può essere preceduto o seguito da una quantità arbitraria di spazio bianco. Giulio@766: Giulio@777: Se il resto della riga comincia e finisce con caratteri corrispettivi di apice o di virgolette, viene trattato come il corpo di un template. Giulio@777: Giulio@777: Se il resto della riga non comincia con caratteri di apice o di virgolette, viene trattato come il nome di un file i cui contenuti saranno letti e usati come il corpo di un template. Giulio@766: Giulio@766: Giulio@766: Giulio@766: Giulio@766: Giulio@766: Esempi di file di stile Giulio@766: Giulio@777: Per illustrare come scrivere un file di stile, ne costruiremo alcuni esempi. Piuttosto che fornire un file di stile completo e ripercorrerlo passo per passo, replicheremo il classico processo di sviluppo di un file di stile cominciando con qualcosa di molto semplice e proseguendo attraverso una serie di esempi successivi più completi. Giulio@766: Giulio@766: Giulio@766: Identificare errori in un file di stile Giulio@766: Giulio@777: Se Mercurial incontra un problema in un file di stile su cui state lavorando, stampa uno stringato messaggio di errore che si rivela in effetti piuttosto utile una volta scoperto cosa significa. Giulio@766: Giulio@766: &interaction.template.svnstyle.syntax.input; Giulio@766: Giulio@803: Notate che stile.errato tenta di definire una parola chiave changeset, ma dimentica di darle un contenuto qualsiasi. Quando gli si chiede di usare questo file di stile, Mercurial si lamenta prontamente. Giulio@766: Giulio@766: &interaction.template.svnstyle.syntax.error; Giulio@766: Giulio@766: Questo messaggio di errore sembra minaccioso, ma non è troppo difficile da seguire. Giulio@766: Giulio@766: Giulio@777: Il primo componente è semplicemente il modo in cui Mercurial dice rinuncio. Giulio@803: ___fallimento___: stile.errato:1: errore di riconoscimento Giulio@766: gpiancastelli@853: Subito dopo, trovate il nome del file di stile che contiene l’errore. Giulio@803: fallimento: ___stile.errato___:1: errore di riconoscimento Giulio@766: gpiancastelli@853: Il nome del file è seguito dal numero di riga dove l’errore è stato incontrato. Giulio@803: fallimento: stile.errato:___1___: errore di riconoscimento Giulio@766: Giulio@766: Infine, viene fornita una descrizione di quello che è andato storto. Giulio@803: fallimento: stile.errato:1: ___errore di riconoscimento___ gpiancastelli@853: La descrizione del problema non è sempre chiara (come in questo caso) ma, anche quando è criptica, è quasi sempre banale trovare la causa dell’errore inspezionando visivamente la riga del file di stile che contiene il problema. Giulio@766: Giulio@766: Giulio@766: Giulio@766: Giulio@766: Giulio@766: Identificare univocamente un repository Giulio@766: Giulio@766: Se volete essere in grado di identificare un repository Mercurial in maniera abbastanza univoca usando una breve stringa come identificatore, potete usare la prima revisione contenuta nel repository. Giulio@766: Giulio@766: &interaction.template.svnstyle.id; Giulio@766: Giulio@777: È molto probabile che questo identificatore sia unico, quindi si rivela utile in molti casi. Ci sono alcune avvertenze. Giulio@777: Giulio@777: Questa tecnica non funzionerà in un repository completamente vuoto, perché un tale repository non possiede la revisione zero. Giulio@777: gpiancastelli@853: Questa tecnica non funzionerà nemmeno nel caso (estremamente raro) in cui un repository sia l’unione di due o più repository precedentemente indipendenti e quei repository siano ancora nei paraggi. Giulio@766: Giulio@766: Ecco alcuni usi che potete fare di questo identificatore: Giulio@766: Giulio@803: come chiave nella tabella di un database che gestisce i repository presenti su un server; Giulio@803: gpiancastelli@853: come metà di una tupla {identificatore di repository, identificatore di revisione}. Salvate questa informazione da qualche parte quando eseguite un assemblaggio automatico o un’altra attività simile, in modo che possiate rieseguire lo stesso assemblaggio in seguito se necessario. Giulio@766: Giulio@766: Giulio@766: Giulio@766: Giulio@766: Giulio@766: Elencare file su più righe Giulio@766: Giulio@777: Supponete di voler elencare i file modificati da un changeset uno per riga, aggiungendo una piccola indentazione prima di ogni nome di file. Giulio@766: Giulio@766: &interaction.ch10-multiline.go; Giulio@766: Giulio@766: Giulio@766: Giulio@777: Imitare i messaggi di Subversion Giulio@777: Giulio@777: Proviamo a emulare il formato predefinito usato da un altro strumento di controllo di revisione, Subversion, per mostrare le voci del proprio registro. Giulio@766: Giulio@766: &interaction.template.svnstyle.short; Giulio@766: Giulio@803: Dato che lo stile della rappresentazione di Subversion è abbastanza semplice, è facile copiare e incollare uno dei suoi messaggi in un file e rimpiazzare il testo prodotto da Subversion con i valori di template che vorremmo vedere espansi. Giulio@766: Giulio@766: &interaction.template.svnstyle.template; Giulio@766: Giulio@803: Questo template si discosta in alcuni modi dalla presentazione prodotta da Subversion. Giulio@777: gpiancastelli@853: Subversion stampa una data leggibile (il Wed, 27 Sep 2006 nel risultato dell’esempio precedente) tra parentesi. Il motore di template di Mercurial non fornisce un modo per visualizzare una data in questo formato senza stampare anche l’ora e il fuso orario. Giulio@777: Giulio@777: Emuliamo la stampa di righe separatrici piene di caratteri - da parte di Subversion concludendo il template con una riga di quel tipo. Usiamo la parola chiave header del motore di template per stampare una riga separatrice come prima riga (vedete più avanti), quindi ottenendo un risultato simile a quello di Subversion. Giulio@777: gpiancastelli@853: Il formato di Subversion include nell’intestazione il conteggio del numero di righe del messaggio di commit. Non possiamo replicare questa caratteristica in Mercurial, poiché attualmente il motore di template non fornisce un filtro che conti il numero di righe generate dal template. Giulio@766: Giulio@777: Non mi ci sono voluti più di uno o due minuti di lavoro per sostituire il testo letterale di un esempio del messaggio di Subversion con alcune parole chiave e alcuni filtri per ottenere il template appena visto. Il file di stile fa semplicemente riferimento al template. Giulio@766: Giulio@766: &interaction.template.svnstyle.style; Giulio@766: gpiancastelli@840: Avremmo potuto includere il testo del file di template direttamente nel file di stile, circondandolo con virgolette e rimpiazzando le nuove righe con sequenze \n, ma questo avrebbe reso il file di stile troppo difficile da leggere. La leggibilità è un buon criterio da cui farsi guidare per decidere se un certo testo appartiene a un file di stile o a un file di template a cui il file di stile fa riferimento. Nel caso il file di stile vi sembri troppo grande o disordinato se inserite un frammento letterale di testo, allora spostate il testo in un template. Giulio@766: Giulio@766: Giulio@766: