Package ortus.boxlang.runtime.components.zip

Class Zip

java.lang.Object
ortus.boxlang.runtime.components.Component
ortus.boxlang.runtime.components.zip.Zip
@BoxComponent(allowsBody=true, alias="gzip") public class Zip extends Component
This component allows you to compress/uncompress and manipulate zip/gzip files

  • Constructor Details

    • Zip

      public Zip()
      Constructor

  • Method Details

    • _invoke

      public Component.BodyResult _invoke(IBoxContext context, IStruct attributes, Component.ComponentBody body, IStruct executionState)
      The BoxLang Zip component is a powerful component that allows you to interact with zip/gzip files. You can compress/uncompress files, list the contents of a zip file, read the contents of a file inside a zip file (text or binary), and delete files from a zip file.

      Actions

      The Zip component has the following actions:
      • delete: Delete a file from a zip file
      • list: List the contents of a zip file
      • read: Read the contents of a file inside a zip file
      • readBinary: Read the contents of a binary file inside a zip file
      • unzip: Uncompress a zip file
      • zip: Compress files into a zip file

      Attributes

      The Zip component has the following attributes:
      • action: The action to take: delete, list, read, readBinary, unzip, zip (default)
      • file: Absolute filepath to the zip/gzip file to be manipulated. Actions: list, read, readBinary, unzip, zip
      • destination: Absolute destination directory where the zip/gzip file will be to. If it doesn't exist it will be created for you. Actions: unzip
      • filter: This can be a regular expression (*.txt) or a BoxLang Closure/Lambda ((path) => path.endsWith(".txt")) that will be used to filter the files. Actions: delete, list, unzip, zip
        • The closure/lambda should return true to extract/compress/zip/list the entry and false to skip it.
        • The closure/lambda should take a single argument which is the entry path.
        • The regular expression is done in a case-insensitive manner.
      • entryPath: Zip entry path or an array of entry paths on which the action is performed. Actions: delete, list, read, readBinary, unzip
        • Can be a single path string.
        • Can be an array of paths which applies to multiple entry paths. Does not apply to read, readBinary
        • Can be used to ONLY include in a listing the entries that match the entry path. The full path must be used
        • Can be used to ONLY delete the entries that match the entry path. The full path must be used
        • If the action is @{code read or readBinary} and you use an entry path, then a variable attribute must also be used to store the contents.
      • charset: Valid Java Charset to use when reading the contents of a file inside a zip file. Default is the machine's default charset. Actions: read, readBinary
      • result: The name of the variable to store the result in when doing a list operation on. If not provided, we will use bxzip. The result is an array of structs. Actions: list
        • fullpath: The full path of the entry: e.g. "folder1/folder2/file.txt"
        • name: The file name of the entry: e.g. "file.txt"
        • directory: The directory containing the entry: e.g. "folder1/folder2"
        • size: The size of the entry in bytes
        • compressedSize: The compressed size of the entry in bytes
        • type: The type of the entry: file or directory
        • dateLastModified: The date the entry was last modified
        • crc: The CRC checksum of the entry
        • comment: The comment of the entry
        • isEncrypted: Whether the entry is encrypted
        • isCompressed: Whether the entry is compressed
        • isDirectory: Whether the entry is a directory
      • overwrite: Whether to overwrite the destination file(s) if it already exists when zipping/unzipping. Default is false. Actions: zip, unzip
      • prefix: The prefix to add to the files when zipping files, this is the directory name to store files in. Not used by default. Actions: zip
      • recurse: Whether to recurse into subdirectories when listing/zipping/unzipping. Default is true. Actions: list, zip, unzip
      • flatList: If false, the list action will return an array of structs with all kinds of information about the entries. If true, it will return a flat list of strings with the path of the entries. Default is false. Actions: list
      • source: The absolute path to the source directory to be zipped. Actions: zip

      Delete Action

      The delete action allows you to delete entries from a zip file. You can delete a single entry or multiple entries.

      Attributes

      • file: Absolute filepath to the zip/gzip file to be manipulated
      • entryPath: Zip entry path or an array of entry paths on which the action is performed. Can also be used with a filter attribute
      • filter: This can be a regular expression (*.txt) or a BoxLang Closure/Lambda ((path) => path.endsWith(".txt")) that will be used to filter the files
      • recurse: Whether to recurse into subdirectories when listing/zipping/unzipping. Default is true

      Example: 

       // Using entries
 zip action="delete" file="/path/to/file.zip" entryPath="folder1/folder2/file.txt";
 // Using filters
 zip action="delete" file="/path/to/file.zip" filter="*.txt";

      List Action

      The list action allows you to list the contents of a zip file. You can list all entries or filter the entries using a regular expression or a closure/lambda. The list action can return a flat list of strings with the path of the entries or an array of structs with all kinds of information about the entries.

      Attributes

      • file: Absolute filepath to the zip/gzip file to be manipulated
      • filter: This can be a regular expression (*.txt) or a BoxLang Closure/Lambda ((path) => path.endsWith(".txt")) that will be used to filter the files
      • recurse: Whether to recurse into subdirectories when listing. Default is true
      • flatList: If false, the list action will return an array of structs with all kinds of information about the entries. If true, it will return a flat list of strings with the path of the entries. Default is false
      • result: The name of the variable to store the result in when doing a list operation on. If not provided, we will use bxzip. The result is an array of structs

      Struct Entry

      Each entry will be a struct with the following keys:

      • fullpath: The full path of the entry: e.g. "folder1/folder2/file.txt"
      • name: The file name of the entry: e.g. "file.txt"
      • directory: The directory containing the entry: e.g. "folder1/folder2"
      • size: The size of the entry in bytes
      • compressedSize: The compressed size of the entry in bytes
      • type: The type of the entry: file or directory
      • dateLastModified: The date the entry was last modified
      • crc: The CRC checksum of the entry
      • comment: The comment of the entry
      • isEncrypted: Whether the entry is encrypted
      • isCompressed: Whether the entry is compressed
      • isDirectory: Whether the entry is a directory

      Example: 

       // List all entries
 zip action="list" file="/path/to/file.zip";
 // List all entries that end with .txt
 zip action="list" file="/path/to/file.zip" filter="*.txt";
 // List all entries that end with .txt and store the result in a variable called myZip
 zip action="list" file="/path/to/file.zip" filter="*.txt" result="myZip";
 // List all entries that end with .txt and return a flat list of strings
 zip action="list" file="/path/to/file.zip" filter="*.txt" flatList="true";

      Read Action

      The read action allows you to read the contents of a file inside a zip file. You can read the contents of a text file only. If you want to read the contents of a binary file, use the readBinary action.

      Attributes

      • file: Absolute filepath to the zip/gzip file to be read
      • entryPath: Zip entry path to read the content
      • charset: Valid Java Charset to use when reading the contents of a file inside a zip file. Default is the machine's default charset
      • variable: The name of the variable to store the read content in

      Example: 

       // Read the contents of a file inside a zip file to a variable called bxzip
 zip action="read" file="/path/to/file.zip" entryPath="folder1/folder2/file.txt";
 // Read the contents of a file inside a zip file and store the result in a variable called myContent
 zip action="read" file="/path/to/file.zip" entryPath="folder1/folder2/file.txt" variable="myContent";

      ReadBinary Action

      The readBinary action allows you to read the contents of a binary file inside a zip file to a variable.

      Attributes

      • file: Absolute filepath to the zip/gzip file to be read
      • entryPath: Zip entry path to read the content
      • variable: The name of the variable to store the binary content in

      Example: 

       // Read the contents of a binary file inside a zip file to a variable called bxzip
 zip action="readBinary" file="/path/to/file.zip" entryPath="folder1/folder2/file.jpg";
 // Read the contents of a binary file inside a zip file and store the result in a variable called myContent
 zip action="readBinary" file="/path/to/file.zip" entryPath="folder1/folder2/file.jpg" variable="myContent";

      Unzip Action

      The unzip action allows you to uncompress a zip file. You can uncompress the entire zip file or filter the entries using a regular expression or a closure/lambda. If the destination directory does not exist, it will be created for you.

      Attributes

      • file: Absolute filepath to the zip/gzip file to be unzipped
      • destination: Absolute destination directory where the zip/gzip file will be extracted
      • filter: This can be a regular expression (*.txt) or a BoxLang Closure/Lambda ((path) => path.endsWith(".txt")) that will be used to filter the files
      • entryPath: Zip entry path or an array of entry paths on which the action is performed. Can also be used with a filter attribute
      • overwrite: Whether to overwrite the destination file(s) if it already exists when unzipping. Default is false
      • recurse: Whether to recurse into subdirectories when unzipping. Default is true

      Example: 

       // Uncompress the entire zip file
 zip action="unzip" file="/path/to/file.zip" destination="/path/to/destination";
 // Uncompress the entire zip file and overwrite the destination files
 zip action="unzip" file="/path/to/file.zip" destination="/path/to/destination" overwrite="true";
 // Uncompress the entire zip file and overwrite the destination files and recurse into subdirectories
 zip action="unzip" file="/path/to/file.zip" destination="/path/to/destination" overwrite="true" recurse="false";
 // Uncompress the entire zip file and overwrite the destination files and recurse into subdirectories and filter the entries
 zip action="unzip" file="/path/to/file.zip" destination="/path/to/destination" overwrite="true" recurse="true" filter="*.txt";
 // Uncompress using a lambda filter
 zip action="unzip" file="/path/to/file.zip" destination="/path/to/destination" filter="(path) -> path.endsWith('.txt')";

      Zip Action

      The zip action allows you to compress files into a zip file. You can compress the entire source directory or filter the entries using a regular expression or a closure/lambda.

      Attributes

      • file: Absolute filepath to the zip/gzip file to be created
      • source: The absolute path to the source directory to be zipped
      • filter: This can be a regular expression (*.txt) or a BoxLang Closure/Lambda ((path) => path.endsWith(".txt")) that will be used to filter the files
      • overwrite: Whether to overwrite the destination file(s) if it already exists when zipping. Default is false
      • prefix: The prefix to add to the files when zipping files, this is the directory name to store files in. Not used by default
      • recurse: Whether to recurse into subdirectories when zipping. Default is true

      Example: 

       // Compress the entire source directory
 zip action="zip" file="/path/to/file.zip" source="/path/to/source";
 // Compress the entire source directory and overwrite the destination files
 zip action="zip" file="/path/to/file.zip" source="/path/to/source" overwrite="true";
 // Compress the entire source directory and overwrite the destination files and recurse into subdirectories
 zip action="zip" file="/path/to/file.zip" source="/path/to/source" overwrite="true" recurse="false";
 // Compress the entire source directory and overwrite the destination files and recurse into subdirectories and filter the entries
 zip action="zip" file="/path/to/file.zip" source="/path/to/source" overwrite="true" recurse="true" filter="*.txt";
 // Compress using a lambda filter
 zip action="zip" file="/path/to/file.zip" source="/path/to/source" filter="(path) -> path.endsWith('.txt')";
      Specified by:
      _invoke in class Component
      Parameters:
      context - The context in which the Component is being invoked
      attributes - The attributes to the Component
      body - The body of the Component
      executionState - The execution state of the Component
      Returns:
      The result of the invocation