File

Purpose¶

Since 6.10.7

Enables the writing, reading, and manipulation of files and directories.

Intended to replace the use of FileUtils Methods, examples allow comparison to legacy implementations.

Optional params are provided using a closure, else defaults will be used.

Methods¶

Binding name: p6.file

write¶

Write a String or Byte Array to a file.
Returns true on completion without error.

Optional params:

^{Params: String - charset, Boolean - append, Boolean - override}
^{Default: charset = UTF-8, append = false, override = true}

override determines if an existing file should be overwritten.
append determines if the provided data should be appended to contents of an existing file.

Syntax

Boolean p6.file.write String data to String filepath

Boolean p6.file.write byte[] data to String filepath

Example

NewLegacy

def data = “data content”
// OR
def data = [0, 0, 0, 0, 0] as byte[]

p6.file.write data to 'Path/To/File.txt'
p6.file.write data to 'Path/To/File.txt', {
charset 'UTF-8'
append true
}

// Write a string
FileUtils.writeStringToFile(data, new File('Path/To/File.txt'));
// Write a byte array
FileUtils.writeByteArrayToFile(data, new File('Path/To/File.txt'));
// Append a string
FileUtils.writeStringToFile(data, new File('Path/To/File.txt', true));

readText¶

Read the contents of a file as a String.

optional params:

^{Params: String - charset}
^{Default: charset = UTF-8}

Syntax

String p6.file.readText String filepath

Example

NewLegacy

String fileContents = p6.file.readText 'Path/To/File.txt' 
// With custom Charset
String fileContents = p6.file.readText 'Path/To/File.txt', {charset 'UTF-16'}

String fileText = FileUtils.readFileToString(new File('Path/To/File.txt'))
// With custom Charset
String fileText = FileUtils.readFileToString(new File('Path/To/File.txt'), 'UTF-16')

readJson¶

Read the contents of a file as a JSON object. As if as using a JsonSlurper.

Optional params:

^{Params: String - charset}
^{Default: charset = UTF-8}

Syntax

Object p6.file.readJson String filepath

Example

NewLegacy

def fileContents = p6.file.readJson 'Path/To/File.txt'
// With custom Charset
String fileContents = p6.file.readJson 'Path/To/File.txt', {charset 'UTF-16'}

String fileText = FileUtils.readFileToString(new File('Path/To/File.txt'))
// Or if with custom charset
String fileText = FileUtils.readFileToString(new File('Path/To/File.txt'), 'UTF-16')
// Then 
def fileContents = new JsonSlurper().parseText(fileText)

readXml¶

Read the contents of a file as a GPathResult object. As if using an XmlSlurper. Allows use of non-default XmlSlurper by specifying behaviour for validation, namespace-awareness, and Doctype declaration.

Optional params:

^{Params: String - charset, Boolean - validating, Boolean - namespaceAware, Boolean - allowDocTypeDeclaration}
^{Default: charset = UTF-8, validating = false, namespaceAware = true, allowDocTypeDeclaration = false, features = null}

Syntax

GPathResult p6.file.readXml String filepath

Example

NewLegacy

GPathResult fileContents = p6.file.readXml 'Path/To/File.txt'
// Or if with custom charset
GPathResult fileContents = p6.file.readXml 'Path/To/File.txt', {charset 'UTF-16'}
// To specify alternate behaviour
GPathResult fileContents = p6.file.readXml 'Path/To/File.txt', {
    validating true
    namespaceAware false
    allowDocTypeDeclaration true
}
// To use the setFeature method
Map<String, Boolean> featuresToSet = ['Feature1': false, 'feature2': true]
GPathResult fileContents = p6.file.readXml 'Path/To/File.txt', {
    features featuresToSet
}

String fileText = FileUtils.readFileToString(new File('Path/To/File.txt'))
// Or if with custom charset
String fileText = FileUtils.readFileToString(new File('Path/To/File.txt'), 'UTF-16')
// Then 
GPathResult fileContents = new XmlSlurper().parseText(fileText)

readToBase64¶

Read the contents of a file as a base64 encoded String.

Optional params:

^{Params: String - charset}
^{Default: charset = UTF-8}

