Editing mirc/file handling

{{mirc title|File Handling}}'''File Handling''' allows you to manipulate files on disk using seperate, simple operations. This allows for efficiency.

To understand how it works, you must be familiar with text file operations such as {{mIRC|/write}} and {{mIRC|$read}}.


== {{mIRC|/fopen}} ==

/fopen [-nox] <name> <filename>

{{mIRC|/fopen}} opens the filename and use the specified name to reference it.

The command fail by default if the file does not exists, the -n switch create the file if it does not exist, fails if it exists. The -o switch create a new file if it does not exist but overwrite the file if it exists. The -x switch opens the file for exclusive access, others processus cannot access that file

'''Note:''' if /fopen fails, it does not halt processing, you must check {{mIRC|$ferr}} to see if any error occured, see below.

After you opened a file with /fopen, you have a pointer of the content of the file, it starts at 0. This pointer is the starting position to read/write from.

== {{mIRC|/fseek}} ==

/fseek -lnwr <name> <position>

{{mIRC|/fseek}} sets the read/write pointer to the specified <position> in the file, unless you use a switch:

* -l - sets the pointer to the beginning of the Nth line, use <position> to specify the Nth line
* -n - sets the pointer to the beginning of the next line (from the current position of the read/write pointer), this does not take a parameter
* -w - sets the pointer to the beginning of the line matching the wildcard expression, use <position> to specify the wildcard expression
* -r - sets the pointer to the beginning of the line matching the regular expression, use <position> to specify the regular expression

If /fseek fails, it sets the pointer to the end of the file.

== {{mIRC|/fwrite}} ==

/fwrite [-bn] <name> <text | &binvar>

{{mIRC|/fwrite}} allows you to write to the file at the current pointer position, -b specify a binary variable, -n adds a $crlf at the end of the line.

== {{mIRC|/fclose}} ==

/fclose <name | wildcard>

{{mIRC|/fclose}} closes all the matching name (wildcard expression allowed)

== {{mIRC|/flist}} ==

{{mIRC|/flist}} just lists all the current handles.

== {{mIRC|$fopen}}(name | N) ==

{{mIRC|$fopen}} Returns the name of that handle if it exists, or the Nth handle.
 
Properties:
* .fname - returns the complete filename opened for that handle
* .pos - returns the current position of the read/write pointer
* .eof - returns $true if the end of the file has been reached
* .err - returns $true if an error occured on the file

In a script, {{mIRC|$ferr}} = $fopen(handle).err and {{mIRC|$feof}} = $fopen(handle).eof, always returns the state of last involved handle in a file handing command.

'''Note:''' Since file access errors will not halt a script, the eof and err properties or identifiers must be checked after each file access command.

== {{mIRC|$fread}}(name | N) ==

This form of {{mIRC|$fread}} returns the next $crlf delimited line, useful to read line by line

== {{mIRC|$fread}}(name | N, M, &binvar) ==

This form of {{mIRC|$fread}} returns the number of bytes read (from the file pointed by name or the Nth handle) into the specified binary variable, where M is the number of bytes to read.

== {{mIRC|$fgetc}}(name | N) ==

{{mIRC|$fgetc}} returns the next character.

== When to use File handling ==
It important to know when to use explicit file handling, and when you can use {{mIRC|/write}} and {{mIRC|$read}}.

Let's take a look at /write, /write is a powerful tool which allows you to write to a file according to severals predefined options.

A simple "/write filename.txt line" involves the following file handling operations:

* /fopen - opens the file
* /fseek - goes to the end of the file
* /fwrite - writes to the file
* /fclose - closes the file

So, executing /write twice involves 8 file handling operations; the more you have to write, the more operations you create. If you do /write three times, the 12 operations can be reduced to 5:

<source lang="mIRC">
; assuming text.txt is empty
write test.txt line 1
write test.txt line 2
write test.txt line 3

; is better written as
fopen test test.txt
fwrite -n line 1
fwrite -n line 2
fwrite -n line 3
fclose test
</source>

The same thing applies to reading, $read opens the file, try to match and close the file, so any consecutive call to $read means the file is opened/closed each time. If you are looking for a particular line, you can avoid multiple $read calls by searching with /fseek.

Whenever you are going to use /write or $read in a loop to write/read a lot of things, if the loop isn't small and if the file isn't small, it might get slow very quickly, and you should consider using file handling.

== Example ==
Here is a real-life example. I wanted to be able to get the associated country for an ip address. You may use socket but I wanted to get the result without leaving the current scope (having to wait for the socket), COM may have been used but that would limit the use under Wine, so I found www.IP2Location.com, which provides a small database, each line being a range of long ip address, here is the first line:

<pre>"16777216","16777471","AU","AUSTRALIA"</pre>

So you have to convert your ip to a long ip using $longip, and then start to look in which range your number belong.

The file is pretty big, you certainly don't want to look line by line, I did the following:

<source lang="mIRC">
;$iptocountry(85.125.126.112)
alias iptocountry {
  ;convert to a long ip, get the length of the file, and prepare a wildcard expression for /fseek
  var %n $longip($1),%a 1,%p,%l $lof(path\to\ip2country.txt),%v,%x *","*","??","*"
  ;opens the file
  .fopen ip2c path\to\ip2country.txt
  ;depending on the length of the ip address, we can jump to a fixed line number, which is the start of ranges for that length
  if ($len(%n) == 9) .fseek -l ip2c 2266
  elseif ($v1 == 10) .fseek -l ip2c 11951
  ;%a starts at 1, as long as we can find a matching line which start with the maximum number of character from the ip address
  while $mid(%n,1,%a) {
    .fseek -w ip2c $+(",$mid(%n,1,%a),%x)
    ; if no match, we break
    if ($fopen(ip2c).pos == %l) break
    ;otherwise we keep the position in a variable to know which line we have the last match
    var %p $v1,%a %a + 1
  }
  ;get to that line
  .fseek ip2c %p
  ;from here we must check if the line we are on is already the correct line
  %v = $fread(ip2c)
  ;if the right value of the range is bigger than our number, we must go upward in the file
  if ($gettok(%v,3,34) > %n) {
    ;well if the left value of the range is smaller than our number, we have our line!
    if ($gettok(%v,1,34) < %n) {
     ;if it is, we return
      %v = $gettok(%v,7,34)
      .fclose ip2c
      return %v
    }
    ;otherwise we must go upward one line, they can't be more line to check (can't remember why though!)
    .fseek ip2c $calc(%p - 3)
    dec %p 3
    while (1) {
      if ($fgetc(ip2c) == 10)  {
        %v = $fread(ip2c)
        .fclose ip2c
        return $gettok(%v,7,34)
      }
      dec %p
      .fseek ip2c %p
    }
  }
  ;otherwise, we must go downward in the file until the right value of the range is bigger than our number
  while $fread(ip2c) {
    %v = $v1
    if ($gettok(%v,3,34) > %n) break
  }
  .fclose ip2c
  return $gettok(%v,7,34)
}
</source>
[[Category:mIRC]]