Documentation › Modules › File.em

File: File.em

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      := "*";

AppendToFile( filename, textlines )#

Parameters

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 config

CreateDirectory( dirname )#

Parameters

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

FileExists( filename )#

Parameters

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 config

ListDirectory( dirname, extension := LISTDIR_ALL_FILES, listdirs := LISTDIR_DONT_LIST_DIRS )#

Parameters

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

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 config

OpenBinaryFile( filename, mode := OPENMODE_IN, endian := LITTLE_ENDIAN )#

Parameters

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

Related config

OpenXMLFile( filename )#

Parameters

filename string

Explanation

opens given filename and returns XMLFile object, fileaccess.cfg is checked

Return values

XMLFile object or error

Related

Related config

ReadFile( filename )#

Parameters

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 config

WriteFile( filename, textcontents )#

Parameters

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 config