Binary Variables

Indice

Archiviazione dati

Binary variables sono una forma speciale di archiviazione offerta da mIRC che può contenere un array di byte di lunghezza arbitraria.

Contenuto

Panoramica

Le &variables binarie di mIRC si distinguono dalle sue %variables testuali perché iniziano con il simbolo & (e commerciale), mentre le variabili di testo iniziano con il simbolo % (percentuale). Differiscono dalle variabili testuali per contenuto, scope, durata e lunghezza.

Sono composte da valori byte, che possono essere uno qualsiasi dei valori 0-255. Tra le altre differenze, possono contenere il valore $chr(0), cosa che le variabili testuali non possono fare.
Il loro scope è simile a quello degli identificatori locali come $nick e $rawmsg. Esistono finché il motore di scripting è in esecuzione, poi vengono eliminate.
Le variabili binarie non vengono salvate nel file delle variabili, il cui nome predefinito è vars.ini, nel modo in cui vengono salvate le %variables globali. Per conservarle, devi scriverle su disco, salvarle in un elemento di hashtable oppure usare $encode per salvarle in una %variable o in una hashtable.
Mentre le variabili di testo sono limitate in lunghezza dal limite di riga di 4150 caratteri, la lunghezza delle variabili binarie è limitata dalla memoria disponibile.
mIRC non interpreta il contenuto della tua variabile binaria, mentre lo fa per una normale %variable. Per impostazione predefinita una %variable non può essere impostata al valore "" (solo due doppi apici), perché nelle routine interne delle variabili ciò viene interpretato come stringa vuota, come se supportasse le stringhe quotate. Nota che da mIRC 7.52, /var e /set supportano lo switch -p che preserva i dati: "" è ora consentito, tranne se inserito direttamente nella sezione variables dell’editor degli script per ragioni di retrocompatibilità, e anche gli spazi vengono preservati integralmente. Senza -p, /var e /set rimuovono un singolo spazio finale, mentre due o più spazi finali vengono mantenuti. Naturalmente $bvar(&binvar,,).text decodifica il contenuto della tua variabile binaria da utf8, reinterpretando i byte, e questo è corretto.

Alcuni usi delle Binary Variables includono:

contenere dati che non possono essere inseriti in %variables testuali
contenere dati troppo lunghi per essere inseriti in variabili di testo
mostrare spazi duplicati o caratteri non stampabili come TAB, che non possono essere visti nelle stringhe mostrate con echo

/Commands e $Identifiers

Esistono alcuni comandi e identificatori creati specificamente per manipolare le variabili binarie:

/bset — Crea o modifica variabili binarie.
/bcopy — Crea o modifica copiando valori byte tra o dentro variabili binarie.
/breplace — Semplice ricerca/sostituzione di tutte le occorrenze di un valore byte con un altro.
/btrunc — Tronca un file su disco a una dimensione specifica indipendentemente dal contenuto o dal terminatore di riga.
/bunset — Elimina una variabile binaria prima della fine dello script/evento.
/bread — Legge il contenuto di un file dentro una variabile binaria.
/bwrite — Scrive una variabile binaria su un file su disco.
$bfind — Cerca in una variabile binaria un pattern composto da uno o più byte.
$bvar — Mostra il contenuto di variabili binarie come testo o come serie di numeri decimali.

Inoltre, ad altri identificatori è stata aggiunta la possibilità di usare variabili binarie in input o in output:

/parseline — Può usare una variabile binaria come input o output.
$cb — Può inviare una riga o l’intera clipboard in una variabile binaria.
$encode — Può usare una variabile binaria come input e output.
$decode — Può usare una variabile binaria come input e output.
$regsub — Può usare una variabile binaria come output.
$regsubex — Può usare una variabile binaria come output.
$compress — Può usare una variabile binaria come input e output.
$decompress — Può usare una variabile binaria come input e output.
/hadd — Può salvare una variabile binaria in un elemento di hashtable.
$hget — Può usare una variabile binaria come output.
/hsave — Può salvare una hashtable in un file binario.
/hload — Può caricare un file binario in una hashtable.
$crc — Può usare una variabile binaria come input.
$md5 — Può usare una variabile binaria come input.
$sha1 — Può usare una variabile binaria come input.
$sha256 — Può usare una variabile binaria come input.
$sha384 — Può usare una variabile binaria come input.
$sha512 — Può usare una variabile binaria come input.
$hmac — Può usare una variabile binaria come input.
$com — Può usare una variabile binaria come input o output.

Posizione e lunghezza

