NAME
    IO::Adapter - adapter for several IO interfaces.

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

    where $map_params is map specific parameters used for such as "RDBMS".
    For example, $map_params is:

        $map_params = {
            'mysql:toymodel' => {
                sql_servers    => 'mysql.fml.org mysql2.fml.org',
                database       => 'fml',
                table          => 'ml',
                user           => 'fml',
                user_password  => "secret password :)",

                # model specific driver module
                driver         => 'My::Driver::Module::Name',
            },
        };

    where you can specify your own module to provide specific SQL
    statements.

DESCRIPTION
    This is "Adapter" (or "Wrapper") "design pattern". This is a wrapper of
    IO for e.g. file, unix group, NIS (Network Information System), RDBMS
    (Relational DataBase Management System) et. al. Once you create and open
    a "map", you can use the same methods as usual file IO.

  DATA STRUCTURE
    Consider file with space separators. The data structure in a file is
    described like this:

            file content = {
                    key1 => undef,
                    key2 => [ value2 ],
                    key3 => [ value3a, value3b ],
            };

    IO::Adapter converts data in arbitrary map e.g. file, /etc/group, RDBMS
    into this structure described above. Also, IO::Adapter provides unified
    access methods to this structure.

    Instead of unification, IO::Adapter may provide amibugous IO. For
    example, IO into array is not described as above. /etc/group must be
    described as

            wheel group = {
                    "root" => undef,
                    key2   => undef,
                    key3   => undef,
            };

  MAP
    "map" specifies the type of the database we read/write.

    For example, "file" map implies we hold our data in a file. The format
    is one line for one entry in a lot of cases.

       key1
       key2 value

    To get one entry is to read one line or a part of one line.

    This wrapper provides IO like a usual file for the specified $map.

  MAP TYPES
       map name        descriptions or examples
       ---------------------------------------------------
       file            file:$file_name (prefix file: is optional).
                       For example, file:/var/spool/ml/elena/recipients

       pcre            pcre:$file_name
                       e.g. pcre:/var/spool/ml/elena/sender_check

       unix.group      unix.group:$group_name
                       For example, unix.group:fml

       nis.group       nis.group:$group_name
                       the NIS "Netork Information System" (YP) map "group.byname"
                       For example, nis.group:fml

       mysql           mysql:$schema_name

       postgresql      postgresql:$schema_name

       ldap            ldap:$schema_name

METHODS
    "new($map, $args)"
        the constructor. The first argument is a map decribed above.

  
    "open([$flag])"
        open IO operation for the map. $flag is passed to SUPER CLASS open()
        when "file:" map is specified. "open()" is a dummy function in other
        maps now.

  touch()
    create a file if not exists. This method is avaialble for all types but
    dummy for maps other than file: type.

  lock()
    lock. currently, only supported for file map.

  unlock()
    unlock. currently, only supported for file map.

  methods to retrieve data
    get_next_key() is used to get the next primary key incrementally.

    Also, another methods, getline() and get_next_value(), can be considered
    but these are not userd in fml version 8 now.

    "get_next_key()"
        return the next primary key.

  add( $address, [$argv] )
    add $address to the specified map.

    Optionally, you can add KEY=>VALUE structures such as $address => STR or
    $address => [ STR1, STR2, ... ].

  delete( $address )
    delete lines which match $regexp from this map.

  find($regexp [,$args])
    search $regexp in "map" and return the line which matches $regexp. It
    searches $regexp in case insenssitive by default. You can change the
    search behaviour by $args (HASH REFERENCE).

        $args = {
            want           => 'key', # 'key' or 'key,value'
            case_sensitive => 1, # case senssitive
            all            => 1, # get all entries matching $regexp as ARRAY REF
        };

    The result returned by find() is primary key of data or key and value
    e.g the whole line in the file format. find() returns the whole one line
    by default. If want option is specified in $args, return value changes.
    'want' options is 'key' or 'key,value', 'key,value' by default.

    find() returns the result as STRING or ARRAY REFERENCE. You get only the
    first entry as string by default. If you specify "all", you get the
    result(s) as ARRAY REFERENCE.

    For example, to search mail addresses matching $regexp in recipient
    list,

        my $a = $self->find($regexp, { want => 'key', all => 1});
        for my $addr (@$a) {
            do_somethig() if ($addr =~ /$regexp/);
        }

SEQUENCE NUMBER OPERATION
    methods suitable for sequence id operation.

  sequence_increment()
    increment map content by one and return the result (incrmented vlaue).

    CAUTION: now implemented only for file map.

  sequence_replace($seq)
    set the sequence value to $seq. that is, overwrite sequence value by
    number $seq.

    CAUTION: now implemented only for file map.

UTILITY
  
    "error()"
        return the most recent error message if exists.

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

AUTHOR
    Ken'ichi Fukamchi

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

    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 first appeared in fml8 mailing list driver package. See
    "http://www.fml.org/" for more details.