--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. | will give a
+.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
+.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
+.\" expand to `' in nroff, nothing in troff, for use with C<>.
+.tr \(*W-|\(bv\*(Tr
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "Archive::Tar::File 3"
+.TH Archive::Tar::File 3 "2009-09-10" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+Archive::Tar::File \- a subclass for in\-memory extracted file from Archive::Tar
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\& my @items = $tar\->get_files;
+.Ve
+.PP
+.Vb 1
+\& print $_\->name, ' ', $_\->size, "\en" for @items;
+.Ve
+.PP
+.Vb 2
+\& print $object\->get_content;
+\& $object\->replace_content('new content');
+.Ve
+.PP
+.Vb 1
+\& $object\->rename( 'new/full/path/to/file.c' );
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+Archive::Tar::Files provides a neat little object layer for in-memory
+extracted files. It's mostly used internally in Archive::Tar to tidy
+up the code, but there's no reason users shouldn't use this \s-1API\s0 as
+well.
+.Sh "Accessors"
+.IX Subsection "Accessors"
+A lot of the methods in this package are accessors to the various
+fields in the tar header:
+.IP "name" 4
+.IX Item "name"
+The file's name
+.IP "mode" 4
+.IX Item "mode"
+The file's mode
+.IP "uid" 4
+.IX Item "uid"
+The user id owning the file
+.IP "gid" 4
+.IX Item "gid"
+The group id owning the file
+.IP "size" 4
+.IX Item "size"
+File size in bytes
+.IP "mtime" 4
+.IX Item "mtime"
+Modification time. Adjusted to mac-time on MacOS if required
+.IP "chksum" 4
+.IX Item "chksum"
+Checksum field for the tar header
+.IP "type" 4
+.IX Item "type"
+File type \*(-- numeric, but comparable to exported constants \*(-- see
+Archive::Tar's documentation
+.IP "linkname" 4
+.IX Item "linkname"
+If the file is a symlink, the file it's pointing to
+.IP "magic" 4
+.IX Item "magic"
+Tar magic string \*(-- not useful for most users
+.IP "version" 4
+.IX Item "version"
+Tar version string \*(-- not useful for most users
+.IP "uname" 4
+.IX Item "uname"
+The user name that owns the file
+.IP "gname" 4
+.IX Item "gname"
+The group name that owns the file
+.IP "devmajor" 4
+.IX Item "devmajor"
+Device major number in case of a special file
+.IP "devminor" 4
+.IX Item "devminor"
+Device minor number in case of a special file
+.IP "prefix" 4
+.IX Item "prefix"
+Any directory to prefix to the extraction path, if any
+.IP "raw" 4
+.IX Item "raw"
+Raw tar header \*(-- not useful for most users
+.SH "Methods"
+.IX Header "Methods"
+.ie n .Sh "Archive::Tar::File\->new( file => $path )"
+.el .Sh "Archive::Tar::File\->new( file => \f(CW$path\fP )"
+.IX Subsection "Archive::Tar::File->new( file => $path )"
+Returns a new Archive::Tar::File object from an existing file.
+.PP
+Returns undef on failure.
+.ie n .Sh "Archive::Tar::File\->new( data => $path\fP, \f(CW$data\fP, \f(CW$opt )"
+.el .Sh "Archive::Tar::File\->new( data => \f(CW$path\fP, \f(CW$data\fP, \f(CW$opt\fP )"
+.IX Subsection "Archive::Tar::File->new( data => $path, $data, $opt )"
+Returns a new Archive::Tar::File object from data.
+.PP
+\&\f(CW$path\fR defines the file name (which need not exist), \f(CW$data\fR the
+file contents, and \f(CW$opt\fR is a reference to a hash of attributes
+which may be used to override the default attributes (fields in the
+tar header), which are described above in the Accessors section.
+.PP
+Returns undef on failure.
+.ie n .Sh "Archive::Tar::File\->new( chunk => $chunk )"
+.el .Sh "Archive::Tar::File\->new( chunk => \f(CW$chunk\fP )"
+.IX Subsection "Archive::Tar::File->new( chunk => $chunk )"
+Returns a new Archive::Tar::File object from a raw 512\-byte tar
+archive chunk.
+.PP
+Returns undef on failure.
+.ie n .Sh "$bool = $file\fP\->extract( [ \f(CW$alternative_name ] )"
+.el .Sh "$bool = \f(CW$file\fP\->extract( [ \f(CW$alternative_name\fP ] )"
+.IX Subsection "$bool = $file->extract( [ $alternative_name ] )"
+Extract this object, optionally to an alternative name.
+.PP
+See \f(CW\*(C`Archive::Tar\->extract_file\*(C'\fR for details.
+.PP
+Returns true on success and false on failure.
+.ie n .Sh "$path = $file\->full_path"
+.el .Sh "$path = \f(CW$file\fP\->full_path"
+.IX Subsection "$path = $file->full_path"
+Returns the full path from the tar header; this is basically a
+concatenation of the \f(CW\*(C`prefix\*(C'\fR and \f(CW\*(C`name\*(C'\fR fields.
+.ie n .Sh "$bool = $file\->validate"
+.el .Sh "$bool = \f(CW$file\fP\->validate"
+.IX Subsection "$bool = $file->validate"
+Done by Archive::Tar internally when reading the tar file:
+validate the header against the checksum to ensure integer tar file.
+.PP
+Returns true on success, false on failure
+.ie n .Sh "$bool = $file\->has_content"
+.el .Sh "$bool = \f(CW$file\fP\->has_content"
+.IX Subsection "$bool = $file->has_content"
+Returns a boolean to indicate whether the current object has content.
+Some special files like directories and so on never will have any
+content. This method is mainly to make sure you don't get warnings
+for using uninitialized values when looking at an object's content.
+.ie n .Sh "$content = $file\->get_content"
+.el .Sh "$content = \f(CW$file\fP\->get_content"
+.IX Subsection "$content = $file->get_content"
+Returns the current content for the in-memory file
+.ie n .Sh "$cref = $file\->get_content_by_ref"
+.el .Sh "$cref = \f(CW$file\fP\->get_content_by_ref"
+.IX Subsection "$cref = $file->get_content_by_ref"
+Returns the current content for the in-memory file as a scalar
+reference. Normal users won't need this, but it will save memory if
+you are dealing with very large data files in your tar archive, since
+it will pass the contents by reference, rather than make a copy of it
+first.
+.ie n .Sh "$bool = $file\fP\->replace_content( \f(CW$content )"
+.el .Sh "$bool = \f(CW$file\fP\->replace_content( \f(CW$content\fP )"
+.IX Subsection "$bool = $file->replace_content( $content )"
+Replace the current content of the file with the new content. This
+only affects the in-memory archive, not the on-disk version until
+you write it.
+.PP
+Returns true on success, false on failure.
+.ie n .Sh "$bool = $file\fP\->rename( \f(CW$new_name )"
+.el .Sh "$bool = \f(CW$file\fP\->rename( \f(CW$new_name\fP )"
+.IX Subsection "$bool = $file->rename( $new_name )"
+Rename the current file to \f(CW$new_name\fR.
+.PP
+Note that you must specify a Unix path for \f(CW$new_name\fR, since per tar
+standard, all files in the archive must be Unix paths.
+.PP
+Returns true on success and false on failure.
+.SH "Convenience methods"
+.IX Header "Convenience methods"
+To quickly check the type of a \f(CW\*(C`Archive::Tar::File\*(C'\fR object, you can
+use the following methods:
+.IP "$file\->is_file" 4
+.IX Item "$file->is_file"
+Returns true if the file is of type \f(CW\*(C`file\*(C'\fR
+.IP "$file\->is_dir" 4
+.IX Item "$file->is_dir"
+Returns true if the file is of type \f(CW\*(C`dir\*(C'\fR
+.IP "$file\->is_hardlink" 4
+.IX Item "$file->is_hardlink"
+Returns true if the file is of type \f(CW\*(C`hardlink\*(C'\fR
+.IP "$file\->is_symlink" 4
+.IX Item "$file->is_symlink"
+Returns true if the file is of type \f(CW\*(C`symlink\*(C'\fR
+.IP "$file\->is_chardev" 4
+.IX Item "$file->is_chardev"
+Returns true if the file is of type \f(CW\*(C`chardev\*(C'\fR
+.IP "$file\->is_blockdev" 4
+.IX Item "$file->is_blockdev"
+Returns true if the file is of type \f(CW\*(C`blockdev\*(C'\fR
+.IP "$file\->is_fifo" 4
+.IX Item "$file->is_fifo"
+Returns true if the file is of type \f(CW\*(C`fifo\*(C'\fR
+.IP "$file\->is_socket" 4
+.IX Item "$file->is_socket"
+Returns true if the file is of type \f(CW\*(C`socket\*(C'\fR
+.IP "$file\->is_longlink" 4
+.IX Item "$file->is_longlink"
+Returns true if the file is of type \f(CW\*(C`LongLink\*(C'\fR.
+Should not happen after a successful \f(CW\*(C`read\*(C'\fR.
+.IP "$file\->is_label" 4
+.IX Item "$file->is_label"
+Returns true if the file is of type \f(CW\*(C`Label\*(C'\fR.
+Should not happen after a successful \f(CW\*(C`read\*(C'\fR.
+.IP "$file\->is_unknown" 4
+.IX Item "$file->is_unknown"
+Returns true if the file type is \f(CW\*(C`unknown\*(C'\fR
projects / catagits/Gitalist.git / blobdiff