Keyword Index

Object: SPZip

This object lets you create, add to, and extract from standard Zip archive files. An object of this class is created by calling the top-level function SPZip.

  • add - Adds files to the Zip archive.
  • addRecursive - Adds files recursively to the Zip archive.
  • extract - Extracts files from the zip archive.
  • getFileList - Gets a list of the files contained in the Zip archive.
    •

    Method: add

    Adds files to the Zip archive.

    void add(list);

    void add(list, rootDir);

    Parameters
    Name Expected Type Description
    list String List of files to add. See below.
    rootDir String The root directory. If this is specified, the file specifications in "list" are relative to this directory and the path stored in the archive will be relative to this directory.

    Remarks:

    If the archive already exists, this method adds the specified files, replacing any existing files with the same name. If the archive doesn't exist, it is created. If you wish to create a completely new archive, replacing any existing one with the same name, you must use the Script.deleteFile function first.

    Specifying File Names

    Filenames should be specified with absolute paths, i.e. starting with the disk or server name. Relative paths will be accepted, but they depend on the system's notion of "current directory", which may change unpredictably. Wildcards are allowed, see below. If absolute paths are supplied, the entire path, except for the drive letter and : character, will be stored in the Zip file.

    Adding Multiple Files

    Multiple files can be specified by separating them with commas or line terminators. To include commas in the name, or for clarity, names can be enclosed in single or double quotes. Arrays of file names returned by functions like getFileList can be passed to add since they are automatically separated by line terminators when converted to strings.

    Including and Excluding Files

    Files can be explicitly excluded or included from the files in the list. To use this feature, first specify all the files and wildcards you want to process, then specify files to include or exclude among the files to process already specified. To exclude certain files, place a < symbol before the filename or wildcard expression to exclude, and add it to the list. To include only certain files, place a > symbol before the filename or wildcard expression. The include or exclude feature may only be used if the list contains at least one filename or wildcard expression without the < or > symbols. The include feature applies primarily when using addRecursive, since it allows you to specify all directories, but filter out only a specific file type within those directories.

    Wildcards

    The add method supports the * and ? wildcard characters. The * character matches a sequence of 0 or more characters. The ? character matches exactly one character. Using * will match all the files and subdirectories encountered. Using *.* will only match files and directories that contain a . in them. The add method is not recursive, that is, it zips only the contents of the specified directory, not any subdirectories it may contain. Use the addRecursive method to add files recursively.

    Example:

    z = SPZip("c:/backups/project.zip");          // Specify the zip file

// "d:/project/*" says add everything inside folder "project".
// "<*.obj" says exclude all files matching *.obj.
// "<*.pch" says exclude all files matching *.pch.

z.add("d:/project/*,<*.obj,<*.pch");

    Method: addRecursive

    Adds files recursively to the Zip archive.

    void addRecursive(list);

    Parameters
    Name Expected Type Description
    list String

    Remarks:

    This method is identical to add except that it adds files in all subdirectories encountered recursively. This only applies when wildcards are specified in the file list. See the comments on file list format under add.

    Example:

    z = SPZip("c:/backups/text.zip");         // Specify the zip file

// "d:/documents/*" says add everything inside folder "documents".
// ">*.txt,>*.rtf" says include only files matching *.txt and *.rtf.

z.addRecursive("d:/documents/*,>*.txt,>*.rtf");

    Method: extract

    Extracts files from the zip archive.

    void extract(destDir);

    void extract(destDir, names);

    Parameters
    Name Expected Type Description
    names String The names of the files to be extracted. The same rules for syntax and wildcard usage apply here as for add, except that the exclude feature is not allowed. If this is not specified, all files are extracted.
    destDir String The full path name of the destination directory for the files extracted. Note that any path name stored in the archive will be used starting at this location.

    Method: getFileList

    Gets a list of the files contained in the Zip archive.

    SPArray getFileList();

    Returns:

    Returns an array of SPFile objects representing the files in the archive.

    Remarks:

    IMPORTANT: In this version, the SPFile objects returned can only be used for extracting name and status information regarding the files in the archive. No operations (e.g. read, write, delete) are allowed on these objects. This may be added in a future version.