File
File
objects are created with the file
command. They contain references to disk files that may or may not actually exist on disk. For example, when you execute the file
command to create a new file, a valid file
object is created but nothing is actually stored on disk until you call the file.create()
function.
Example
The following example creates a preferences file in the project folder:
var created : boolean
created = file("/PACKAGE/SpecialPrefs/"+storage.users[2].name+".myPrefs").create()
Pathnames
File
objects support several pathnames, including filesystems
or posix
syntax. Supported pathnames are detailed in the Pathnames page.
Functions and properties
.copyTo( destinationFolder : 4D.Folder { , newName : string } { , overwrite : integer } ) : 4D.File copies the file object into the specified destinationFolder |
.create() : boolean creates a file on disk according to the properties of the file object |
.createAlias( destinationFolder : 4D.Folder , aliasName : string ) : 4D.File creates a symbolic link |
.delete() deletes the file |
.exists : boolean true if the file exists on disk |
.extension : string the extension of the file name (if any) |
.fullName : string the full name of the file, including its extension (if any) |
.getContent() : 4D.Blobreturns a 4D.Blob object containing the entire content of a file |
.getText( { charSetName : string { , breakMode : integer } } ) : string .getText( { charSetNum : integer { , breakMode : integer } } ) : string returns the contents of the file as text |
.hidden : boolean true if the file is set as "hidden" at the system level |
.isAlias : boolean true if the file is an alias, a shortcut, or a symbolic link |
.isFile : boolean always true for a file |
.isFolder : boolean always false for a file |
.isWritable : boolean true if the file exists on disk and is writable |
.modificationDate : date the date of the file's last modification |
.modificationTime : time the time of the file's last modification |
.moveTo( destinationFolder : 4D.Folder { , newName : string } ) : 4D.File moves or renames the file object into the specified destinationFolder |
.name : string the name of the file without extension (if any) |
.open( { mode : string } ) : 4D.FileHandle .open( { options : object } ) : 4D.FileHandle creates and returns a new 4D.FileHandle object on the file, in the specified mode or with the specified options |
.original : 4D.File .original : 4D.Folder the target element for an alias, a shortcut, or a symbolic link file |
.parent : 4D.Folder the parent folder object of the file |
.path : string the POSIX path of the file |
.rename( newName : string ) : 4D.File renames the file with the name you passed in newName and returns the renamed file object |
.setContent ( content : blob ) rewrites the entire content of the file using the data stored in the content blob |
.setText ( text : string {, charSetName : string { , breakMode : integer } } ) .setText ( text : string {, charSetNum : integer { , breakMode : integer } } ) writes text as the new contents of the file |
.size : number the size of the file expressed in bytes |
4D.File.new()
4D.File.new ( path : string ) : 4D.File
Description
The 4D.File.new()
function creates and returns a new object of the 4D.File
type. It is identical to the file
command (shortcut).
It is recommended to use the
file
shortcut command instead of4D.File.new()
.
.copyTo()
.copyTo( destinationFolder : 4D.Folder { , newName : string } { , overwrite : integer } ) : 4D.File
Parameter | Type | Description | |
---|---|---|---|
destinationFolder | 4D.Folder | → | Destination folder |
newName | string | → | Name for the copy |
overwrite | integer | → | kOverwrite to replace existing elements |
Result | 4D.File | ← | Copied file |
Description
The .copyTo()
function copies the file
object into the specified destinationFolder .
The destinationFolder must exist on disk, otherwise an error is generated.
By default, the file is copied with the name of the original file. If you want to rename the copy, pass the new name in the newName parameter. The new name must comply with naming rules (e.g., it must not contain characters such as ":", "/", etc.), otherwise an error is returned.
If a file with the same name already exists in the destinationFolder, by default 4D generates an error. You can pass the kOverwrite
constant in the overwrite parameter to ignore and overwrite the existing file
Constant | Value | Comment |
---|---|---|
kOverwrite | 4 | Overwrite existing elements, if any |
Returned value
The copied file
object.
Example
You want to copy a picture file from the user's document folder to the application folder:
var source, copy : 4D.File
source = file("/SOURCES/Shared/Pictures/photo.png")
copy = source.copyTo(folder("/PACKAGE"),kOverwrite)
.create()
Not available for ZIP archives
.create() : boolean
Parameter | Type | Description | |
---|---|---|---|
Result | boolean | ← | true if the file was created successfully, false otherwise |
Description
The .create()
function creates a file on disk according to the properties of the file
object.
if necessary, the function creates the folder hierachy as described in the path property. if the file already exists on disk, the function does nothing (no error is thrown) and returns false.
Returned value
- true if the file is created successfully,
- false if a file with the same name already exists or if an error occured.
Example
Creation of a preferences file in the project folder:
var created : boolean
created = File("/PACKAGE/SpecialPrefs/settings.myPrefs").create()
.createAlias()
.createAlias( destinationFolder : 4D.Folder , aliasName : string ) : 4D.File
Parameter | Type | Description | |
---|---|---|---|
destinationFolder | 4D.Folder | → | Destination folder for the alias or shortcut |
aliasName | string | → | Name of the alias or shortcut |
Result | 4D.File | ← | Alias or shortcut file reference |
Description
The .createAlias()
function creates a symbolic link to the file with the specified aliasName name in the folder designated by the destinationFolder object.
Pass the name of the symbolic link in the aliasName parameter.
Returned object
A 4D.File
object with the isAlias
property set to true.
Example
You want to create a symbolic link to a file in your resources folder:
myFile = file("/SOURCES/Shared/Archives/ReadMe.txt")
aliasFile = myFile.createAlias(file("/RESOURCES"),"ReadMe")
.delete()
.delete()
Parameter | Type | Description | |
---|---|---|---|
Does not require any parameters |
Description
The .delete()
function deletes the file.
if the file does not exist on disk, the function does nothing (no error is generated).
WARNING:
.delete()
can delete any file on a disk. This includes documents created with other applications, as well as the applications themselves..delete()
should be used with extreme caution. Deleting a file is a permanent operation and cannot be undone.
Example
You want to delete a specific file in the project folder:
var tempo : 4D.File
var info : string
tempo = file("PACKAGE/SpecialPrefs/settings.prefs")
if(tempo.exists)
tempo.delete()
info = "User preference file deleted."
end
.exists
.exists : boolean
Description
The .exists
property returns true if the file exists on disk, and false otherwise.
This property is read-only.
.extension
.extension : string
Description
The .extension
property returns the extension of the file name (if any). An extension always starts with ".". The property returns an empty string if the file name does not have an extension.
This property is read-only.
.fullName
.fullName : string
Description
The .fullName
property returns the full name of the file, including its extension (if any).
This property is read-only.
.getContent()
.getContent() : 4D.Blob
Parameter | Type | Description | |
---|---|---|---|
Result | 4D.Blob | ← | File content |
Description
The .getContent()
function returns a 4D.Blob
object containing the entire content of a file. For information on blobs, please refer to the blob section.
Returned value
A 4D.Blob
object.
Example
To save a document's contents in a Blob
attribute:
var myFile : 4D.File
var vEntity : cs.myClassEntity
myFile = file("/SOURCES/Shared/Archives/data.txt")
vEntity = ds.myClass.all().first() //get an entity
vEntity.infoBlob = myFile.getContent()
vEntity.save()
.getText()
.getText( { charSetName : string { , breakMode : integer } } ) : string
.getText( { charSetNum : integer { , breakMode : integer } } ) : string
Parameter | Type | Description | |
---|---|---|---|
charSetName | string | → | Name of character set |
charSetNum | integer | → | Number of character set |
breakMode | integer | → | Processing mode for line breaks |
Result | string | ← | String from the document |
Description
The .getText()
function returns the contents of the file as text.
Optionally, you can designate the character set to be used for reading the contents. You can pass either:
- in charSetName, a string containing the standard set name (for example "ISO-8859-1" or "UTF-8"),
- or in charSetNum, the MIBEnum ID (number) of the standard set name.
For the list of character sets supported by Qodly, refer to the description of the
convertFromText
command.
If the document contains a Byte Order Mark (BOM), Qodly uses the character set that it has set instead of the one specified in charSetName or charSetNum (this parameter is then ignored). If the document does not contain a BOM and if charSetName or charSetNum is omitted, by default Qodly uses the "UTF-8" character set.
In breakMode, you can pass a number indicating the processing to apply to end-of-line characters in the document. The following constants of the "System Documents" theme are available:
Constant | Value | Comment |
---|---|---|
kDocumentUnchanged | 0 | No processing |
kDocumentWithNativeFormat | 1 | (Default) Line breaks are converted to the native format of the operating system: CR (carriage return) under Unix, CRLF (carriage return + line feed) under Windows |
kDocumentWithCRLF | 2 | Line breaks are converted to Windows format: CRLF (carriage return + line feed) |
kDocumentWithCR | 3 | Line breaks are converted to OS X format: CR (carriage return) |
kDocumentWithLF | 4 | Line breaks are converted to Unix format: LF (line feed) |
By default, when you omit the breakMode parameter, line breaks are processed in native mode (1).
Returned value
Text of the file.
Example
Given the following text document (fields are separated by tabs):
id name price vat
3 thé 1.06€ 19.6
2 café 1.05€ 19.6
When you execute this code:
var myFile : 4D.File
var txt : string
myFile = file("/SOURCES/Shared/Billing.txt") //UTF-8 by default
txt = myFile.getText()
... you get the following for txt
:
"id\tname\tprice\tvat\r\n3\tthé\t1.06€\t19.6\r\n2\tcafé\t1.05€\t19.6"
with \t
(tab) as separator and \r\n
(CRLF) as line delimiter.
Here is another example with the same file, but a different line delimiter:
txt = myFile.getText("UTF-8", kDocumentWithLF)
In this case, the contents of txt
are as follows:
"id\tname\tprice\tvat\n3\tthé\t1.06€\t19.6\n2\tcafé\t1.05€\t19.6"
This time \n
(LF) is used as line delimiter.
.hidden
.hidden : boolean
Description
The .hidden
property returns true if the file is set as "hidden" at the system level, and false otherwise.
This property is read/write.
.isAlias
.isAlias : boolean
Description
The .isAlias
property returns true if the file is an alias, a shortcut, or a symbolic link, and false otherwise.
This property is read-only.
.isFile
.isFile : boolean
Description
The .isFile
property returns always true for a file.
This property is read-only.
.isFolder
.isFolder : boolean
Description
The .isFolder
property returns always false for a file.
This property is read-only.
.isWritable
.isWritable : boolean
Description
The .isWritable
property returns true if the file exists on disk and is writable.
The property checks the ability of the application to write on the disk (access rights), it does not solely rely on the writable attribute of the file.
This property is read-only.
Example
myFile = file("/SOURCES/Shared/Archives/ReadMe.txt")
if(myFile.isWritable)
myNewFile = myFile.setText("Added text")
end
.modificationDate
.modificationDate : date
Description
The .modificationDate
property returns the date of the file's last modification.
This property is read-only.
.modificationTime
.modificationTime : time
Description
The .modificationTime
property returns the time of the file's last modification (expressed as a number of seconds beginning at 00:00).
This property is read-only.
.moveTo()
.moveTo( destinationFolder : 4D.Folder { , newName : string } ) : 4D.File
Parameter | Type | Description | |
---|---|---|---|
destinationFolder | 4D.Folder | → | Destination folder |
newName | string | → | Full name for the moved file |
Result | 4D.File | ← | Moved file |
Description
The .moveTo()
function moves or renames the file
object into the specified destinationFolder.
The destinationFolder must exist on disk, otherwise an error is generated.
By default, the file retains its name when moved. if you want to rename the moved file, pass the new full name in the newName parameter. The new name must comply with naming rules (e.g., it must not contain characters such as ":", "/", etc.), otherwise an error is returned.
Returned object
The moved file
object.
Example
myFolder = folder("/SOURCES/Shared/Contents")
myFile = myFolder.file("Infos.txt")
myFile.moveTo(myFolder.folder("Archives"),"Infos_old.txt")
.name
.name : string
Description
The .name
property returns the name of the file without extension (if any).
This property is read-only.
.open()
.open( { mode : string } ) : 4D.FileHandle
.open( { options : object } ) : 4D.FileHandle
Parameter | Type | Description | |
---|---|---|---|
mode | string | → | Opening mode: "read", "write", "append" |
options | object | → | Opening options |
Result | 4D.FileHandle | ← | New File handle object |
Description
The .open()
function creates and returns a new 4D.FileHandle object on the file, in the specified mode or with the specified options. You can use functions and properties of the 4D.FileHandle class to write, read, or append contents to the file.
if you use the mode (string) parameter, pass the opening mode for the file handle:
mode | Description |
---|---|
"read" | (Default) Creates a file handle to read values from the file. if the file does not exist on disk, an error is returned. You can open as many file handles as you want in "read" mode on the same file object. |
"write" | Creates a file handle to write values to the file (starting at the beginning of the file content). if the file does not exist on disk, it is created. You can open only one file handle in "write" mode on the same file object. |
"append" | Creates a file handle to write values to the file (starting at the end of the file content). if the file does not exist on disk, it is created. You can open only one file handle in "append" mode on the same file object. |
The mode value is case sensitive.
If you use the options (object) parameter, you can pass more options for the file handle through the following properties (these properties can be read afterwards from the opened file handle object):
options | Type | Description | Default |
---|---|---|---|
.mode | string | Opening mode (see mode above) | "read" |
.charset | string | Charset used when reading from or writing to the file. Use the standard name of the set (for example "ISO-8859-1" or "UTF-8") | "UTF-8" |
.breakModeRead | string or number | Processing mode for line breaks used when reading in the file (see below) | "native" or 1 |
.breakModeWrite | string or number | Processing mode for line breaks used when writing to the file (see below) | "native" or 1 |
This function replaces all original end-of-line delimiters. The .breakModeRead
and .breakModeWrite
indicate the processing to apply to end-of-line characters in the document. You can use one of the following values (string or number):
Break mode as text | Break mode as number (constant) | Description |
---|---|---|
"native" | 1 (kDocumentWithNativeFormat ) | (Default) Line breaks are converted to the native format of the operating system: LF (line feed) under Unix and macOS, CRLF (carriage return + line feed) under Windows |
"crlf" | 2 (kDocumentWithCRLF ) | Line breaks are converted to CRLF (carriage return + line feed), the default Windows format |
"cr" | 3 (kDocumentWithCR ) | Line breaks are converted to CR (carriage return), the default Classic Mac OS format |
"lf" | 4 (kDocumentWithLF ) | Line breaks are converted to LF (line feed), the default Unix and macOS format |
The Break mode as text value is case sensitive.
Example
You want to create a file handle for reading the "ReadMe.txt" file:
var f : 4D.File
var fhandle : 4D.FileHandle
f = file("/SOURCES/ReadMe.txt")
fhandle = f.open("read")
.original
.original : 4D.File
.original : 4D.Folder
Description
The .original
property returns the target element for an alias, a shortcut, or a symbolic link file. The target element can be:
- a file object
- a folder object
For non-alias files, the property returns the same file object as the file.
This property is read-only.
.parent
.parent : 4D.Folder
Description
The .parent
property returns the parent folder object of the file. If the path represents a system path (e.g., "/DATA/"), the system path is returned.
This property is read-only.
.path
.path : string
Description
The .path
property returns the POSIX path of the file. If the path represents a filesystem (e.g., "/DATA/"), the filesystem is returned.
This property is read-only.
.rename()
.rename( newName : string ) : 4D.File
Parameter | Type | Description | |
---|---|---|---|
newName | string | → | New full name for the file |
Result | 4D.File | ← | Renamed file |
Description
The .rename()
function renames the file with the name you passed in newName and returns the renamed file
object.
The newName parameter must comply with naming rules (e.g., it must not contain characters such as ":", "/", etc.), otherwise an error is returned. if a file with the same name already exists, an error is returned.
Note that the function modifies the full name of the file, i.e. if you do not pass an extension in newName, the file will have a name without an extension.
Returned object
The renamed file
object.
Example
You want to rename "ReadMe.txt" in "ReadMe_new.txt":
toRename = file("/SOURCES/ReadMe.txt")
newName = toRename.rename(toRename.name+"_new"+toRename.extension)
.setContent()
.setContent ( content : blob )
Parameter | Type | Description | |
---|---|---|---|
content | blob | → | New contents for the file |
Description
The .setContent()
function rewrites the entire content of the file using the data stored in the content blob. For information on blobs, please refer to the Blob section.
Example
var myFile : 4D.File
var vEntity : cs.myClassEntity
myFile = "/SOURCES/Archives/data.txt")
vEntity = ds.myClass.all().first() //get an entity
myFile.setContent(vEntity.infoBlob)
vEntity.save()
.setText()
.setText ( text : string {, charSetName : string { , breakMode : integer } } )
.setText ( text : string {, charSetNum : integer { , breakMode : integer } } )
Parameter | Type | Description | |
---|---|---|---|
text | string | → | string to store in the file |
charSetName | string | → | Name of character set |
charSetNum | integer | → | Number of character set |
breakMode | integer | → | Processing mode for line breaks |
Description
The .setText()
function writes text as the new contents of the file.
if the file referenced in the file
object does not exist on the disk, it is created by the function. When the file already exists on the disk, its prior contents are erased, except if it is already open, in which case, its contents are locked and an error is generated.
In text, pass the text to write to the file. It can be a literal ("my text"), or a 4D text field or variable.
Optionally, you can designate the character set to be used for writing the contents. You can pass either:
- in charSetName, a string containing the standard set name (for example "ISO-8859-1" or "UTF-8"),
- or in charSetNum, the MIBEnum ID (number) of the standard set name.
For the list of character sets supported by Qodly, refer to the description of the
convertFromText
command.
if a Byte Order Mark (BOM) exists for the character set, Qoldy inserts it into the file unless the character set used contains the suffix "-no-bom" (e.g. "UTF-8-no-bom"). if you do not specify a character set, by default 4D uses the "UTF-8" character set without BOM.
In breakMode, you can pass a number indicating the processing to apply to end-of-line characters before saving them in the file. The following constants are available:
Constant | Value | Comment |
---|---|---|
kDocumentUnchanged | 0 | No processing |
kDocumentWithNativeFormat | 1 | (Default) Line breaks are converted to the native format of the operating system (line feed on Unix) |
kDocumentWithCRLF | 2 | Line breaks are converted to CRLF (carriage return + line feed), the default Windows format |
kDocumentWithCR | 3 | Line breaks are converted to CR (carriage return), the default Classic Mac OS format |
kDocumentWithLF | 4 | Line breaks are converted to LF (line feed), the default Unix and macOS format |
By default, when you omit the breakMode parameter, line breaks are processed in native mode (1).
Example
var myFile : 4D.File
myFile = file("/SOURCES/Hello.txt")
myFile.setText("Hello world")
.size
.size : number
Description
The .size
property returns the size of the file expressed in bytes. If the file does not exist on disk, the size is 0.
This property is read-only.