File IO

If you don't already have a programming background, starting in on
file reading and writing from Mel may be a little intimidating.  It was for me.
It seems like such a big thing to do, to write a brand new file to the hard-drive.

You get used to it pretty quick.

The commands we'll most commonly use are:

fopen ...... to open a file
fclose ..... closes a file once we're done

those commands deal with any file type

these ones are specifically for ascii type files:

fprint ..... to write to a file
fgetline ... reads in the current line from the file
feof ....... used to find out if the end of the file has been reached

there are also commands for dealing with binary file types:

fread ...... similar to fgetline
fwrite ..... similar to fprint

but dealing with ascii files is a lot more common.

I won't go over the details of using all these commands, because
that's what the help docs are for.

One thing that's not made clear in the doc's is:
If you give fopen a file that does not exist, it will create the file
provided that the directory path is valid.

Here's an example, edit the file path to whatever suits your computer setup:

	string $path = "E:/temp/aFileWithThisNameProbablyDoesNotExist.txt";
	int $fileId = `fopen $path "a"`; // incase the file does exist, open in mode "a"
	if (!$fileId)
		error ("Could not open file at " + $path );
	fprint $fileId "I opened a file.";
	fclose $fileId;

fopen returns an integer value which is used to access the file.
If it could not open the file it will return 0, otherwise it
will always return a number greater than 0;
If it can't open the file, it won't give you an error message, so
it's always a good idea to do plenty of error checking when you work
with fopen.

I opened the file in mode "a", which means append.  If the file does not exist, it
will be created, but if it does exist the current contents will not be touched
and fprint will append it's text to the end.
Mode "w" will erase the contents of the file and start from the beginning.

You can have multiple file streams open at once.
Here's an example of an efficient way to edit the contents of a file
It's a little long, so download it here...
if it tries to open in the browser, right click -> save target as...
File Editing
To run this, you'll need to have a dummy file for it to work on.
This example also uses System Commands

The fileReplace example opens two file streams, and reads the contents of the first, plus
an additional string, into the second file.  It then renames the new file to have the name
of the original, and gives the original a different name.  It could also delete the old file,
thereby "replacing" it.

The most efficient way to write to files is to open the file and do it all at once.
Opening a file just to print a line or two, and closing it again, then reopening and printing
a couple more lines, repeat, repeat, will take a lot more time to run.

This has to do with the way fprint buffers it's ouput, the help docs have the detail.