There are several ways of using this plugin: There is a low-level library interface which provides dedicated functions for dealing with archives, e.g. xad.OpenArchive() to open an archive and xad.ExtractFile() to extract a file. The low-level interface is a bit more difficult to use than the high-level interface but offers the greatest level of control over archives and also the best performance.
Additionally, xad.hwp has a high-level interface which allows your script to deal with
archives without having to learn any kind of new APIs. Instead, you can just use normal
Hollywood functions to access archives. There are two ways of using the high-level interface:
You can either activate the plugin globally by setting the InstallAdapter tag to True when
@REQUIRE-ing it (not recommended, see below) or you can manually tell Hollywood functions
that deal with files to use the plugin by setting the Adapter tag when you call those
functions (recommended, see below).
To activate the plugin globally, you must set InstallAdapter to True when you @REQUIRE the
plugin, e.g. like this:
@REQUIRE "xad", {InstallAdapter = True}
|
If you activate the high-level interface by setting InstallAdapter to True, it will become globally available
and all ensuing commands that deal with files will support the opening of files from archive
sources. For example, you could do something like this then:
LoadBrush(1, "test.rar/pic.jpg") |
If the archive is protected with a password, you can use Hollywood user tags to forward the password to the XAD plugin like this:
LoadBrush(1, "test.rar/pic.jpg", {UserTags = {Password = "123456"}})
|
Note that setting InstallAdapter to True comes with significant overhead because all functions that
deal with files and directories will first be routed through the XAD plugin so that it can
check if the specified file is in an archiver format that the plugin can handle. This means
that file IO becomes slower because all file IO first goes through the XAD plugin. This is
why it's not recommended to set InstallAdapter to True. Instead, you should omit the InstallAdapter
tag on @REQUIRE and simply use the Adapter tag offered by most Hollywood commands instead
to tell the respective Hollywood command to open the file using the XAD plugin. Here is an example:
LoadBrush(1, "test.rar/pic.jpg", {Adapter = "xad"})
|
By using the Adapter tag, LoadBrush() is told to open the specified file using
the specified adapter, which is "xad" in our case. Thus, the Adapter tag
allows you to use this plugin even without having installed a global file adapter for
it first.
The same is true for Hollywood functions dealing with directories. If the XAD plugin has been globally activated, it is possible to do things like the following:
OpenDirectory(1, "test.rar") |
You could then iterate over all files and directories in test.rar. If you haven't
activated a global adapter for xad.hwp, then just use the Adapter like above, e.g.
OpenDirectory(1, "test.rar", {Adapter = "xad"})
|
You can also query the #ATTRFORMAT tag for files or directories opened by the XAD plugin to
find out the archiver format used by the file, e.g.
OpenDirectory(1, "test.rar", {Adapter = "xad"})
DebugPrint(GetAttribute(#DIRECTORY, 1, #ATTRFORMAT))
|
The code above will print "RAR" because test.rar is a RAR archive.
See the next chapter for more details on treating archives supported by the XAD system as directories.