NAME
    IO::Adapter::File - IO functions for a file.

SYNOPSIS
        $map = 'file:/some/where/file';

    To read list

        use IO::Adapter;
        $obj = new IO::Adapter $map;
        $obj->open || croak("cannot open $map");
        while ($x = $obj->getline) { ... }
        $obj->close;

    To add the address

        $obj = new IO::Adapter $map;
        $obj->add( $address );

    To delete it

        $regexp = "^$address";
        $obj->delete( $regexp );

DESCRIPTION
    This module provides real IO functions for a file used in "IO::Adapter".
    The map is the fully path-ed file name or a file name with 'file:/'
    prefix.

METHODS
  new()
    constructor.

  open($args)
    $args HASH REFERENCE must have two parameters. "file" is the target file
    to open. "flag" is the mode of open().

  touch()
    create a file if not exists.

  getline()
    return one line. It is the same as usual getline() call for a file.

  getpos()
    get the position in the opened file.

  setpos(pos)
    set the position in the opened file.

  eof()
    Eof Of File?

  close()
    close the opended file.

  add($address, ... )
    add (append) $address to this map.

  delete($key)
    delete lines with key $key from this map.

LOCK
  lock($args)
  unlock($args)
SEQUENCE FILE OPERATION
  sequence_increment($args)
    For example, to get a new (incremented) sequence number of mailing list
    article:

        sub get_sequence_id
        {
            ... lock ...;

            my $obj = new IO::Adapter $map;
            my $id  = $obj->sequence_increment();
            unless ($obj->error()) {
                return $id;
            }
            else {
                print $obj->error(), "\n";
            }

            ... unlock ...;
        }

  sequence_replace($args)
    For example, to set sequence number to the specified value $new_id:

        sub set_sequence_id
        {
            my ($self, $new_id) = @_;

            ... lock ...;

            my $obj = new IO::Adapter $map;
            my $id  = $obj->sequence_replace($new_id);
            unless ($obj->error()) {
                return "ok";
            }
            else {
                print $obj->error(), "\n";
                return "fail";
            }

            ... unlock ...;
        }

SEE ALSO
    IO::Adapter

CODING STYLE
    See "http://www.fml.org/software/FNF/" on fml coding style guide.

AUTHOR
    Ken'ichi Fukamachi

COPYRIGHT
    Copyright (C) 2001,2002,2003,2004,2005,2006 Ken'ichi Fukamachi

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

HISTORY
    IO::Adapter::File first appeared in fml8 mailing list driver package.
    See "http://www.fml.org/" for more details.