Version: 1.0.0

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

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().

.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

.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")

.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")

.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")

Example​

Pathnames​

Functions and properties​

4D.File.new()​

Description​

.create()​

Description​

Example​

.createAlias()​

Description​

Example​

.delete()​

Description​

Example​

.moveTo()​

Description​

Example​

.open()​

Description​

Example​

.rename()​

Description​

Example​

.setContent()​

Description​

Example​

.setText()​

Description​

Example​

Example

Pathnames

Functions and properties

4D.File.new()

Description

.create()

Description

Example

.createAlias()

Description

Example

.delete()

Description

Example

.moveTo()

Description

Example

.open()

Description

Example

.rename()

Description

Example

.setContent()

Description

Example

.setText()

Description

Example