Emanuele Paolini: hpp: Istruzioni

Hpp è un preprocessore di testi, orientato alla scrittura di documenti HTML.

Comandi

La sintassi per i comandi riconosciuti da HPP assomiglia ai TAG dell'HTML:

<TAG name=value [...] >

Alcuni comandi prevedono un TAG di chiusura che, come in HTML, è dato dal nome del comando preceduto dal carattere '/'. In questo caso la parte di testo compresa tra il TAG di apertura e il TAG di chiusura viene interpretato dal comando. All'interno del blocco di testo di un comando ci possono naturalmente essere "annidiati" altri comandi.

Elenco dei comandi

```
<NOSPACE>
```
Elimina tutti gli spazi (cioè spazio, tab e andata a capo) che seguono il TAG.
```
<IGNORE> testo </IGNORE> 
```
Elimina il testo.
```
<LITERAL> testo </LITERAL> 
```
Inserisce il testo senza espanderlo ulteriormente.
```
<SET name=value[...]>
```
```
<SET name> testo </SET>
```
Nella prima forma setta la variabile name al valore value. Nello stesso TAG possono essere presenti più di un assegnamento. Nella seconda forma setta la variabile (ovvero la macro) name al valore testo.
```
<DEF name> testo </DEF>
```
Questo comando è equivalente al comando SET a parte il fatto che la macro risultante può essere usata direttamente con il comando <name ...> senza dover usare il costrutto <USE name ...>. Inoltre se oltre alla macro name esiste anche la macro /name, quando nel buffer viene trovato il comando <name...>, viene cercato il tag corrispondente </name...>, quindi viene inserito in un nuovo buffer il valore della macro name, il testo compreso tra i due TAG e infine il valore della macro /name. Dunque entrambe le macro vengono espanse nello stesso ambiente, cosicchè anche nell'espansione della seconda macro sono visibili le variabili passate alla prima macro.
```
<USE name arg=value[...]>
```
Copia il valore della variabile (o macro) name in un nuovo buffer, e associa al buffer un nuovo ambiente "figlio" in cui vengono settate le variabili arg ai valori value. Quindi il testo della macro viene espanso e il buffer risultate viene rinserito al posto del TAG.
```
<IF [NOT] expr> testo1 [<ELSE> testo2] </IF>
```
Inserisce nel buffer testo1 se expr è vera, testo2 altrimenti (e se presente). Il testo inserito viene quindi espanso. Se è presente l'opzione NOT il valore di verità viene invertito. expr può essere: name oppure string1=string2. Nel primo caso l'espressione è vera se la variabile name è stata definita. Nel secondo caso vengono confrontate le due stringhe.
```
<FOREACH name [val ... ]> testo </FOREACH>
```
Per ogni elemento val viene creato un nuovo buffer e un nuovo ambiente nel quale la variabile name ha valore val. Quindi testo viene espanso e il contenuto del buffer viene re-inserito al posto del TAG.
```
<ENV [GLOBAL]>
```
Viene inserita nel buffer una lista della forma name=value di tutte le variabili definite nell'ambiente corrente. Se l'opzione GLOBAL è presente, vengono inserite anche le variabili degli ambienti più esterni.
```
<MESSAGE [[MSG=]message] [ERR=error]>
```
Viene riportato sullo stderr il messaggio message o l'errore error. Nel caso di un messaggio di errore il programma termina.
```
<FILE [LITERAL] INPUT[=filename]>
<FILE OUTPUT[=filename]>
```
Nel primo caso viene inserito nel buffer corrente il contenuto del file filename. Se filename non viene specificato, viene letto lo stdin. Se il primo carattere di filename è il carattere '|', viene eseguito filename e viene inserito il suo output. In ogni caso il testo appena inserito viene espanso a meno che non sia presente l'attributo LITERAL. Nel secondo caso il contenuto del buffer corrente viene salvato sul file filename. Viene usato stdout o l'input di un programma in analogia col caso precedente. Il buffer salvato viene poi cancellato.
```
<STAT [PATH BASE EXT MIN MAX
FILE=filename DATE FORMAT=format SIZE DIM] >
```
Vengono inserite nel buffer alcune informazioni sul file filename. Se non viene indicato il nome del file, si considera il file sorgente &SourceFile;. Le opzioni PATH BASE EXT specificano quali parti del nome del file devono essere stampate (rispettivamente il path, il nome e l'estensione), mentre MIN MAX indicano se l'estensione deve essere considerata a partire dall'ultimo '.' o dal primo. L'opzione DATE indica che la data di ultima modifica del file dev'essere stampata. Se l'opzione FILE non viene messa, viene stampata la data corrente. L'opzione FORMAT serve per specificare il formato di visualizzazione di data e ora, come specificato nelle man-pages del comando strftime. L'opzione SIZE stampa la dimensione in bytes del file.
```
<CLEAR>
```
Tutto il buffer corrente viene cancellato.
```
<PROCESS> testo </PROCESS>
```
Viene creato un nuovo buffer con un nuovo ambiente. In questo buffer viene copiato testo e viene quindi espanso. Se dopo l'espansione il buffer non risulta vuoto, viene generato un messaggio di avvertimento e comunque il buffer viene distrutto.

Regole di espansione

L'espansione del testo avviene solamente all'occorrenza di uno dei caratteri '<', '&' e '$'. Nel caso del carattere '<', il preprocessore, dopo aver saltato eventuali spazi bianchi, legge un nome, cioè una sequenza di caratteri alfanumerici, con in aggiunta i caratteri '/', '_' e '-'. Se il nome risultante corrisponde ad un comando interno o al nome di una macro definita con DEF, si procede all'espansione delle opzioni del comando o della macro, altrimenti il testo viene lasciato così com'è. Le opzioni sono separate da spazi, e sono formate da un nome e opzionalmente un carattere '=' seguito da una stringa. Le stringhe sono sequenze di caratteri alfanumerici. Se però in una stringa è presente uno dei caratteri '<','&' o '$', tale carattere viene espanso a sua volta. Se in una stringa compare un carattere '"', i successivi caratteri vengono tutti inseriti nella stringa (anche se non alfanumerici) fino al successivo '"'. Se all'interno di una stringa "quotata" compare il carattere '\', il carattere successivo viene inserito senza essere interpretato in alcun modo.

Anche nel caso del carattere '&' il preprocessore legge un nome, che deve terminare con un carattere ';'. Se il nome corrisponde al nome di una variabile, il valore della variabile viene inserito altrimenti il testo non viene modificato. Il carattere '$' precede anch'esso il nome di una variabile. Il nome in questo caso può essere racchiuso tra parentesi graffe. Viene fatta quindi l'espansione come nel caso di '&'.

Riga di comando e file di configurazione

Quando viene eseguito, Hpp crea il buffer principale e l'ambiente principale. Le opzioni date nella riga di comando vengono quindi interpretate in due possibili modi: se sono assegnamenti del tipo var=value, viene creata nell'ambiente principale la variabile var con valore value. Le altre opzioni vengono interpretate come nomi di files, che vengono memorizzati, separati da spazi, nella variabile &SourceFileList;. A questo punto viene cercato un file da inserire nel buffer che usando i comandi del preprocessore si dovrà prendere la responsabilità di caricare in successione i files indicati nella riga di comando (probabilmente mediante un <FOREACH file &SourceFileList >. Prima di tutto viene cercato un file chiamato ".hpp" nella directory corrente, se questo non esiste viene caricato il file "~/.hpp", se neanche questo esiste viene inserito il seguente buffer di default:

<if sourcefilelist>
<foreach SourceFile $sourcefilelist>
<process>
<set OutputFile=<stat base file=$sourceFile>.html>
<message \"Processing SourceFile \"$SourceFile>
<input $SourceFile>
<message \"   ----> \"$OutputFile>
<output $OutputFile>
</process>
</foreach>
<else>
<message>
No files specified.
try: hpp <hpp-files>
</message>
<output>
</if>