clarify IO::Adapter definition and clean up get_XXX() functions.

remove get_member(), get_active() and get_recipient()
define get_next_key() and get_next_value() and clarify thier definitions.

8 files changed, 218 insertions, 59 deletions

diff --git a/fml/lib/IO/Adapter.pm b/fml/lib/IO/Adapter.pm
index 865781fb..58b6cde1 100644
--- a/fml/lib/IO/Adapter.pm
+++ b/fml/lib/IO/Adapter.pm
@@ -4,7 +4,7 @@
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself.
 #
-# $FML: Adapter.pm,v 1.12 2002/01/27 09:21:51 fukachan Exp $
+# $FML: Adapter.pm,v 1.13 2002/01/27 09:25:23 fukachan Exp $
 #
 
 package IO::Adapter;
@@ -62,6 +62,34 @@ et. al.
 Once you create and open a C<map>,
 you can use the same methods as usual file IO.
 
+=head2 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,
+	};
+
+
 =head2 MAP
 
 C<map> specifies the type of the database we read/write.
@@ -242,45 +270,43 @@ sub touch
 }
 
 
-=head2
+=head2 getXXX(), methods to retrieve data
+
+getXXX() should be classified into:
+
+   getline()        raw data
+                    which may consist of "key" and "value" pair. 
+   get_next_key()   next primary key
+   get_next_value() next value for (the next) key
+
+For a file map, following usage is intuitive such that 
+getline() returns "key value1 value2 ...",
+get_next_key() returns "key" and
+get_next_value() returns "value1 value2 ...", isn't it ?
+
+If possible, getline() should not be used since the definition of
+getline() for a file map is valid but amgibuous for other maps e.g.
+/etc/group, DBMS (SQL based) et. al.
 
 =item C<getline()>
 
 In C<file> map case, it is the same as usual getline() for a file.
 In other maps, it is the same as C<get_next_value()> method below.
 
+=item C<get_next_key()>
+
+return the next primary key.
+
 =item C<get_next_value()>
 
+return the next values (for the next key).
+
 get the next value from the specified database (map).
 For example, this function returns the first column in the next line
 for C<file> map.
 It return the next element of the array,
 in C<array_reference>, C<unix.group>, C<nis.grouop> maps.
 
-=item C<get_member()>
-
-an alias of C<get_next_value()> now.
-
-=item C<get_active()>
-
-an alias of C<get_next_value()> now.
-
-=item C<get_recipient()>
-
-an alias of C<get_next_value()> now.
-
-=cut
-
-# Descriptions: aliases for convenience
-#               request is forwarded to get_next_value() method.
-#    Arguments: OBJ($self)
-# Side Effects: none
-# Return Value: STR
-sub get_member    { my ($self) = @_; $self->get_next_value;}
-sub get_active    { my ($self) = @_; $self->get_next_value;}
-sub get_recipient { my ($self) = @_; $self->get_next_value;}
-
-
 =head2 C<add( $address )>
 
 add $address to the specified map.
@@ -411,7 +437,7 @@ sub find
 
     # search regexp by reading the specified map.
     $self->open;
