From WikiChip
Editing mirc/binary variables
Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.
The edit can be undone.
Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
This page supports semantic in-text annotations (e.g. "[[Is specified as::World Heritage Site]]") to build structured and queryable content provided by Semantic MediaWiki. For a comprehensive description on how to use annotations or the #ask parser function, please have a look at the getting started, in-text annotation, or inline queries help pages.
Latest revision | Your text | ||
Line 1: | Line 1: | ||
{{mirc title|Binary Variables}} | {{mirc title|Binary Variables}} | ||
− | |||
− | |||
− | |||
mIRC's '''binary &variables''' are distinguished from its text %variables by beginning with the & ampersand symbol, while text variables begin with the % percent symbol. They differ from text variables in content, scope, duration, and length. | mIRC's '''binary &variables''' are distinguished from its text %variables by beginning with the & ampersand symbol, while text variables begin with the % percent symbol. They differ from text variables in content, scope, duration, and length. | ||
* They are composed of byte values, which can be any of the values 0-255. Among other differences, they can contain the $chr(0) value, which text variables cannot. | * They are composed of byte values, which can be any of the values 0-255. Among other differences, they can contain the $chr(0) value, which text variables cannot. | ||
− | * Their scope is similar to that of local identifiers such as $nick and $rawmsg. They exist as long as | + | * Their scope is similar to that of local identifiers such as $nick and $rawmsg. They exist as long as the event or script/alias is running, then are deleted. When your alias begins executing or an event is triggered, you must create all binary variables before you can use them. Binary variables continue to exist until the script/alias/event ends or they are deleted with /bunset. |
− | * Binary variables | + | * Binary variables cannot be saved to your variables file (default name is vars.ini) the way global %variables are saved. To preserve them, you must either write them to a disk file, save to a hashtable item, or use $encode to save them to a %variable or hashtable. |
* While text variables are limited in length by the 4150 line length, binary variable length is limited by available memory. | * While text variables are limited in length by the 4150 line length, binary variable length is limited by available memory. | ||
− | |||
Some uses for Binary Variables include: | Some uses for Binary Variables include: | ||
Line 65: | Line 61: | ||
== Position and Length == | == Position and Length == | ||
− | Position in binary variables is 1-based, where the first byte value in a binary variable is position 1. This is different than the position used by /bread | + | Position in binary variables is 1-based, where the first byte value in a binary variable is position 1. This is different than the position used by /bread amd /bwrite to read/write binary variables to disk files, where file position 0 is the position for reading/writing the first byte of the file. |
If a binary variable has length N, position N is the last byte of the variable. Because appending to a binary variable requires calculating and writing to position N+1, several of the binary commands allow using position -1 to append to a variable. Also, instead of using $bvar to find the length of a variable, some of them also allow -1 in the length parameter for writing the entire variable. | If a binary variable has length N, position N is the last byte of the variable. Because appending to a binary variable requires calculating and writing to position N+1, several of the binary commands allow using position -1 to append to a variable. Also, instead of using $bvar to find the length of a variable, some of them also allow -1 in the length parameter for writing the entire variable. | ||
Line 72: | Line 68: | ||
Writing unicode characters to binary variables using the -t switch causes the length of the binary variable to be longer than the length of the text string written to them. Unicode characters 128-2047 add 2 bytes to a binary variable and 2048-65535 add 3 each. When adding text to a variable you can use -ta instead of -t to avoid encoding Unicode characters 128-255 as 2 bytes, but only if the text value being added contains no Unicode characters greater than 255. | Writing unicode characters to binary variables using the -t switch causes the length of the binary variable to be longer than the length of the text string written to them. Unicode characters 128-2047 add 2 bytes to a binary variable and 2048-65535 add 3 each. When adding text to a variable you can use -ta instead of -t to avoid encoding Unicode characters 128-255 as 2 bytes, but only if the text value being added contains no Unicode characters greater than 255. | ||
− | < | + | <syntaxhighlight lang="mirc"> |
//bset -t &var1 1 $chr( 233) | echo -a shows length is 2 -> $bvar(&var1,0) | //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 -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 &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 &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)</ | + | //bset -ta &var5 1 $chr(233) $+ $chr(10004) | echo -a shows length is 2+3=5 -> $bvar(&var5,0)</syntaxhighlight> |
Note: If you add $chr(233) and $chr(10004) as 2 separate -ta commands, you can add character 233 as 1 byte and add 10004 as 3 bytes. In that case the 10004 does not cause the 233 to be encoded as 2 bytes because the strings were added separately: | Note: If you add $chr(233) and $chr(10004) as 2 separate -ta commands, you can add character 233 as 1 byte and add 10004 as 3 bytes. In that case the 10004 does not cause the 233 to be encoded as 2 bytes because the strings were added separately: | ||
− | < | + | <syntaxhighlight lang="mirc"> |
− | //bset -ta &var5 1 $chr(233) | bset -ta &var5 -1 $chr(10004) | echo -a shows length is 4 -> $bvar(&var5,1-)</ | + | //bset -ta &var5 1 $chr(233) | bset -ta &var5 -1 $chr(10004) | echo -a shows length is 4 -> $bvar(&var5,1-)</syntaxhighlight> |
== Creating Binary Variables Examples == | == Creating Binary Variables Examples == | ||
Binary variables can be created using one of the /commands or $identifiers which accept a binary variable as an output parameter, or by the /bset, /bcopy, and /bwrite commands created for that purpose. | Binary variables can be created using one of the /commands or $identifiers which accept a binary variable as an output parameter, or by the /bset, /bcopy, and /bwrite commands created for that purpose. | ||
− | < | + | <syntaxhighlight lang="mirc"> |
Set &binvar to 99 byte value 0 followed by byte value 255 at position 100: | Set &binvar to 99 byte value 0 followed by byte value 255 at position 100: | ||
//bset -c &binvar 100 255 | echo -a &bvar(&binvar,1-) | //bset -c &binvar 100 255 | echo -a &bvar(&binvar,1-) | ||
Line 101: | Line 97: | ||
Read from socket to &binvar | Read from socket to &binvar | ||
on *:SOCKREAD:socket: { sockread 4096 &binsockread } | on *:SOCKREAD:socket: { sockread 4096 &binsockread } | ||
− | </ | + | </syntaxhighlight> |
== Modifying Binary Variables Examples == | == Modifying Binary Variables Examples == | ||
− | < | + | <syntaxhighlight lang="mirc"> |
Replace all TAB characters with spaces: | Replace all TAB characters with spaces: | ||
/breplace &binvar 9 32 | /breplace &binvar 9 32 | ||
Line 110: | Line 106: | ||
encrypt and encode contents of &versions | encrypt and encode contents of &versions | ||
//noop $encode(&versions,bcm,password) | //noop $encode(&versions,bcm,password) | ||
− | </ | + | </syntaxhighlight> |
=== Modifying existing Binary Variables === | === Modifying existing Binary Variables === | ||
Binary variables are different than text variables in how you add values to them, and what happens when you add shorter content to an existing variable with longer content. If you add 3 bytes to position 1 of a binary variable with length of 5, the 3 added bytes replace the 3 bytes in those positions, and the values in positions 4-5 remain unless you use the -c switch: | Binary variables are different than text variables in how you add values to them, and what happens when you add shorter content to an existing variable with longer content. If you add 3 bytes to position 1 of a binary variable with length of 5, the 3 added bytes replace the 3 bytes in those positions, and the values in positions 4-5 remain unless you use the -c switch: | ||
− | < | + | <syntaxhighlight lang="mirc"> |
− | //bset -t &var 1 1234567890 | bset -t &var 1 test | echo -a shows content is test567890 -> $bvar(&var,1-)</ | + | //bset -t &var 1 1234567890 | bset -t &var 1 test | echo -a shows content is test567890 -> $bvar(&var,1-)</syntaxhighlight> |
The above example could be a string even longer than 10 if &var previously contained a strong longer than 10. If the 1st command used -tc instead of -t, the variable content is chopped beyond the 10 bytes being added. If the 2nd command used -tc instead of -t, the content beyond the 4 bytes being added is chopped. | The above example could be a string even longer than 10 if &var previously contained a strong longer than 10. If the 1st command used -tc instead of -t, the variable content is chopped beyond the 10 bytes being added. If the 2nd command used -tc instead of -t, the content beyond the 4 bytes being added is chopped. | ||
Line 122: | Line 118: | ||
== Binary Variables as Input Examples == | == Binary Variables as Input Examples == | ||
− | < | + | <syntaxhighlight lang="mirc"> |
display $sha1 hash of contents of &versions | display $sha1 hash of contents of &versions | ||
//echo -a $sha1(&versions,1) | //echo -a $sha1(&versions,1) | ||
write &versions to disk | write &versions to disk | ||
//bwrite -c test.dat 0 -1 &versions | //bwrite -c test.dat 0 -1 &versions | ||
− | </ | + | </syntaxhighlight> |
== 'local' Binary variables == | == 'local' Binary variables == | ||
Line 138: | Line 134: | ||
Pass binary variable name to alias, display $bvar output in hex instead of decimal: | Pass binary variable name to alias, display $bvar output in hex instead of decimal: | ||
− | < | + | <syntaxhighlight lang="mirc">//echo -a $BvarAsHex(&binvar) |
− | alias BvarAsHex { return $regsubex($bvar($1,1-1000),/(\d*)/g,$base(\1,10,16,2)) }</ | + | alias BvarAsHex { return $regsubex($bvar($1,1-1000),/(\d*)/g,$base(\1,10,16,2)) }</syntaxhighlight> |
Create unique name to avoid destroying existing variable: | Create unique name to avoid destroying existing variable: | ||
− | < | + | <syntaxhighlight lang="mirc"> |
− | //var %a $(myalias,$ticks,$ctime) | bset -t & $+ %a 1 test | echo -a $bvar(& $+ %a ,1-).text</ | + | //var %a $(myalias,$ticks,$ctime) | bset -t & $+ %a 1 test | echo -a $bvar(& $+ %a ,1-).text</syntaxhighlight> |
See {{mIRC|Variables}} in the Guide for more details on creating dynamic variable names. | See {{mIRC|Variables}} in the Guide for more details on creating dynamic variable names. |