Permalink
Browse files

[Archive] add some documentation

  • Loading branch information...
1 parent 66e6aee commit 8cc26e4a562cd565a4da9596d716fd981275a813 @fperrad fperrad committed Jul 26, 2011
Showing with 105 additions and 26 deletions.
  1. +60 −17 runtime/parrot/library/Archive/Tar.pir
  2. +45 −9 runtime/parrot/library/Archive/Zip.pir
@@ -2,7 +2,30 @@
=head1 NAME
-Archive/Tar
+Archive/Tar - module for manipulations of tar archives
+
+head2 SYNOPSIS
+
+ load_bytecode 'Archive/Tar.pbc'
+
+ .local pmc archive
+ archive = new ['Archive';'Tar']
+
+ archive.'add_data'('file/baz.txt', "This is the contents now", 1000 :named('uid'))
+ archive.'add_files'('file/foo.pir', 'docs/README')
+
+ .local pmc fh
+ fh = new 'FileHandle'
+ fh.'open'('files.tar', 'wb')
+ archive.'write'(fh) # plain tar
+ fh.'close'()
+
+ $P0 = loadlib 'gziphandle'
+ .local pmc fh
+ fh = new 'GzipHandle'
+ fh.'open'('files.tgz', 'wb')
+ archive.'write'(fh) # gzip compressed
+ fh.'close'()
=head2 DESCRIPTION
@@ -49,7 +72,9 @@ See L<http://search.cpan.org/dist/Archive-Tar/>
.globalconst int BLOCK = 512
.end
-=item data
+=item $S0 = file.'data' ()
+
+Returns the current content for the in-memory file.
=cut
@@ -58,7 +83,9 @@ See L<http://search.cpan.org/dist/Archive-Tar/>
.return ($P0)
.end
-=item new_from_file
+=item $P0 = new_from_file ( path )
+
+Returns a new ['Archive';'Tar';'File'] object from an existing file.
=cut
@@ -94,7 +121,12 @@ See L<http://search.cpan.org/dist/Archive-Tar/>
.return ($P0)
.end
-=item new_from_data
+=item $P0 = new_from_data (path, data, opt :flat :named)
+
+Returns a new ['Archive';'Tar';'File'] object from data.
+
+'path' defines the file name (which need not exist), 'data' the file contents,
+and 'opt' is a hash of attributes which may be used to override the default attributes.
=cut
@@ -198,7 +230,9 @@ See L<http://search.cpan.org/dist/Archive-Tar/>
.return (directories, file)
.end
-=item full_path
+=item $S0 = file.'full_path' ()
+
+Returns the full path from the tar header; this is basically a concatenation of the prefix and name fields.
=cut
@@ -215,7 +249,9 @@ See L<http://search.cpan.org/dist/Archive-Tar/>
.return ($S0)
.end
-=item rename
+=item file.'rename' ( path )
+
+Rename the current file to 'path'.
=cut
@@ -229,10 +265,6 @@ See L<http://search.cpan.org/dist/Archive-Tar/>
setattribute self, 'prefix', $P0
.end
-=item _format_tar_entry
-
-=cut
-
.sub '_format_tar_entry' :method
$P0 = new 'StringBuilder'
$P1 = new 'FixedPMCArray'
@@ -342,6 +374,10 @@ See L<http://search.cpan.org/dist/Archive-Tar/>
=over 4
+=item tar = new ['Archive';'Tar']
+
+Returns a new ['Archive';'Tar'] object.
+
=cut
.namespace ['Archive';'Tar']
@@ -356,7 +392,11 @@ See L<http://search.cpan.org/dist/Archive-Tar/>
setattribute self, 'data', $P0
.end
-=item add_files
+=item tar.'add_files' ( filenamelist :flat )
+
+Takes a list of filenames and adds them to the in-memory archive.
+
+Returns a list of ['Archive';'Tar';'File'] objects that were just added.
=cut
@@ -395,7 +435,12 @@ See L<http://search.cpan.org/dist/Archive-Tar/>
.return (rv)
.end
-=item add_data
+=item tar.'add_data' ( filename, data, opt :flat :named )
+
+Add a file to the in-memory archive, with name 'filename' and content 'data'
+and 'opt' is a hash of attributes which may be used to override the default attributes.
+
+Returns the ['Archive';'Tar';'File'] object that was just added.
=cut
@@ -411,7 +456,9 @@ See L<http://search.cpan.org/dist/Archive-Tar/>
.return (obj)
.end
-=item write
+=item tar.'write' ( fh )
+
+Write the in-memory archive to disk. The argument is already opened filehandle.
=cut
@@ -443,10 +490,6 @@ See L<http://search.cpan.org/dist/Archive-Tar/>
fh.'puts'(TAR_END)
.end
-=item _error
-
-=cut
-
.sub '_error' :method
.param pmc args :slurpy
$S0 = join '', args
@@ -2,7 +2,24 @@
=head1 NAME
-Archive/Zip
+Archive::Zip - Provide an interface to ZIP archive files.
+
+=head2 SYNOPSIS
+
+ load_bytecode 'Archive/Zip.pbc'
+
+ .local pmc archive
+ archive = new ['Archive';'Zip']
+
+ archive.'addFile'('xyz.pl', 'AnotherName.pl')
+
+ archive.'writeToFileNamed'('someZip.zip')
+
+ .local pmc fh
+ fh = new 'FileHandle'
+ fh.'open'('files.zip', 'wb')
+ archive.'writeToFileHandle'(fh, 1)
+ fh.'close'()
=head2 DESCRIPTION
@@ -154,7 +171,11 @@ See L<http://search.cpan.org/dist/Archive-Zip/>
setattribute self, 'fileComment', $P0
.end
-=item newFromFile
+=item newFromFile( fileName, [ zipName ] )
+
+Construct a new member from the given file.
+The optional 'zipName' argument sets the internal file name
+to something different than the given 'fileName'.
=cut
@@ -665,6 +686,10 @@ See L<http://search.cpan.org/dist/Archive-Zip/>
=over 4
+=item zip = new ['Archive';'Zip']
+
+Make a new, empty zip archive.
+
=cut
.namespace ['Archive';'Zip']
@@ -682,7 +707,9 @@ See L<http://search.cpan.org/dist/Archive-Zip/>
setattribute self, 'zipfileComment', $P0
.end
-=item addMember
+=item zip.'addMember' ( member )
+
+Append a member.
=cut
@@ -692,7 +719,11 @@ See L<http://search.cpan.org/dist/Archive-Zip/>
push $P0, member
.end
-=item addFile
+=item zip.'addFile' ( fileName [, newName ] )
+
+Append a member whose data comes from an external file.
+The optional 'newName' argument sets the internal file name
+to something different than the given 'fileName'.
=cut
@@ -705,7 +736,9 @@ See L<http://search.cpan.org/dist/Archive-Zip/>
.return ($P1)
.end
-=item writeToFileNamed
+=item zip.'writeToFileNamed' ( fileName )
+
+Write a zip archive to named file. Returns AZ_OK on success.
=cut
@@ -733,21 +766,24 @@ See L<http://search.cpan.org/dist/Archive-Zip/>
.tailcall self.'_ioError'("Can't open ", fileName, " for write")
.end
-=item writeToFileHandle
+=item zip.'writeToFileHandle' ( fileHandle, seekable )
+
+Write a zip archive to a file handle. Returns AZ_OK on success.
+The second arg tells whether or not to try to seek backwards to re-write headers.
=cut
.sub 'writeToFileHandle' :method
.param pmc fh
.param int fhIsSeekable
unless null fh goto L1
- $I0 = isa fh, 'FileHandle'
+ $I0 = isa fh, 'Handle'
if $I0 goto L1
- .tailcall self.'_error'('No filehandle given')
+ .tailcall self.'_error'('No handle given')
L1:
$I0 = fh.'is_closed'()
unless $I0 goto L2
- .tailcall self.'_ioError'('filehandle not open')
+ .tailcall self.'_ioError'('handle not open')
L2:
.local int offset
offset = 0

0 comments on commit 8cc26e4

Please sign in to comment.