archive.pl -- Access several archive formats
This library uses libarchive to access a variety of archive formats. The following example lists the entries in an archive:
list_archive(File) :- archive_open(File, Archive, []), repeat, ( archive_next_header(Archive, Path) -> format('~w~n', [Path]), fail ; !, archive_close(Archive) ).
Here is another example which counts the files in the archive and prints file type information. It uses archive_foldl/4, a higher level predicate:
print_entry(Path, Handle, Cnt0, Cnt1) :- archive_header_property(Handle, filetype(Type)), format('File ~w is of type ~w~n', [Path, Type]), Cnt1 is Cnt0 + 1. list_archive(File) :- archive_foldl(print_entry, File, 0, FileCount), format('We have ~w files', [FileCount]).
- archive_open(+Data, -Archive, +Options) is det
- Wrapper around archive_open/4 that opens the archive in read mode.
- archive_open(+Data, +Mode, -Archive, +Options) is det
- Open the archive in Data and unify Archive with a handle to the
opened archive. Data is either a file or a stream that contains
a valid archive. Details are controlled by Options. Typically,
the option
close_parent(true)
is used to close stream if the archive is closed using archive_close/1. For other options, the defaults are typically fine. The optionformat(raw)
must be used to process compressed streams that do not contain explicit entries (e.g., gzip'ed data) unambibuously. Theraw
format creates a pseudo archive holding a single member nameddata
.- close_parent(+Boolean)
- If this option is
true
(defaultfalse
), Stream is closed if archive_close/1 is called on Archive. - compression(+Compression)
- Synomym for
filter(Compression)
. Deprecated. - filter(+Filter)
- Support the indicated filter. This option may be
used multiple times to support multiple filters. In read mode,
If no filter options are provided,
all
is assumed. In write mode, none is assumed. Supported values areall
,bzip2
,compress
,gzip
,grzip
,lrzip
,lzip
,lzma
,lzop
,none
,rpm
,uu
andxz
. The valueall
is default for read,none
for write. - format(+Format)
- Support the indicated format. This option may be used
multiple times to support multiple formats in read mode.
In write mode, you must supply a single format. If no format
options are provided,
all
is assumed for read mode. Note thatall
does not includeraw
andmtree
. To open both archive and non-archive files, bothformat(all)
andformat(raw)
and/orformat(mtree)
must be specified. Supported values are:all
,7zip
,ar
,cab
,cpio
,empty
,gnutar
,iso9660
,lha
,mtree
,rar
,raw
,tar
,xar
andzip
. The valueall
is default for read.
Note that the actually supported compression types and formats may vary depending on the version and installation options of the underlying libarchive library. This predicate raises a domain error if the (explicitly) requested format is not supported.
- archive_close(+Archive) is det
- Close the archive. If
close_parent(true)
is specified, the underlying stream is closed too. If there is an entry opened with archive_open_entry/2, actually closing the archive is delayed until the stream associated with the entry is closed. This can be used to open a stream to an archive entry without having to worry about closing the archive:archive_open_named(ArchiveFile, EntryName, Stream) :- archive_open(ArchiveFile, Handle, []), archive_next_header(Handle, Name), archive_open_entry(Handle, Stream), archive_close(Archive).
- archive_property(+Handle, ?Property) is nondet
- True when Property is a property of the archive Handle. Defined
properties are:
- filters(List)
- True when the indicated filters are applied before reaching the archive format.
- archive_next_header(+Handle, -Name) is semidet
- Forward to the next entry of the archive for which Name unifies
with the pathname of the entry. Fails silently if the name of
the archive is reached before success. Name is typically
specified if a single entry must be accessed and unbound
otherwise. The following example opens a Prolog stream to a
given archive entry. Note that Stream must be closed using
close/1 and the archive must be closed using archive_close/1
after the data has been used. See also setup_call_cleanup/3.
open_archive_entry(ArchiveFile, Entry, Stream) :- open(ArchiveFile, read, In, [type(binary)]), archive_open(In, Archive, [close_parent(true)]), archive_next_header(Archive, Entry), archive_open_entry(Archive, Stream).
- archive_open_entry(+Archive, -Stream) is det
- Open the current entry as a stream. Stream must be closed. If the stream is not closed before the next call to archive_next_header/2, a permission error is raised.
- archive_set_header_property(+Archive, +Property)
- Set Property of the current header. Write-mode only. Defined
properties are:
- filetype(-Type)
- Type is one of
file
,link
,socket
,character_device
,block_device
,directory
orfifo
. It appears that this library can also return other values. These are returned as an integer. - mtime(-Time)
- True when entry was last modified at time.
- size(-Bytes)
- True when entry is Bytes long.
- link_target(-Target)
- Target for a link. Currently only supported for symbolic links.
- archive_header_property(+Archive, ?Property)
- True when Property is a property of the current header. Defined
properties are:
- filetype(-Type)
- Type is one of
file
,link
,socket
,character_device
,block_device
,directory
orfifo
. It appears that this library can also return other values. These are returned as an integer. - mtime(-Time)
- True when entry was last modified at time.
- size(-Bytes)
- True when entry is Bytes long.
- link_target(-Target)
- Target for a link. Currently only supported for symbolic links.
- format(-Format)
- Provides the name of the archive format applicable to the
current entry. The returned value is the lowercase version
of the output of
archive_format_name()
. - permissions(-Integer)
- True when entry has the indicated permission mask.
- archive_extract(+ArchiveFile, +Dir, +Options)
- Extract files from the given archive into Dir. Supported
options:
- remove_prefix(+Prefix)
- Strip Prefix from all entries before extracting. If Prefix is a list, then each prefix is tried in order, succeding at the first one that matches. If no prefixes match, an error is reported. If Prefix is an atom, then that prefix is removed.
- exclude(+ListOfPatterns)
- Ignore members that match one of the given patterns. Patterns are handed to wildcard_match/2.
- include(+ListOfPatterns)
- Include members that match one of the given patterns.
Patterns are handed to wildcard_match/2. The
exclude
options takes preference if a member matches both theinclude
and theexclude
option.
- archive_entries(+Archive, -Paths) is det
- True when Paths is a list of pathnames appearing in Archive.
- archive_data_stream(+Archive, -DataStream, +Options) is nondet
- True when DataStream is a stream to a data object inside
Archive. This predicate transparently unpacks data inside
possibly nested archives, e.g., a tar file inside a zip
file. It applies the appropriate decompression filters and thus
ensures that Prolog reads the plain data from DataStream.
DataStream must be closed after the content has been processed.
Backtracking opens the next member of the (nested) archive. This
predicate processes the following options:
- meta_data(-Data:list(dict))
- If provided, Data is unified with a list of filters applied to
the (nested) archive to open the current DataStream. The first
element describes the outermost archive. Each Data dict
contains the header properties (archive_header_property/2) as
well as the keys:
- filters(Filters:list(atom))
- Filter list as obtained from archive_property/2
- name(Atom)
- Name of the entry.
Non-archive files are handled as pseudo-archives that hold a single stream. This is implemented by using archive_open/3 with the options
[format(all),format(raw)]
. - archive_create(+OutputFile, +InputFiles, +Options) is det
- Convenience predicate to create an archive in OutputFile with
data from a list of InputFiles and the given Options.
Besides options supported by archive_open/4, the following options are supported:
- directory(+Directory)
- Changes the directory before adding input files. If this is
specified, paths of input files must be relative to
Directory and archived files will not have Directory
as leading path. This is to simulate
-C
option of thetar
program. - format(+Format)
- Write mode supports the following formats: `7zip
,
cpio,
gnutar,
iso9660,
xarand
zip`. Note that a particular installation may support only a subset of these, depending on the configuration oflibarchive
.
- archive_foldl(:Goal, +Archive, +State0, -State)
- Operates like foldl/4 but for the entries in the archive. For each member of the archive, Goal called as `call(:Goal, +Path, +Handle, +S0, -S1). Here, S0 is current state of the accumulator (starting with State0) and S1 is the next state of the accumulator, producing State after the last member of the archive.