_file.fopen

Open a file for reading or writing.

Syntax

_file.fopen(filename, fmode[, "BOM"])

Parameters

filename the name of a file to be opened.

fmode The type of open. This setting is a standard C file open mode, typically r for "read", w for "write" or a for "append".

Supplying a third parameter of value BOM (Byte Order Mark) will indicate that a BOM is required on output. Otherwise, no BOM will be written. Note that this is a different default than what applies to _file.writeFile(). If the open mode is w or a, i.e. for output, then the file will be immediately created. For mode w it will silently overwrite an existing file of the given filename.

Returned Value

If successful, fopen returns a new object that represents the File Pointer fp of the open file. You can then use this new fp object to read or write. If the file cannot be opened, null is returned.

Functions

You must use the returned fp object from fopen in order to read or write a file. The following functions can be used with this file pointer:

• fp.fclose()
Close the file specified by fp.

• fp.fflush()
  Force the file's memory buffer to be written to the file.
  
  
• fp.fgetc()
  Read a single byte (an integer between 0 and 255) from the current open file specified by fp. Returns -1 when at end-of-file. Multi-byte characters will be returned one byte at a time. Users of these byte-oriented functions will likely be interested in the basic JavaScript functions of charCodeAt() and String.fromCharCode().
  
  
• fp.fgets()
  Read a single line from the current open file specified by fp. Returns null when at end-of-file. The file is expected to be encoded in UTF8 (7-bit ASCII is a subset of UTF8).
  
  
• fp.fprintf(format[, p1[, p2 ...]])
  Write a formatted line of text to the file. See _printf for details.
• fp.fputc(an integer number)
  Write a single byte to the file. The number should be 0 <= n <= 255. Note that no automatic UTF8 encoding will occur. It's very raw.
  
  
• fp.fputs(string)
  Write a line of text to the file. The line will be encoded in UTF8. (Internally, strings are in multi-byte Unicode.)
  
  
• fp.fread([count])
  Read up to count bytes of data from the input file. This returns a string containing the bytes read. If count is not specified, everything up to and including the next newline is read. This bypasses any implied assumption that characters are encoded as UTF8. Instead, the raw bytes are read. In theory you could read binary files with this function but in practice null bytes will terminate the returned string and processing non 7-bit ASCII characters will be nigh impossible. See fp.fwrite() as well.
  
  
• fp.fseek(offset, 0|1|2)
  Move to a new location in the file. 0 is start-of-file, 1 is current offset, 2 is end-of-file. offset can be negative.
  
  
• fp.ftell()
  Returns the next read/write position (i.e. the current offset) in the file.
  
  
• fp.fwrite(string[, count])
  Write count characters to the file. This writes the data without the usual conversion to UTF8. If count is not specified, the entire string is written out.

Example

var fp = _file.fopen("myfile.txt", "w");    // open for write
if (fp) {
	fp.fputs("Hello World");                // write to file
	fp.fclose();
}

Naming Conventions

fp is an extremely common variable name to use for a file pointer. It's readily understood by maintainers of your code; great for when dealing with only one file. As a suggestion, you might consider using fpIn and fpOut for a classic case where you have an input file and an output file. Another useful method is to prefix fp to the file's purpose. E.g. fpForm, fpData, fpControl. Using that convention helps make your script more readily understood (and thus maintained). This is akin to the habit of using what is called "Hungarian notation" wherein strings would start with "s" (e.g. sName); Booleans start with "b" (e.g. bFound); integers start with "i" if they are 0-based, or with "n" if they are 1-based (e.g. iIndex, nCount). Similarly, it is useful to adopt the convention of prefixing your file name variables with fn. E.g. fnForm, fnData, fnControl. Correlating your fn's and your fp's is pretty helpful.