Welcome to PenUltima Online. Click to login or register.

File: File.em

Description: File Access functions
Last Modified: 11/10/2019

File Constants:

// LogToFile constants
const LOG_DATETIME := 1; // log Core-Style DateTimeStr in front of log entry
//BinaryFile constants
const OPENMODE_IN := 0x01; // (input) Allow input operations on the stream
const OPENMODE_OUT := 0x02; // (output) Allow output operations on the stream
const OPENMODE_ATE := 0x04; // (at end) Set the stream's position indicator to the end of the stream on opening
const OPENMODE_APP := 0x08; // (append) Set the stream's position indicator to the end of the stream before each output operation
const OPENMODE_TRUNC := 0x10; // (truncate) Any current content is discarded, assuming a length of zero on opening

const SEEKDIR_BEG := 0x00; // beginning of sequence
const SEEKDIR_CUR := 0x01; // current position within sequence
const SEEKDIR_END := 0x02; // end of sequence

const LITTLE_ENDIAN := 0x00;
const BIG_ENDIAN := 0x01;

// ListDirectory constants
const LISTDIR_LIST_DIRS := 0x1;
const LISTDIR_DONT_LIST_DIRS := 0x0;
const LISTDIR_NO_FILES := "";
const LISTDIR_ALL_FILES := "*";

Modules:

AppendToFile( filename, textlines )
Parameters:
Name Type
filename string
textlines array of strings
Explanation
Appends to a text file, adding newlines. Creates file if it does not exist.
By default, no package has any file access rights. To grant access, see config/fileaccess.cfg
Return values
1 or error
Errors
"Invalid parameter type"
"Error in filename descriptor"
"No parent path traversal please."
"Access denied"
"Unable to open file: X"
"Error during write."
Related Configs
fileaccess.cfg
CreateDirectory( dirname )
Parameters:
Name Type
dirname string
Explanation
Creates directory
Return values
1 or error
Errors
"Invalid parameter type"
"Error in dirname descriptor"
"No parent path traversal please."
"Directory already exists."
"Could not create directory."
CreateXMLFile()
Explanation
creates an empty XMLFile object
Return values
XMLFile object or error
Related
XMLFile
FileExists( filename )
Parameters:
Name Type
filename string
Explanation
Checks for the existence of a file based on Filename parameter.
Return values
1 on success
Errors
"Invalid parameter type"
"Error in filename descriptor"
"No parent path traversal please."
Related Configs
fileaccess.cfg
ListDirectory( dirname, extension := LISTDIR_ALL_FILES, listdirs := LISTDIR_DONT_LIST_DIRS )
Parameters:
Name Type
dirname string
extension string
listdirs Integer
Explanation
List directory content
extension param can be extension without "." or file.em constant:
const LISTDIR_NO_FILES       := "";
const LISTDIR_ALL_FILES      := "*";
file.em constants for listdirs:
const LISTDIR_LIST_DIRS      := 0x1;
const LISTDIR_DONT_LIST_DIRS := 0x0;
Return values
array of strings or error
Errors
"Invalid parameter type"
"Error in dirname descriptor"
"No parent path traversal please."
"Directory not found."
LogToFile( filename, line, flags := 0 )
Parameters:
Name Type
filename String
line String
flags Integer
Explanation
Appends a single line to a text file, adds newlines, creates file if it does not exist.
By default, no package has any file access rights. To grant access, see config/fileaccess.cfg
file.em constants for flags:
const LOG_DATETIME := 1; // log Core-Style DateTimeStr in front of log entry
Return values
1 or error
Errors
"Invalid parameter type"
"Error in filename descriptor"
"No parent path traversal please."
"Access denied"
"Unable to open file: X"
"Error during write."
Related Configs
fileaccess.cfg
OpenBinaryFile( filename, mode := OPENMODE_IN, endian := LITTLE_ENDIAN )
Parameters:
Name Type
filename string
mode Integer
endian Integer
Explanation
Opens BinaryFile stream
By default, no package has any file access rights. To grant access, see config/fileaccess.cfg
file.em constants for mode:
const OPENMODE_IN    := 0x01; // (input) Allow input operations on the stream
const OPENMODE_OUT   := 0x02; // (output) Allow output operations on the stream
const OPENMODE_ATE   := 0x04; // (at end) Set the stream's position indicator to the end of the stream on opening
const OPENMODE_APP   := 0x08; // (append) Set the stream's position indicator to the end of the stream before each output operation
const OPENMODE_TRUNC := 0x10; // (truncate) Any current content is discarded, assuming a length of zero on opening
file.em constants for endian:
const LITTLE_ENDIAN := 0x00;
const BIG_ENDIAN    := 0x01;
Return values
BinaryFile or error
Errors
"Invalid parameter type"
"Error in filename descriptor"
"No parent path traversal please."
"Access denied"
Related
BinaryFile
Related Configs
fileaccess.cfg
OpenXMLFile( filename )
Parameters:
Name Type
filename string
Explanation
opens given filename and returns XMLFile object, fileaccess.cfg is checked
Return values
XMLFile object or error
Related
XMLFile
Related Configs
fileaccess.cfg
ReadFile( filename )
Parameters:
Name Type
filename string
Explanation
Reads a text file, returning the contents as an array of strings, removing newlines.
By default, no package has any file access rights. To grant access, see config/fileaccess.cfg
Return values
returns array of strings
Errors
"Invalid parameter type"
"Error in filename descriptor"
"No parent path traversal please."
"Access denied"
"File not found: X"
Related Configs
fileaccess.cfg
WriteFile( filename, textcontents )
Parameters:
Name Type
filename string
textcontents array of strings
Explanation
Writes a new file to disk, appends newlines, creates file if it does not exist, renames existing file to filename.bak
By default, no package has any file access rights. To grant access, see config/fileaccess.cfg
Return values
1 or error
Errors
"Invalid parameter type"
"Error in filename descriptor"
"No parent path traversal please."
"Access denied"
"File not found: X"
"Error during write."
"Unable to remove filenameX: reasonY
"Unable to rename filenameX: to filenameZ: reasonY
Related Configs
fileaccess.cfg