La posizione nelle variabili binarie è basata su 1, dove il primo byte di una variabile binaria è in posizione 1. Questo è diverso dalla posizione usata da /bread e /bwrite per leggere o scrivere variabili binarie su file, dove la posizione 0 del file corrisponde al primo byte del file.

Se una variabile binaria ha lunghezza N, la posizione N è l’ultimo byte della variabile. Poiché aggiungere dati in coda a una variabile binaria richiede di calcolare e scrivere alla posizione N+1, diversi comandi binari permettono di usare la posizione -1 per appendere dati alla variabile. Inoltre, invece di usare $bvar per trovare la lunghezza di una variabile, alcuni di essi consentono anche di usare -1 come parametro length per scrivere l’intera variabile.

Unicode

Scrivere caratteri unicode in variabili binarie usando lo switch -t fa sì che la lunghezza della variabile binaria sia maggiore della lunghezza della stringa di testo scritta. I caratteri Unicode 128-2047 aggiungono 2 byte a una variabile binaria e quelli 2048-65535 ne aggiungono 3 ciascuno. Quando aggiungi testo a una variabile puoi usare -ta invece di -t per evitare di codificare i caratteri Unicode 128-255 come 2 byte, ma solo se il testo aggiunto non contiene caratteri Unicode maggiori di 255.

//bset -t &var1 1 $chr(233) | echo -a shows length is 2 -> $bvar(&var1,0)
//bset -t &var2 1 $chr(10004) | echo -a shows length is 3 -> $bvar(&var2,0)
//bset -ta &var3 1 $chr(233) | echo -a shows length is 1 -> $bvar(&var3,0)
//bset -ta &var4 1 $chr(10004) | echo -a shows length is 3 -> $bvar(&var4,0)
//bset -ta &var5 1 $chr(233) $+ $chr(10004) | echo -a shows length is 2+3=5 -> $bvar(&var5,0)

Nota: se aggiungi $chr(233) e $chr(10004) come due comandi -ta separati, puoi aggiungere il carattere 233 come 1 byte e 10004 come 3 byte. In quel caso il 10004 non fa sì che il 233 venga codificato come 2 byte perché le stringhe sono state aggiunte separatamente:

//bset -ta &var5 1 $chr(233) | bset -ta &var5 -1 $chr(10004) | echo -a shows length is 4 -> $bvar(&var5,1-)

Esempi di creazione di variabili binarie

Le variabili binarie possono essere create usando uno dei /commands o $identifiers che accettano una variabile binaria come parametro di output, oppure tramite i comandi /bset, /bcopy e /bwrite creati a questo scopo.

; Imposta &binvar al byte 0 ripetuto 99 volte seguito dal byte 255 alla posizione 100:
//bset -c &binvar 100 255 | echo -a $bvar(&binvar,1-)

; Imposta &binvar al contenuto testuale di %variable:
//bset -tc &binvar 1 %variable | echo -a $bvar(&binvar,1-).text

; Crea o accoda l'intero contenuto di &binvar a &var2:
//bcopy -1 &var2 1 &binvar -1

; Legge l'intero contenuto di versions.txt in &versions:
//bread versions.txt 0 $file(versions.txt).size &versions | echo -a $bvar(&versions,0)

; Imposta &binvar al contenuto del messaggio di canale:
ON *:TEXT:*:#:{
  noop $regsubex(,$parms,,,&binvar)
}

; Imposta &binvar al contenuto della clipboard:
//clipboard $+(abc,$crlf,def) | noop $cb(-1,,&binvar) | echo -a $bvar(&binvar,1-)

; Legge dal socket in &binvar:
on *:SOCKREAD:socket:{
  sockread 4096 &binsockread
}

Esempi di modifica di variabili binarie

; Sostituisce tutti i caratteri TAB con spazi:
/breplace &binvar 9 32

; Comprimi il contenuto di &versions:
//bread versions.txt 0 $file(versions.txt).size &versions | noop $compress(&versions,b) | echo -a $bvar(&versions,0)

; Cifra e codifica il contenuto di &versions:
//noop $encode(&versions,bcm,password)

Modifica di variabili binarie esistenti

Le variabili binarie differiscono dalle variabili di testo nel modo in cui vi aggiungi valori e in ciò che accade quando aggiungi contenuto più corto a una variabile esistente che ne contiene uno più lungo. Se aggiungi 3 byte alla posizione 1 di una variabile binaria lunga 5, i 3 byte aggiunti sostituiscono i 3 byte in quelle posizioni e i valori nelle posizioni 4-5 rimangono, a meno che tu non usi lo switch -c:

