Modulo:Citazione/man
Questa è la pagina di documentazione per Modulo:Citazione
Modulo Lua per la riproduzione delle funzioni dei vari template {{Cita libro}}, {{Cita web}}, {{Cita news}}, {{Cita pubblicazione}}, {{Cita conferenza}} e {{Cita video}}.
Quelle che seguono sono note tecniche sul funzionamento del modulo. Per le istruzioni su come usarlo per inserire citazioni nelle voci vedi il manuale di {{Cita testo}}.
Sottomoduli
[modifica]- Modulo:Citazione/Configurazione - Contiene le tabelle di configurazione con i nomi dei parametri, i messaggi di errore, i caratteri di separazione...
- Modulo:Citazione/Whitelist - Contiene le tabelle dei parametri accettati dal modulo per poter identificare parametri con un nome errato.
- Modulo:Citazione/Suggerimenti - Contiene una tabella in cui è possile inserire nomi di parametri che vengono sbagliati spesso e suggerire nel messaggio d'errore il nome del parametro corretto.
- Modulo:Citazione/Argomenti - Serve a generare Modulo:Citazione/Whitelist ed è usato una tantum.
Funzioni accessorie
[modifica]Nel seguito per settata si intende una variabile diversa da nil e da stringa nulla
- is_set(var)
- vera se una variabile è settata
- first_set(...)
- ritorna la prima variabile settata
- inArray( needle, haystack )
- scandisce l'array haystack e ritorna la posizione in cui si trova il valore needle. Se needle non si trova in haystack o è nil ritorna false
- substitute( msg, args )
- ritorna la stringa msg compilata usando la tabella di valori args. Basata sulla funzione
mw.message.newRawMessage
, non granchè documentata, apparentemente nella stringa i$n
vengono sostituiti dal valore in posizione ennesima in args. Se args è nil ritorna nil - wrap( key, str, lower )
- formatta il messaggio key con la stringa str. key deve essere un indice della tabella citation_config.messages. Se lower è vero il messaggio viene messo in minuscolo prima di inserire str
- debug_msg(msg)
- inserisce un messaggio di debug nella coda dei messaggi di errore per essere emesso a video
- debug_value(name, value)
- inserisce il messaggio di debug name = value. Usata per emettere il valore di una variabile, da usare per esempio come debug_value('name', name)
- argument_wrapper( args )
- restituisce una tabella per accedere ai valori della tabella originale args mediante una tabella di alias. Data l'istruzione
A=argument_wrapper(args)
la chiamataA[key]
il valoreargs[first_set(citation_config.aliases[key])]
. Questo permette la localizzazione dei parametri e la creazione di alias per lo stesso valore. Per esempio secitation_config.aliases['Chapter'] = {'capitolo', 'contributo', 'voce', 'articolo', 'sezione' }
la chiamataA['Chapter']
resituirà uno dei valori settati traargs['capitolo']
,args['contributo']
,args['voce']
,args['articolo']
,args['sezione']
. Aggiunge inoltre il metodo A:ORIGIN che restituisce l'alias con il quale è stato trovato un valore. I valori trovati vengono bufferizzati in una tabella interna. - Aggiunge un messaggio alla coda di errori se:
- key non è presente in citation_config.aliases
- key è una tabella di valori e più di uno di questi è settato
- se in args non viene trovato alcun valore corrispondente a uno degli alias di key ritorna stringa vuota ""
- validate(name)
- ritorna
true
se name non è nil ed è il nome di un parametro accettato,false
in caso contrario - errorcomment( content, hidden )
- formatta il commento comment per la visualizzazione, se hidden è
true
il codice sarà inserito ma non visibile salvo analizzare il codice html della pagina, altrimenti sarà formattato come da settaggio delle classi "error" e "citation-comment" nel css (normalmente una scritta in rosso) - seterror( error_id, arguments, raw, prefix, suffix )
- formatta il commento con codice error_id con la tabella di argomenti arguments. Se valorizzati prefix e suffix vengono aggiunti rispettivamente prima e dopo il messggio. Se raw è
true
il messaggio viene ritornato senza essere passato prima per errorcomment. - la chiave error_id fa riferimento alla tabella di messaggi citation_config.error_conditions che per ogni codice di errore restituisce il messaggio da formattare, la categoria di errore in cui inserire la voce e se il messaggio deve essere visibile o nascosto.
Fragment
[modifica]Per gestire l'unione dei pezzi di citazione, viene definito un "oggetto" Lua (in realtà una tabella con una metatable che definisce alcuni metodi aggiuntivi). Un fragment è composto da un array il cui primo elemento è un stringa da inserire all'inizio della sequenza, seguito da uno o più stringhe e terminati da una stringa da inserire al termine della sequenza. Quando due frammenti f1 e f2 vengono uniti (vedi fragment.append e fragment.appends) viene valutata la priorità dell'ultimo separatore di f1 e quella del primo di f2 e conservato solo quello con priorità maggiore. Il nuovo frammento avrà il separatore iniziale di f1 e quello finale di f2.
- Fragment.new(text, sep_key)
- crea un pseudooggetto Lua che memorizza l'array di stringhe text usando come separatore tra una stringa e l'altra sep_key. Setta come separatore iniziale per la sequenza la stringa nulla e come separatore finale sep_key. Ritorna l'oggetto creato.
- Sep_key deve essere una chiave della tabella Fragment.priority che per ogni separatore indica la sua priorità (quindi quale separatore prevale quando due frammenti vengono uniti) e cosa inserire esattamente (per esempio per "," inserisce in realtà ", " — aggiunge cioè lo spazio). La tabella è caricata dal modulo di configurazione, un esempio è:
[""] = { order=0, sep = ""},
[" "] = { order=1, sep = " "},
[","] = { order=2, sep = ", "},
["."] = { order=3, sep = ". "},
["in"] = {order=4, sep = " in "},
[" "] = { order=5, sep = " "},
spazio semplice che però prevale su altri separatori["nothing"] = {order=6, sep="" }
stringa nulla che prevale su tutto (per forzare nessun separatore a inizio citazione)
- Fragment:start(sep_key)
- setta come separatore iniziale sep_key
- Fragment:last(sep_key)
- setta come separatore finale sep_key
- Fragment:empy(sep_key)
- ritorna
true
se fragment è un frammento vuoto (contiene un array di stringhe vuoto) - Fragment:append(txr)
- appende il frammento o strigna txr in fondo a fragment (nel caso che txr è una stringa la trasforma in fragment con sep_key uguale a quella del frammento a cui viene appesa)
- Fragment:appends(txr)
- appende un array misto di frammenti/stringhe