home *** CD-ROM | disk | FTP | other *** search
/ PC World 2004 November / PCWorld_2004-11_cd.bin / software / topware / activeperl / ActivePerl-5.8.4.810-MSWin32-x86.exe / ActivePerl-5.8.4.810 / Perl / lib / FileHandle.pm < prev    next >
Text File  |  2004-06-01  |  7KB  |  263 lines
  1. package FileHandle;
  2.  
  3. use 5.006;
  4. use strict;
  5. our($VERSION, @ISA, @EXPORT, @EXPORT_OK);
  6.  
  7. $VERSION = "2.01";
  8.  
  9. require IO::File;
  10. @ISA = qw(IO::File);
  11.  
  12. @EXPORT = qw(_IOFBF _IOLBF _IONBF);
  13.  
  14. @EXPORT_OK = qw(
  15.     pipe
  16.  
  17.     autoflush
  18.     output_field_separator
  19.     output_record_separator
  20.     input_record_separator
  21.     input_line_number
  22.     format_page_number
  23.     format_lines_per_page
  24.     format_lines_left
  25.     format_name
  26.     format_top_name
  27.     format_line_break_characters
  28.     format_formfeed
  29.  
  30.     print
  31.     printf
  32.     getline
  33.     getlines
  34. );
  35.  
  36. #
  37. # Everything we're willing to export, we must first import.
  38. #
  39. import IO::Handle grep { !defined(&$_) } @EXPORT, @EXPORT_OK;
  40.  
  41. #
  42. # Some people call "FileHandle::function", so all the functions
  43. # that were in the old FileHandle class must be imported, too.
  44. #
  45. {
  46.     no strict 'refs';
  47.  
  48.     my %import = (
  49.     'IO::Handle' =>
  50.         [qw(DESTROY new_from_fd fdopen close fileno getc ungetc gets
  51.         eof flush error clearerr setbuf setvbuf _open_mode_string)],
  52.     'IO::Seekable' =>
  53.         [qw(seek tell getpos setpos)],
  54.     'IO::File' =>
  55.         [qw(new new_tmpfile open)]
  56.     );
  57.     for my $pkg (keys %import) {
  58.     for my $func (@{$import{$pkg}}) {
  59.         my $c = *{"${pkg}::$func"}{CODE}
  60.         or die "${pkg}::$func missing";
  61.         *$func = $c;
  62.     }
  63.     }
  64. }
  65.  
  66. #
  67. # Specialized importer for Fcntl magic.
  68. #
  69. sub import {
  70.     my $pkg = shift;
  71.     my $callpkg = caller;
  72.     require Exporter;
  73.     Exporter::export($pkg, $callpkg, @_);
  74.  
  75.     #
  76.     # If the Fcntl extension is available,
  77.     #  export its constants.
  78.     #
  79.     eval {
  80.     require Fcntl;
  81.     Exporter::export('Fcntl', $callpkg);
  82.     };
  83. }
  84.  
  85. ################################################
  86. # This is the only exported function we define;
  87. # the rest come from other classes.
  88. #
  89.  
  90. sub pipe {
  91.     my $r = new IO::Handle;
  92.     my $w = new IO::Handle;
  93.     CORE::pipe($r, $w) or return undef;
  94.     ($r, $w);
  95. }
  96.  
  97. # Rebless standard file handles
  98. bless *STDIN{IO},  "FileHandle" if ref *STDIN{IO}  eq "IO::Handle";
  99. bless *STDOUT{IO}, "FileHandle" if ref *STDOUT{IO} eq "IO::Handle";
  100. bless *STDERR{IO}, "FileHandle" if ref *STDERR{IO} eq "IO::Handle";
  101.  
  102. 1;
  103.  
  104. __END__
  105.  
  106. =head1 NAME
  107.  
  108. FileHandle - supply object methods for filehandles
  109.  
  110. =head1 SYNOPSIS
  111.  
  112.     use FileHandle;
  113.  
  114.     $fh = new FileHandle;
  115.     if ($fh->open("< file")) {
  116.         print <$fh>;
  117.         $fh->close;
  118.     }
  119.  
  120.     $fh = new FileHandle "> FOO";
  121.     if (defined $fh) {
  122.         print $fh "bar\n";
  123.         $fh->close;
  124.     }
  125.  
  126.     $fh = new FileHandle "file", "r";
  127.     if (defined $fh) {
  128.         print <$fh>;
  129.         undef $fh;       # automatically closes the file
  130.     }
  131.  
  132.     $fh = new FileHandle "file", O_WRONLY|O_APPEND;
  133.     if (defined $fh) {
  134.         print $fh "corge\n";
  135.         undef $fh;       # automatically closes the file
  136.     }
  137.  
  138.     $pos = $fh->getpos;
  139.     $fh->setpos($pos);
  140.  
  141.     $fh->setvbuf($buffer_var, _IOLBF, 1024);
  142.  
  143.     ($readfh, $writefh) = FileHandle::pipe;
  144.  
  145.     autoflush STDOUT 1;
  146.  
  147. =head1 DESCRIPTION
  148.  
  149. NOTE: This class is now a front-end to the IO::* classes.
  150.  
  151. C<FileHandle::new> creates a C<FileHandle>, which is a reference to a
  152. newly created symbol (see the C<Symbol> package).  If it receives any
  153. parameters, they are passed to C<FileHandle::open>; if the open fails,
  154. the C<FileHandle> object is destroyed.  Otherwise, it is returned to
  155. the caller.
  156.  
  157. C<FileHandle::new_from_fd> creates a C<FileHandle> like C<new> does.
  158. It requires two parameters, which are passed to C<FileHandle::fdopen>;
  159. if the fdopen fails, the C<FileHandle> object is destroyed.
  160. Otherwise, it is returned to the caller.
  161.  
  162. C<FileHandle::open> accepts one parameter or two.  With one parameter,
  163. it is just a front end for the built-in C<open> function.  With two
  164. parameters, the first parameter is a filename that may include
  165. whitespace or other special characters, and the second parameter is
  166. the open mode, optionally followed by a file permission value.
  167.  
  168. If C<FileHandle::open> receives a Perl mode string (">", "+<", etc.)
  169. or a POSIX fopen() mode string ("w", "r+", etc.), it uses the basic
  170. Perl C<open> operator.
  171.  
  172. If C<FileHandle::open> is given a numeric mode, it passes that mode
  173. and the optional permissions value to the Perl C<sysopen> operator.
  174. For convenience, C<FileHandle::import> tries to import the O_XXX
  175. constants from the Fcntl module.  If dynamic loading is not available,
  176. this may fail, but the rest of FileHandle will still work.
  177.  
  178. C<FileHandle::fdopen> is like C<open> except that its first parameter
  179. is not a filename but rather a file handle name, a FileHandle object,
  180. or a file descriptor number.
  181.  
  182. If the C functions fgetpos() and fsetpos() are available, then
  183. C<FileHandle::getpos> returns an opaque value that represents the
  184. current position of the FileHandle, and C<FileHandle::setpos> uses
  185. that value to return to a previously visited position.
  186.  
  187. If the C function setvbuf() is available, then C<FileHandle::setvbuf>
  188. sets the buffering policy for the FileHandle.  The calling sequence
  189. for the Perl function is the same as its C counterpart, including the
  190. macros C<_IOFBF>, C<_IOLBF>, and C<_IONBF>, except that the buffer
  191. parameter specifies a scalar variable to use as a buffer.  WARNING: A
  192. variable used as a buffer by C<FileHandle::setvbuf> must not be
  193. modified in any way until the FileHandle is closed or until
  194. C<FileHandle::setvbuf> is called again, or memory corruption may
  195. result!
  196.  
  197. See L<perlfunc> for complete descriptions of each of the following
  198. supported C<FileHandle> methods, which are just front ends for the
  199. corresponding built-in functions:
  200.  
  201.     close
  202.     fileno
  203.     getc
  204.     gets
  205.     eof
  206.     clearerr
  207.     seek
  208.     tell
  209.  
  210. See L<perlvar> for complete descriptions of each of the following
  211. supported C<FileHandle> methods:
  212.  
  213.     autoflush
  214.     output_field_separator
  215.     output_record_separator
  216.     input_record_separator
  217.     input_line_number
  218.     format_page_number
  219.     format_lines_per_page
  220.     format_lines_left
  221.     format_name
  222.     format_top_name
  223.     format_line_break_characters
  224.     format_formfeed
  225.  
  226. Furthermore, for doing normal I/O you might need these:
  227.  
  228. =over 4
  229.  
  230. =item $fh->print
  231.  
  232. See L<perlfunc/print>.
  233.  
  234. =item $fh->printf
  235.  
  236. See L<perlfunc/printf>.
  237.  
  238. =item $fh->getline
  239.  
  240. This works like <$fh> described in L<perlop/"I/O Operators">
  241. except that it's more readable and can be safely called in a
  242. list context but still returns just one line.
  243.  
  244. =item $fh->getlines
  245.  
  246. This works like <$fh> when called in a list context to
  247. read all the remaining lines in a file, except that it's more readable.
  248. It will also croak() if accidentally called in a scalar context.
  249.  
  250. =back
  251.  
  252. There are many other functions available since FileHandle is descended
  253. from IO::File, IO::Seekable, and IO::Handle.  Please see those
  254. respective pages for documentation on more functions.
  255.  
  256. =head1 SEE ALSO
  257.  
  258. The B<IO> extension,
  259. L<perlfunc>, 
  260. L<perlop/"I/O Operators">.
  261.  
  262. =cut
  263.