File Plugin

Overview

The file plugin provides a number of methods that help you deal with files and archives.

LATEST VERSION: 0.3.0

Loading the plugin

Here is how you load this plugin:

file = loadPlugin(id: "org.lattejava.plugin:file:0.3.0")

FileSets

Most of the methods on the file plugin use FileSets to identify files. The fileSet and optionalFileSet methods allow you to specify files that are either required or optional. If a required FileSet references a dir that doesn’t exist, an exception will be thrown.

You can also reduce a FileSet by supplying it with a list of patterns to include or exclude. These patterns are Regular Expressions (NOT Ant style expressions). These are specified via the includePatterns and excludePatterns parameters.

Here are the attributes you can supply to FileSets:

ArchiveFileSet

The tar and zip methods allow you to supply specialized FileSets to provide more information about how files and directories are stored inside TAR and ZIP files. Here are the attributes you can supply to the ArchiveFileSet:

Filter definitions

Some methods on this plugin also take Filter definitions. A filter consists of a token and a value. The token is replaced with the value for operations like rename or filtering while copying.

Here are the attributes you can supply to Filter definitions:

Appending to a file

The append method allows you to append the contents of files to another file. It takes 1 or more FileSets inside its closure. It also takes these parameters:

Here is an example of calling this method:

file.append(to: "some-file.txt") {
  fileSet(dir: "src/main/text-files", includePatterns: [~/.+.txt/])
}

Copying files

The copy method on the file plugin allows you to copy files between directories. This method takes one or more FileSets inside its closure. It also takes these parameters:

Here is an example of using this method:

file.copy(to: "build/distributions/bin") {
  fileSet(dir: "src/main/scripts")
}

This copies all the files (recursively) from the src/main/scripts directory to the build/distributions/bin directory.

Here’s an example that only copies a specific set of files.

file.copy(to: "build/distributions/bin") {
  fileSet(dir: "src/main/scripts", includePatterns: [/.*\.sh/])
}

This copies all the files (recursively) from the src/main/scripts directory with an extension of .sh to the build/distributions/bin directory.

You can also filter text inside files while copying. To do this, you supply one or more filter definitions inside the closure. Here is an example of using filters:

file.copy(to: "build/distributions/bin") {
  fileSet(dir: "src/main/scripts", includePatterns: [/.*\.sh/])
  filter(token: "%VERSION%", value: "${project.version}")
}

Copy a single file

The copyFile allows you to copy a single file to another location. It takes these parameters:

Here is an example of calling this method:

file.copyFile(file: "some-file.txt", to: "build/some-file-renamed.txt")

Deleting files

The delete method allows you to delete zero or more files. It takes one or more FileSets inside its closure. Here is an example of calling this method:

file.delete {
  fileSet(dir: "build/example", includePatterns: [~/foobar.+/])
}

Jarring files

The jar method on the file plugin allows you to create Jar files. It takes one or more FileSets inside its closure. It also takes these parameters:

Here is an example of using this method:

file.jar(file: "build/jars/foobar.jar") {
  fileSet(dir: "src/main/java")
  optionalFileSet(dir: "build/output")
}

This adds all the files in the src/main/java directory to the jar file build/jars/foobar.jar. It also optionally adds all the files from the build/output directory to the jar file if that directory exists.

Making a directory

The mkdir allows you to create a directory. It takes these parameters:

Here is an example of calling this method:

file.mkdir(dir: "build/test")

Pruning

The prune method on the file plugin allows you to delete a directory and everything inside it. It takes these parameters:

Here is an example of using this method:

file.prune(dir: "build/classes/main")

NOTE: This method correctly handles symlinks by removing the link. This DOES NOT traverse symlinks.

Renaming files

The rename method allows you to rename multiple files at the same time. This takes one or more FileSets inside its closure. It renames files based on one or more Filter definitions that are also provided inside the closure. Here is an example of calling this method:

file.rename {
  fileSet(dir: "build/classes/main")
  filter(token: "foobar", value: "baz")
}

Creating symlinks

The symlink method allows you to create symlinks. You almost never need to unlink a symlink because Latte almost never traverses symlinks. This method takes these parameters:

Here is an example of calling this method:

file.symlink(target: "build/classes/main", link: "/tmp/foo/bar")

Tarring files

The tar method on the file plugin allows you to create Tarballs. This method takes these parameters:

Here is an example of using this method:

file.tar(file: "build/tars/foobar.tar.gz", compress: true) {
  fileSet(dir: "src/main/java")
}

You can also supply ArchiveFileSets to the tar method. These are called tarFileSets. Here is an example of using tarFileSets:

file.tar(file: "build/tars/foobar.tar.gz", compress: true) {
  tarFileSet(dir: "src/main/java", prefix: "/usr/local/foobar", mode: 0x744, userName: "root", groupName: "root")
}

Unjar files

The unjar method allows you to extract a JAR file. This method takes these parameters:

Here is an example of calling this method:

file.unjar(file: "build/jars/foobar.jar", to: "build/output")

Untar files

The untar method allows you to extract a TAR file. This method takes these parameters:

Here is an example of calling this method:

file.untar(file: "build/tars/foobar.tar.gz", to: "build/output")

Unzip files

The unzip method allows you to extract a ZIP file. This method takes these parameters:

Here is an example of calling this method:

file.unzip(file: "build/zips/foobar.zip", to: "build/output")

Zipping files

The zip method on the file plugin allows you to create ZIP files. The files in the ZIP retain the mode of the original file, but not the owner and group. This method takes these parameters:

Here is an example of using this method:

file.zip(file: "build/zips/foobar.zip") {
  fileSet(dir: "src/main/java")
}

You can also supply ArchiveFileSets to the zip method. These are called zipFileSets. Here is an example of using zipFileSets:

file.zip(file: "build/zips/foobar.zip") {
  zipFileSet(dir: "src/main/java", prefix: "/usr/local/foobar", mode: 0x744)
}