NAME

IO::Unread - push more than one character back onto a filehandle

SYNOPSIS

    use IO::Unread;

    unread STDIN, "hello world\n";

    $_ = "goodbye";
    unread ARGV;

DESCRIPTION

IO::Unread exports one function, unread, which will push data back onto a filehandle. Any amount of data can be pushed: if your perl is built with PerlIO layers, the data is stored in a special :pending layer; if not, the module ties the filehandle to a class which returns the unread data and unties itself.

unread FILEHANDLE, LIST

unread unreads LIST onto FILEHANDLE. If LIST is omitted, $_ is unread. Returns the number of characters unread on success, undef on failure. Warnings are produced under category io.

Note that unread $FH, 'a', 'b' is equivalent to

  unread $FH, 'a';
  unread $FH, 'b';

, ie. to unread $FH, 'ba' rather than unread $FH, 'ab'.

ungetc FILEHANDLE, STRING

ungetc pushes the first character of STRING onto FILEHANDLE. Unlike unread, it does not use a tie implementation if your perl doesn't support PerlIO layers; rather it calls your ungetc(3). This is only guarenteed to support one character of pushback, and then only if it is the last character that was read from the handle.

EXPORTS

None by default; unread, ungetc on request.

BUGS

ungetc is subject to the whims of your libc if you're not using perlio.

COPYRIGHT

Copyright 2003 Ben Morrow <ben@morrow.me.uk>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

PerlIO, perltie, ungetc(3)