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.

1 files changed, 53 insertions, 27 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) {