Modulo:Citazione/man

Da Wikiversità, l'apprendimento libero.
Jump to navigation Jump to search

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 chiamata A[key] il valore args[first_set(citation_config.aliases[key])]. Questo permette la localizzazione dei parametri e la creazione di alias per lo stesso valore. Per esempio se citation_config.aliases['Chapter'] = {'capitolo', 'contributo', 'voce', 'articolo', 'sezione' } la chiamata A['Chapter'] resituirà uno dei valori settati tra args['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