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 of 4D.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("/RESOURCES/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("/RESOURCES/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("/RESOURCES/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("/RESOURCES/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("/RESOURCES/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("/RESOURCES/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.

Example​

Pathnames​

Functions and properties​

4D.File.new()​

Description​

.copyTo()​

Description​

Example​

.create()​

Description​

Example​

.createAlias()​

Description​

Example​

.delete()​

Description​

Example​

.exists​

Description​

.extension​

Description​

.fullName​

Description​

.getContent()​

Description​

Example​

.getText()​

Description​

Example​

.hidden​

Description​

.isAlias​

Description​

.isFile​

Description​

.isFolder​

Description​

.isWritable​

Description​

.modificationDate​

Description​

.modificationTime​

Description​

.moveTo()​

Description​

Example​

.name​

Description​

.open()​

Description​

Example​

.original​

Description​

.parent​

Description​

.path​

Description​

.rename()​

Description​

Example​

.setContent()​

Description​

Example​

.setText()​

Description​

Example​

.size​

Description​

Example

Pathnames

Functions and properties

4D.File.new()

Description

.copyTo()

Description

Example

.create()

Description

Example

.createAlias()

Description

Example

.delete()

Description

Example

.exists

Description

.extension

Description

.fullName

Description

.getContent()

Description

Example

.getText()

Description

Example

.hidden

Description

.isAlias

Description

.isFile

Description

.isFolder

Description

.isWritable

Description

.modificationDate

Description

.modificationTime

Description

.moveTo()

Description

Example

.name

Description

.open()

Description

Example

.original

Description

.parent

Description

.path

Description

.rename()

Description

Example

.setContent()

Description

Example

.setText()

Description

Example

.size

Description