//bset -t &var 1 1234567890 | bset -t &var 1 test | echo -a shows content is test567890 -> $bvar(&var,1-)

L’esempio sopra potrebbe produrre una stringa anche più lunga di 10 se &var conteneva in precedenza una stringa più lunga di 10. Se il primo comando usasse -tc invece di -t, il contenuto verrebbe troncato oltre i 10 byte aggiunti. Se il secondo comando usasse -tc invece di -t, il contenuto oltre i 4 byte aggiunti verrebbe troncato.

Se usi bset per inserire valori in una variabile alla posizione 10, le prime 9 posizioni sono indefinite, a seconda del fatto che la variabile esistesse già. Se la variabile esisteva già con lunghezza 4, i byte nelle posizioni 5-9 vengono riempiti con valore 0, non con il testo “0” che corrisponde al byte 48. Se la variabile non esisteva ancora, i byte nelle posizioni 1-9 vengono riempiti con valore 0.

Esempi di variabili binarie come input

; Mostra l'hash $sha1 del contenuto di &versions:
//echo -a $sha1(&versions,1)

; Scrive &versions su disco:
//bwrite -c test.dat 0 -1 &versions

Variabili binarie “locali”

Quando usi %variables dentro un alias, puoi sfruttare il loro scope “locale” per riutilizzare in sicurezza i nomi delle variabili senza preoccuparti di distruggere variabili usate da altri script o alias. Puoi usare /var %a value in un alias per impostare quella variabile locale senza preoccuparti di distruggere una variabile con lo stesso nome usata dall’alias che ha chiamato il tuo alias, e non devi preoccuparti se il tuo script chiama un altro alias che usa anch’esso quel nome come variabile locale.

Tuttavia, lo scope delle variabili binarie implica che esse esistano in tutti gli alias che si chiamano a vicenda o nell’evento che ne ha attivato l’uso. Per evitare che gli alias danneggino il contenuto delle rispettive variabili binarie, se un alias deve creare variabili binarie ed è progettato per essere chiamato da altri alias che potrebbero usare anch’essi variabili binarie, devi proteggerti dal distruggere le variabili binarie usate dal chiamante. Due modi per farlo sono:

Richiedere che il chiamante invii il nome della variabile come parametro quando chiama il tuo alias.
Creare un nome di variabile unico in modo da rendere improbabile che un altro alias usi lo stesso nome per una variabile binaria.

Passa il nome della variabile binaria all’alias e visualizza l’output di $bvar in esadecimale invece che in decimale:

//echo -a $BvarAsHex(&binvar)

alias BvarAsHex {
  return $regsubex($bvar($1,1-1000),/(\d*)/g,$base(\1,10,16,2))
}

Crea un nome univoco per evitare di distruggere una variabile esistente:

//var %a $+(myalias,$ticks,$ctime) | bset -t & $+ %a 1 test | echo -a $bvar(& $+ %a,1-).text

Vedi la guida sulle Variabili per maggiori dettagli sulla creazione di nomi di variabile dinamici.

Nota: se la tua variabile temporanea non è più necessaria ed è molto grande, puoi usare /bunset per ridurre l’uso di memoria se durante l’esecuzione dello script stai creando anche altre variabili binarie di grandi dimensioni. Altrimenti, verrà eliminata alla fine dell’esecuzione dello script.

Salvataggio delle variabili binarie

Poiché le variabili binarie scompaiono non appena termina l’esecuzione del tuo script, se hai bisogno di riutilizzarle più tardi devi trovare un modo per salvarle:

scriverle su un file su disco:

//bwrite -c save.dat 0 1 &binvar

memorizzarle in una hashtable:

/hadd -smb binvar_save binvar &binvar

Nota: le hashtable non vengono salvate su disco, quindi devi salvare anche la tabella su disco:

/hsave -sb binvar_save savebins.dat

… e poi ricaricare la variabile binaria la prossima volta che riavvii mIRC:

/hload -sb binvar_save savebins.dat

Usare $encode per tradurre i dati binari in testo, che può essere salvato in variabili o scritto su disco.

//noop $encode(&binvar,bm) | set %binvar_save $bvar(&binvar,1-).text

Nota: $encode traduce 3 byte di input, binari o testuali, in 4 caratteri di testo, quindi non dovresti tentare di usare questo metodo su variabili binarie più lunghe di circa 3000 byte. Recupera il contenuto binario dalla %variable di testo con:

//bset -t &binvar 1 %binvar_save | noop $decode(&binvar,bm)