-    my $fp = $want eq 'key' ? 'get_next_value' : 'getline';
+    my $fp = $want eq 'key' ? 'get_next_key' : 'getline';
     while (defined ($x = $self->$fp())) {
 	if ($show_all) {
 	    if ($case_sensitive) {
diff --git a/fml/lib/IO/Adapter/Array.pm b/fml/lib/IO/Adapter/Array.pm
index 741850bb..52718957 100644
--- a/fml/lib/IO/Adapter/Array.pm
+++ b/fml/lib/IO/Adapter/Array.pm
@@ -1,10 +1,10 @@
 #-*- perl -*-
 #
-#  Copyright (C) 2001 Ken'ichi Fukamachi
+#  Copyright (C) 2001,2002 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.
 #
-# $FML: Array.pm,v 1.20 2001/12/22 09:21:12 fukachan Exp $
+# $FML: Array.pm,v 1.21 2001/12/24 07:40:56 fukachan Exp $
 #
 
 package IO::Adapter::Array;
@@ -22,15 +22,22 @@ IO::Adapter::Array - base class for IO emulation for the ARRAY
 
     use IO::Adapter::Array;
 
-    $map = [ 1, 2, 3 ];
+    $map = [ 'rudo', 'kenken', 'hitomi' ];
     $obj = new IO::Adapter::Array $map;
     $obj->open;
-    while ($x = $obj->get_next_value) { print $x;}
+    while ($x = $obj->get_next_key) { print $x;}
     $obj->close;
 
 =head1 DESCRIPTION
 
 emulate IO operation for the ARRAY.
+One array is similar to a set of primary keys without optional values
+such as a file:
+
+    rudo
+    kenken
+    hitomi
+      ...
 
 =head1 METHODS
 
@@ -103,25 +110,31 @@ sub open
 
 the same as get_next_value().
 
-=item C<get_next_value()>
+=item C<get_next_key()>
 
 return the next element of the array
 
+=item C<get_next_value()>
+
+undef. ambigous in array case.
+
 =cut
 
 
-# Descriptions: forwarded to get_next_value()
+# Descriptions: forwarded to get_next_key()
+#               XXX getline() == get_next_key() is valid in this case.
+#               XXX since this map has only key and no value. 
 #    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: increment the counter in the object
 # Return Value: STR(the next element)
-sub getline { get_next_value(@_);}
+sub getline { get_next_key(@_);}
 
 
 # Descriptions: return the next element of the array
 #    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: increment the counter in the object
 # Return Value: STR(the next element)
-sub get_next_value
+sub get_next_key
 {
     my ($self, $args) = @_;
     my $i  = $self->{_counter}++;
@@ -130,6 +143,12 @@ sub get_next_value
 }
 
 
+sub get_next_value
+{
+    return undef;
+}
+
+
 =head2 C<getpos()>
 
 return the current position in the array
@@ -203,7 +222,7 @@ Ken'ichi Fukamachi
 
 =head1 COPYRIGHT
 
-Copyright (C) 2001 Ken'ichi Fukamachi
+Copyright (C) 2001,2002 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.
diff --git a/fml/lib/IO/Adapter/DBI.pm b/fml/lib/IO/Adapter/DBI.pm
index 9ba60351..9b789c34 100644
--- a/fml/lib/IO/Adapter/DBI.pm
+++ b/fml/lib/IO/Adapter/DBI.pm
@@ -3,7 +3,7 @@
 # Copyright (C) 2000,2001,2002 Ken'ichi Fukamachi
 #          All rights reserved.
 #
-# $FML: DBI.pm,v 1.11 2002/01/27 09:21:52 fukachan Exp $
+# $FML: DBI.pm,v 1.12 2002/01/27 09:25:24 fukachan Exp $
 #
 
 package IO::Adapter::DBI;
@@ -179,17 +179,39 @@ same as C<getline()> now.
 sub getline
 {
     my ($self, $args) = @_;
-    $self->get_next_value($args);
+    $self->get_next_key($args);
 }
 
 
-# Descriptions: get from DBI map
-#    Arguments: OBJ($self) HASH_REF($args)
+# Descriptions: return key from DBI map
+#    Arguments: OBJ($self) HASH_REF($args) STR($mode)
+# Side Effects: none
+# Return Value: STR
+sub get_next_key
+{
+    my ($self, $args) = @_;
+    $self->_get_next_xxx($args, 'key');
+}
+
+
+# Descriptions: return value(s) from DBI map
+#    Arguments: OBJ($self) HASH_REF($args) STR($mode)
 # Side Effects: none
 # Return Value: STR
 sub get_next_value
 {
     my ($self, $args) = @_;
+    $self->_get_next_xxx($args, 'value');
+}
+
+
+# Descriptions: get from DBI map
+#    Arguments: OBJ($self) HASH_REF($args) STR($mode)
+# Side Effects: none
+# Return Value: STR
+sub _get_next_xxx
+{
+    my ($self, $args, $mode) = @_;
 
     # for the first time
     unless ($self->{ _res }) {
@@ -213,7 +235,16 @@ sub get_next_value
 
 	my @row = $self->{ _res }->fetchrow_array;
 	$self->{ _row_pos }++;
-	join(" ", @row);
+	if ($mode eq 'key') {
+	    $row[0];
+	}
+	elsif ($mode eq 'value') {
+	    shift @row;
+	    join(" ", @row);
+	}
+	else {
+	    warn("invalid option");
+	}
     }
     else {
 	$self->error_set( $DBI::errstr );
diff --git a/fml/lib/IO/Adapter/File.pm b/fml/lib/IO/Adapter/File.pm
index b125e68d..c9dc6f3c 100644
--- a/fml/lib/IO/Adapter/File.pm
+++ b/fml/lib/IO/Adapter/File.pm
@@ -1,10 +1,10 @@
 #-*- perl -*-
 #
-#  Copyright (C) 2001 Ken'ichi Fukamachi
+#  Copyright (C) 2001,2002 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.
 #
-# $FML: File.pm,v 1.26 2001/12/24 07:40:56 fukachan Exp $
+# $FML: File.pm,v 1.27 2001/12/24 07:44:35 fukachan Exp $
 #
 
 package IO::Adapter::File;
@@ -192,14 +192,35 @@ sub getline
 }
 
 
-# Descriptions: get string for new line after
-#               clean up for fml
+# Descriptions: return the next key
+#    Arguments: OBJ($self)
+# Side Effects: none
+# Return Value: STR
+sub get_next_key
+{
+    my ($self) = @_;
+    $self->_get_next_xxx('key');
+}
+
+
+# Descriptions: return value(s) for the next key
 #    Arguments: OBJ($self)
 # Side Effects: none
 # Return Value: STR
 sub get_next_value
 {
     my ($self) = @_;
+    $self->_get_next_xxx('value');
+}
+
+
+# Descriptions: get data and return key or value by $mode.
+#    Arguments: OBJ($self) STR($mode)
+# Side Effects: none
+# Return Value: STR
+sub _get_next_xxx
+{
+    my ($self, $mode) = @_;
 
     my ($buf) = '';
     my $fh = $self->{_fh};
@@ -218,9 +239,14 @@ sub get_next_value
 	}
 
 	if (defined $buf) {
-	    my @buf = split(/\s+/, $buf);
-	    $buf    = $buf[0];
-	    $buf    =~ s/[\r\n]*$//o;
+	    $buf =~ s/[\r\n]*$//o;
+	    my ($key, $value) = split(/\s+/, $buf, 2);
+	    if ($mode eq 'key') {
+		$buf = $key;
+	    }
+	    elsif ($mode eq 'value') {
+		$buf = $value;
+	    }
 	    $ec++;
 	}
 	return $buf;
@@ -421,7 +447,7 @@ Ken'ichi Fukamachi
 
 =head1 COPYRIGHT
 
-Copyright (C) 2001 Ken'ichi Fukamachi
+Copyright (C) 2001,2002 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.
diff --git a/fml/lib/IO/Adapter/IMPLEMENTATION.jp b/fml/lib/IO/Adapter/IMPLEMENTATION.jp
new file mode 100644
index 00000000..bb425b75
--- /dev/null
+++ b/fml/lib/IO/Adapter/IMPLEMENTATION.jp
@@ -0,0 +1,57 @@
+		諸問題
+
+
+○ 問題: getline() と get_XXX() メソッドについて
+
+ファイルとそれ以外では事情がかなり異なることに留意することが重要である。
+
+* ファイル(スペース区切り)では
+
+	key1
+	key2	value2
+	key3	value3a value3b
+
+というデータ構造が多い。これは
+
+	ファイル = {
+		key1 => undef,
+		key2 => [ value2 ],
+		key3 => [ value3a, value3b ], 
+	};
+
+という perl のデータ構造に相当するだろう。
+
+
+* 一方、/etc/group は : と , 区切りと
+
+	key:value1, value2
+
+いう点を考えると、上のファイルと一見同様だが、
+
+	$obj = new IO::Adapter 'unix.group:wheel';
+
+という場合は、
+
+	wheel グループ = {
+
+		root	=> undef,
+		だれか  => undef,
+			....
+
+	};
+
+もしくは
+
+	wheel グループ = [
+
+		root	=> undef,
+		だれか  => undef,
+			....
+
+	];
+
+
+だが、汎用性を考えればハッシュにあわせるべきだろう。
+
+----------
+$FML$
diff --git a/fml/lib/IO/Adapter/MySQL.pm b/fml/lib/IO/Adapter/MySQL.pm
index 1a5bc529..e48395e6 100644
--- a/fml/lib/IO/Adapter/MySQL.pm
+++ b/fml/lib/IO/Adapter/MySQL.pm
@@ -1,9 +1,9 @@
 #-*- perl -*-
 #
-# Copyright (C) 2000,2001 Ken'ichi Fukamachi
+# Copyright (C) 2000,2001,2002 Ken'ichi Fukamachi
 #          All rights reserved.
 #
-# $FML: MySQL.pm,v 1.17 2001/12/22 09:21:13 fukachan Exp $
+# $FML: MySQL.pm,v 1.18 2001/12/24 07:40:57 fukachan Exp $
 #
 
 
@@ -145,7 +145,7 @@ sub setpos
     }
 
     # discard
-    while ($i-- > 0) { $self->get_next_value();}
+    while ($i-- > 0) { $self->get_next_key();}
 }
 
 
@@ -193,7 +193,7 @@ Ken'ichi Fukamachi
 
 =head1 COPYRIGHT
 
-Copyright (C) 2001 Ken'ichi Fukamachi
+Copyright (C) 2000,2001,2002 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.
diff --git a/fml/lib/IO/t/array_map.pl b/fml/lib/IO/t/array_map.pl
index 10a46cbd..8079ad74 100755
--- a/fml/lib/IO/t/array_map.pl
+++ b/fml/lib/IO/t/array_map.pl
@@ -1,10 +1,10 @@
 #-*- perl -*-
 #
-#  Copyright (C) 2001 Ken'ichi Fukamachi
+#  Copyright (C) 2001,2002 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. 
 #
-# $FML: array_map.pl,v 1.3 2001/05/04 14:32:34 fukachan Exp $
+# $FML: array_map.pl,v 1.4 2001/08/19 16:12:25 fukachan Exp $
 #
 
 use Carp;
@@ -19,7 +19,7 @@ if ($obj->error) { croak( $obj->error );}
 
 my $x;
 my @recipients = ();
-while ($x = $obj->get_recipient) { push(@recipients, $x); }
+while ($x = $obj->get_next_key) { push(@recipients, $x); }
 $obj->close;
 
 my $ok = 0;
diff --git a/fml/lib/IO/t/unixgroup_map.pl b/fml/lib/IO/t/unixgroup_map.pl
index 392ae842..2cde661e 100755
--- a/fml/lib/IO/t/unixgroup_map.pl
+++ b/fml/lib/IO/t/unixgroup_map.pl
@@ -1,10 +1,10 @@
 #-*- perl -*-
 #
-#  Copyright (C) 2001 Ken'ichi Fukamachi
+#  Copyright (C) 2001,2002 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. 
 #
-# $FML: unixgroup_map.pl,v 1.4 2001/05/04 14:32:34 fukachan Exp $
+# $FML: unixgroup_map.pl,v 1.5 2001/08/19 16:12:25 fukachan Exp $
 #
 
 use Carp;
@@ -22,7 +22,7 @@ if ($obj->error) { croak( $obj->error );}
 
 my $x;
 my @x = ();
-while ($x = $obj->get_recipient) { push(@x, $x);}
+while ($x = $obj->get_next_key) { push(@x, $x);}
 $obj->close;
 
 my $bad = 0;