home *** CD-ROM | disk | FTP | other *** search
/ CLIX - Fazer Clix Custa Nix / CLIX-CD.cdr / mac / lib / FileHandle.pm < prev    next >
Text File  |  1997-05-18  |  6KB  |  253 lines

  1. package FileHandle;
  2.  
  3. use 5.003_11;
  4. use strict;
  5. use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
  6.  
  7. $VERSION = "2.00";
  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.     Exporter::export $pkg, $callpkg, @_;
  73.  
  74.     #
  75.     # If the Fcntl extension is available,
  76.     #  export its constants.
  77.     #
  78.     eval {
  79.     require Fcntl;
  80.     Exporter::export 'Fcntl', $callpkg;
  81.     };
  82. }
  83.  
  84. ################################################
  85. # This is the only exported function we define;
  86. # the rest come from other classes.
  87. #
  88.  
  89. sub pipe {
  90.     my $r = new IO::Handle;
  91.     my $w = new IO::Handle;
  92.     CORE::pipe($r, $w) or return undef;
  93.     ($r, $w);
  94. }
  95.  
  96. 1;
  97.  
  98. __END__
  99.  
  100. =head1 NAME
  101.  
  102. FileHandle - supply object methods for filehandles
  103.  
  104. =head1 SYNOPSIS
  105.  
  106.     use FileHandle;
  107.  
  108.     $fh = new FileHandle;
  109.     if ($fh->open "< file") {
  110.         print <$fh>;
  111.         $fh->close;
  112.     }
  113.  
  114.     $fh = new FileHandle "> FOO";
  115.     if (defined $fh) {
  116.         print $fh "bar\n";
  117.         $fh->close;
  118.     }
  119.  
  120.     $fh = new FileHandle "file", "r";
  121.     if (defined $fh) {
  122.         print <$fh>;
  123.         undef $fh;       # automatically closes the file
  124.     }
  125.  
  126.     $fh = new FileHandle "file", O_WRONLY|O_APPEND;
  127.     if (defined $fh) {
  128.         print $fh "corge\n";
  129.         undef $fh;       # automatically closes the file
  130.     }
  131.  
  132.     $pos = $fh->getpos;
  133.     $fh->setpos($pos);
  134.  
  135.     $fh->setvbuf($buffer_var, _IOLBF, 1024);
  136.  
  137.     ($readfh, $writefh) = FileHandle::pipe;
  138.  
  139.     autoflush STDOUT 1;
  140.  
  141. =head1 DESCRIPTION
  142.  
  143. NOTE: This class is now a front-end to the IO::* classes.
  144.  
  145. C<FileHandle::new> creates a C<FileHandle>, which is a reference to a
  146. newly created symbol (see the C<Symbol> package).  If it receives any
  147. parameters, they are passed to C<FileHandle::open>; if the open fails,
  148. the C<FileHandle> object is destroyed.  Otherwise, it is returned to
  149. the caller.
  150.  
  151. C<FileHandle::new_from_fd> creates a C<FileHandle> like C<new> does.
  152. It requires two parameters, which are passed to C<FileHandle::fdopen>;
  153. if the fdopen fails, the C<FileHandle> object is destroyed.
  154. Otherwise, it is returned to the caller.
  155.  
  156. C<FileHandle::open> accepts one parameter or two.  With one parameter,
  157. it is just a front end for the built-in C<open> function.  With two
  158. parameters, the first parameter is a filename that may include
  159. whitespace or other special characters, and the second parameter is
  160. the open mode, optionally followed by a file permission value.
  161.  
  162. If C<FileHandle::open> receives a Perl mode string (">", "+<", etc.)
  163. or a POSIX fopen() mode string ("w", "r+", etc.), it uses the basic
  164. Perl C<open> operator.
  165.  
  166. If C<FileHandle::open> is given a numeric mode, it passes that mode
  167. and the optional permissions value to the Perl C<sysopen> operator.
  168. For convenience, C<FileHandle::import> tries to import the O_XXX
  169. constants from the Fcntl module.  If dynamic loading is not available,
  170. this may fail, but the rest of FileHandle will still work.
  171.  
  172. C<FileHandle::fdopen> is like C<open> except that its first parameter
  173. is not a filename but rather a file handle name, a FileHandle object,
  174. or a file descriptor number.
  175.  
  176. If the C functions fgetpos() and fsetpos() are available, then
  177. C<FileHandle::getpos> returns an opaque value that represents the
  178. current position of the FileHandle, and C<FileHandle::setpos> uses
  179. that value to return to a previously visited position.
  180.  
  181. If the C function setvbuf() is available, then C<FileHandle::setvbuf>
  182. sets the buffering policy for the FileHandle.  The calling sequence
  183. for the Perl function is the same as its C counterpart, including the
  184. macros C<_IOFBF>, C<_IOLBF>, and C<_IONBF>, except that the buffer
  185. parameter specifies a scalar variable to use as a buffer.  WARNING: A
  186. variable used as a buffer by C<FileHandle::setvbuf> must not be
  187. modified in any way until the FileHandle is closed or until
  188. C<FileHandle::setvbuf> is called again, or memory corruption may
  189. result!
  190.  
  191. See L<perlfunc> for complete descriptions of each of the following
  192. supported C<FileHandle> methods, which are just front ends for the
  193. corresponding built-in functions:
  194.  
  195.     close
  196.     fileno
  197.     getc
  198.     gets
  199.     eof
  200.     clearerr
  201.     seek
  202.     tell
  203.  
  204. See L<perlvar> for complete descriptions of each of the following
  205. supported C<FileHandle> methods:
  206.  
  207.     autoflush
  208.     output_field_separator
  209.     output_record_separator
  210.     input_record_separator
  211.     input_line_number
  212.     format_page_number
  213.     format_lines_per_page
  214.     format_lines_left
  215.     format_name
  216.     format_top_name
  217.     format_line_break_characters
  218.     format_formfeed
  219.  
  220. Furthermore, for doing normal I/O you might need these:
  221.  
  222. =over 
  223.  
  224. =item $fh->print
  225.  
  226. See L<perlfunc/print>.
  227.  
  228. =item $fh->printf
  229.  
  230. See L<perlfunc/printf>.
  231.  
  232. =item $fh->getline
  233.  
  234. This works like <$fh> described in L<perlop/"I/O Operators">
  235. except that it's more readable and can be safely called in an
  236. array context but still returns just one line.
  237.  
  238. =item $fh->getlines
  239.  
  240. This works like <$fh> when called in an array context to
  241. read all the remaining lines in a file, except that it's more readable.
  242. It will also croak() if accidentally called in a scalar context.
  243.  
  244. =back
  245.  
  246. =head1 SEE ALSO
  247.  
  248. The B<IO> extension,
  249. L<perlfunc>, 
  250. L<perlop/"I/O Operators">.
  251.  
  252. =cut
  253.