doc/utils/archive.scrbl

2 @subsection[:tag "archive"]{(archive) - Generic archive interface}
4 @define[Library]{@name{archive}}
5 @desc{This library provides generic interface to access archive libraries.
12 (import (rnrs) (archive))
15 (call-with-input-archive-file 'zip "foo.zip"
18       (when (string=? (archive-entry-name e) "bar.txt")
23 ;; archive "bar.txt" into foo.tar
24 (call-with-output-archive-file 'tar "foo.tar"
30 Following sections use @var{type} as a supported archive type. More precisely,
31 if it's a supported archive type then there must be a library named
32 @code{(archive @var{type})}.
36 @define[Function]{@name{make-input-archive} @args{type input-port}}
37 @desc{@var{type} must be a symbol and supported archive type.
40 Creates an archive input which represents the specified type of archive.
43 @define[Method]{@name{next-entry!} @args{archive-input}}
44 @desc{Retrieves next entry of the given archive input. If there is no entry,
48 @define[Macro]{@name{do-entry} @args{(entry archive-input) body @dots{}}}
49 @define[Macro]{@name{do-entry} @args{(entry archive-input result) body @dots{}}}
50 @desc{Convenient macro. Iterates the given @var{archive-input}'s entries.
55 (do ((@var{entry} (next-entry! @var{archive-input}) (next-entry! @var{archive-input})))
64 @desc{Extract the given archive entry @var{entry} to binary output port
69  @args{archive-input :key (destinator archive-entry-name) (overwrite #f)}}
71 @var{archive-input} to the file specified by @var{destinator}.
74 one argument, archive entry, and return a string represents the
81 @define[Method]{@name{finish!} @args{archive-input}}
82 @desc{Finalize the given archive input.}
84 @define[Function]{@name{call-with-input-archive} @args{archive-input proc}}
85 @desc{@var{archive-input} must be an archive input.
88 Call the @var{proc} with archive input and returns the result of the
91 The @var{archive-input} is finalized by @code{finish!}.
94 @define[Function]{@name{call-with-input-archive-port}
96 @desc{Creates an archive input with @var{type} and @var{input-port}, then
97 call @code{call-with-input-archive}.
100 @define[Function]{@name{call-with-input-archive-file}
103 @code{call-with-input-archive-port}.
108 @define[Function]{@name{make-output-archive} @args{type output-port}}
112 Creates an archive output which represents the specified type of archive.
115 @define[Method]{@name{create-entry} @args{archive-output file}}
116 @desc{Creates an archive entry from the given @var{file}.
118 For implementing user defined archive;
122 (define-method create-entry ((out <archive-output>) file)
129 @define[Method]{@name{create-entry} @args{archive-output entry-name file}}
130 @desc{Creates an archive entry from the given @var{file}. The entry's name
134 @define[Method]{@name{append-entry!} @args{archive-output entry}}
135 @desc{Appends the given @var{entry} to @var{archive-output}.}
137 @define[Method]{@name{finish!} @args{archive-output}}
138 @desc{Finalize the given archive output.}
140 @define[Function]{@name{call-with-output-archive} @args{archive-output proc}}
141 @desc{@var{archive-output} must be an archive output.
144 Call the @var{proc} with archive input and returns the result of the
147 The @var{archive-output} is finalized by @code{finish!}.
150 @define[Function]{@name{call-with-output-archive-port}
152 @desc{Creates an archive output with @var{type} and @var{output-port}, then
153 call @code{call-with-output-archive}.
156 @define[Function]{@name{call-with-output-archive-file}
159 @code{call-with-output-archive-port}.
164 @define[Function]{@name{archive-entry-name} @args{entry}}
167 @define[Function]{@name{archive-entry-type} @args{entry}}
172 @subsubsection{Implementing archive implementation library}
174 To support other archive such as RAR, then you need to create a implementation
177 @define[Library]{@name{(archive interface}}
179 archive access.
182 To support @var{foo} archive, then the library name must be
183 code{(archive @var{foo})} and it must import @code{(archive interface)}.
187 (library (archive foo)
191           (archive interface)
202 @codeblock{make-archive-input, next-entry, extract-entry}
203 @codeblock{<archive-input> <archive-entry>}
207 @codeblock{make-archive-output, create-entry, append-entry!, finish!}
208 @codeblock{<archive-output> <archive-entry>}
210 NOTE: @code{<archive-entry>} may be shared between archiving and extracting.
212 @define[Class]{@name{<archive-input>}}
213 @desc{Abstract class of the archive input. This class has the following
218    Source of the archive. For compatibility of other archive, this should be
224 @define[Class]{@name{<archive-output>}}
225 @desc{Abstract class of the archive output. This class has the following
230    Destination of the archive. For compatibility of other archive, this
236 @define[Class]{@name{<archive-entry>}}
237 @desc{Abstract class of the archive entry. This class has the following
243    Entry type. For compatibility of other archive, this must be @code{file} or
249 @define[Method]{@name{make-archive-input} @args{type (source <port>)}}
250 @define[Method]{@name{make-archive-output} @args{type (sink <port>)}}
251 @desc{Creates an archive input or output. @var{type} specifies the
252 archive type. It is recommended to use @code{eql} specializer to specify.
255 @define[Method]{@name{finish!} @args{(in <archive-input>)}}
256 @desc{The @code{finish!} method for archive input has a default
259 Users can specialize the method for own archive input.