Syntax

String p6.file.readBase64 String filepath

Example

NewLegacy

String fileContents = p6.file.readBase64 'Path/To/File.txt'
// Or if with custom charset
String fileContents = p6.file.readBase64 'Path/To/File.txt', {charset 'UTF-16'}

byte[] fileBytes = FileUtils.readFileToByteArray(new File('Path/To/File.txt'))
// Or if with custom charset
byte[] fileBytes = FileUtils.readFileToByteArray(new File('Path/To/File.txt'), 'UTF-16')
// Then
byte[] encodedBytes = Base64.encodeBase64(fileBytes);
String fileContents = new String(encodedBytes, charset)

move¶

Moves the File or Folder from source location to destination.
Returns true on completion without error.
Will error if destination file/folder exists unless override is set to true.

Optional params:

^{Params: Boolean - override}
^{Default: override = false}

Syntax

Boolean p6.file.move String source to String destination

Example

NewLegacy

p6.file.move 'Path/To/sourceFile.txt' to 'Path/To/destFile.txt'
// Or to change override behaviour
p6.file.move 'Path/To/sourceFile.txt' to 'Path/To/destFile.txt', {override true}

// For file
FileUtils.moveFile('Path/To/File.txt', 'Path/To/destFile.txt')
// For directory
FileUtils.moveDirectory('Path/To/SourceDirectory', 'Path/To/DestDirectory')
// To overwrite existing
FileUtils.moveFile('Path/To/File.txt', 'Path/To/destFile.txt', StandardCopyOption.REPLACE_EXISTING)

copy¶

Copies the File or Folder from source location to destination.
Returns true on completion without error.

Optional params:

^{Params: Boolean - override}
^{Default: override = true}

Syntax

Boolean p6.file.copy String source to String destination

Example

NewLegacy

p6.file.copy 'Path/To/sourceFile.txt' to 'Path/To/destFile.txt'
// Or to change override behaviour
p6.file.copy 'Path/To/sourceFile.txt' to 'Path/To/destFile.txt', {override true}

// For file
FileUtils.copyFile('Path/To/File.txt', 'Path/To/destFile.txt')
// For directory
FileUtils.copyDirectory('Path/To/SourceDirectory', 'Path/To/DestDirectory')
// No override equivalent for  FileUtils copy methods, legacy would check for existing files and not copy if they exist

delete¶

Deletes the File or Folder at filepath given.
Returns true on completion without error.

Syntax

Boolean p6.file.delete String source

Example

NewLegacy

p6.file.delete 'Path/To/File.txt'

// For file
FileUtils.deleteFile('Path/To/File.txt')
// For directory
FileUtils.deleteDirectory('Path/To/Directory')

cleanFolder¶

Empties the contents of a directory. Canonical to deleting, and recreation of the folder.

Syntax

Boolean p6.file.cleanFolder 'Path/To/Folder'

Example

p6.file.cleanFolder 'Path/To/Folder'

permissions¶

Since 6.10.8

Set the permissions of a file or directory. When setting permissions on a directory, the recursive parameter can be used to set permissions on all files and directories within the directory.

Syntax

Boolean p6.file.permissions 'Path/To/Folder', { perms 'rwxr-xr-x' }

Example

p6.file.permissions 'Path/To/Folder', { perms 'rwxr-xr-x' }
p6.file.permissions 'Path/To/Folder', { perms 'rwxr-xr-x'; recursive false}
p6.file.permissions 'Path/To/Folder/File', { perms 'rwxr-xr-x'}

Tip

The perms parameter must be a valid Unix permission string. For more information on Unix permission strings, refer to this guide. The recursive parameter is optional and defaults to true.

Examples¶

To append the string “appended string” to the contents of a file, in charset UTF-16

Example

p6.file.write 'appended string' to 'Path/To/File.txt', {
charset 'UTF-16'
append true
}

To move a file, overwriting any existing file.

Example

p6.file.move 'Path/To/SourceFile.txt' to 'Path/To/DestFile.txt', {override true}

To copy a file, without overwriting any existing file.

Example

p6.file.copy 'Path/To/SourceFile.txt' to 'Path/To/DestFile.txt', {override false}