overhaul: fix comments and messages. validate initial value.

5 files changed, 44 insertions, 33 deletions

diff --git a/fml/lib/IO/Adapter.pm b/fml/lib/IO/Adapter.pm
index 2613a06c..d44151ba 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.32 2004/04/11 12:58:38 fukachan Exp $
+# $FML: Adapter.pm,v 1.33 2004/04/27 13:31:54 fukachan Exp $
 #
 
 package IO::Adapter;
@@ -23,7 +23,7 @@ END   {}
 
 =head1 NAME
 
-IO::Adapter - adapter for several IO interfaces
+IO::Adapter - adapter for several IO interfaces.
 
 =head1 SYNOPSIS
 
@@ -110,7 +110,7 @@ This wrapper provides IO like a usual file for the specified C<$map>.
 
    map name        descriptions or examples
    ---------------------------------------------------
-   file            file:$file_name
+   file            file:$file_name (prefix file: is optional).
                    For example, file:/var/spool/ml/elena/recipients
 
    unix.group      unix.group:$group_name
@@ -138,7 +138,7 @@ the constructor. The first argument is a map decribed above.
 
 
 # Descriptions: a constructor, which prepare IO operations for the
-#               given $map.
+#               specified $map.
 #    Arguments: OBJ($self) STR($map) HASH_REF($args)
 # Side Effects: @ISA is modified
 #               load and import sub-class
@@ -266,9 +266,8 @@ sub open
 
 =head2 touch()
 
-create a file if not exists.
-This method is avaialble for file: type.
-It is dummy for maps other than file: type.
+create a file if not exists. This method is avaialble for all types
+but dummy for maps other than file: type.
 
 =cut
 
@@ -299,7 +298,7 @@ unlock. currently, only supported for file map.
 =cut
 
 
-# Descriptions: create a file if not exists.
+# Descriptions: lock. currently, only supported for file map.
 #    Arguments: OBJ($self)
 # Side Effects: create $map if needed or possible
 # Return Value: none
@@ -314,7 +313,7 @@ sub lock
 }
 
 
-# Descriptions: create a file if not exists.
+# Descriptions: unlock. currently, only supported for file map.
 #    Arguments: OBJ($self)
 # Side Effects: create $map if needed or possible
 # Return Value: none
@@ -352,7 +351,7 @@ or
 
 =head2 delete( $address )
 
-delete lines which matches $regexp from this map.
+delete lines which match $regexp from this map.
 
 =cut
 
@@ -417,14 +416,14 @@ You can change the search behaviour by C<$args> (HASH REFERENCE).
 
 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 options is specified in $args, return value
+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 C<all>, you get the result(s) as ARRAY REFERENCE.
 
-For example, to search mail addresses in recipient list,
+For example, to search mail addresses matching $regexp in recipient list,
 
     my $a = $self->find($regexp, { want => 'key', all => 1});
     for my $addr (@$a) {
@@ -451,7 +450,8 @@ sub find
 	return $self->md_find($regexp, $args);
     }
 
-    # XXX NO, quotemeta $regexp before call find() method.
+    # XXX NO, NOT USE quotemeta $regexp before call find() method HERE.
+    # XXX PLEASE CARE REGEXP BEFORE CALL IO::Adapter.
     # we may need quote for special address e.g. a+b@domain.
     # $regexp = quotemeta($regexp);
 
@@ -506,16 +506,20 @@ methods suitable for sequence id operation.
 
 increment map content by one and return the result (incrmented vlaue).
 
+CAUTION: now implemented only for file map.
+
 =head2 sequence_replace($seq)
 
 set the sequence value to $seq.
 that is, overwrite sequence value by number $seq.
 
+CAUTION: now implemented only for file map.
+
 =cut
 
 
 # Descriptions: increment map content by one and return the result
-#               (incrmented vlaue).
+#               (incremented vlaue).
 #    Arguments: OBJ($self)
 # Side Effects: create $map if needed or possible
 # Return Value: NUM(> 1, 0 is failure)
@@ -556,6 +560,15 @@ sub sequence_replace
 }
 
 
+=head1 UTILITY
+
+=head2
+
+=item C<error()>
+
+return the most recent error message if exists.
+
+
 =head1 DESTRUCTOR
 
 =head2 DESTROY
@@ -575,13 +588,6 @@ sub DESTROY
 }
 
 
-
-=head2
-
-=item C<error()>
-
-return the most recent error message if exists.
-
 =head1 CODING STYLE
 
 See C<http://www.fml.org/software/FNF/> on fml coding style guide.
diff --git a/fml/lib/IO/Adapter/Array.pm b/fml/lib/IO/Adapter/Array.pm
index 7b8b3779..014439d1 100644
--- a/fml/lib/IO/Adapter/Array.pm
+++ b/fml/lib/IO/Adapter/Array.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: Array.pm,v 1.34 2003/11/29 06:31:48 fukachan Exp $
+# $FML: Array.pm,v 1.35 2004/01/24 09:03:55 fukachan Exp $
 #
 
 package IO::Adapter::Array;
@@ -84,7 +84,7 @@ $flag is "r" only (read only) now.
 #                              flag => $flag
 #                  _array_reference => ARRAY_REFERENCE
 #               }
-# Side Effects: malloc @elements array
+# Side Effects: malloc @elements array.
 # Return Value: ARRAY_REF
 sub open
 {
@@ -102,7 +102,7 @@ sub open
     $self->{_elements}     = $r_array;
     $self->{_num_elements} = $#elements;
     $self->{_counter}      = 0;
-    return( @elements ? \@elements : undef );
+    return( @elements ? \@elements : [] );
 }
 
 
@@ -119,7 +119,7 @@ return the next element of the array.
 =cut
 
 
-# Descriptions: forwarded to get_next_key()
+# 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)
@@ -128,7 +128,8 @@ return the next element of the array.
 sub getline { get_next_key(@_);}
 
 
-# Descriptions: return (key, values, ... ) as ARRAY_REF
+# Descriptions: return (key, values, ... ) as ARRAY_REF.
+#               XXX no value in the case of this map.
 #    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: none
 # Return Value: ARRAY_REF
@@ -139,7 +140,7 @@ sub get_key_values_as_array_ref
     return [ $x ];
 }
 
-# Descriptions: return the next element of the array
+# 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)
@@ -198,6 +199,7 @@ end of IO operation. It is a dummy.
 
 =cut
 
+
 # Descriptions: echeck whether end of the array is not now.
 #    Arguments: OJB($self)
 # Side Effects: none
@@ -206,6 +208,8 @@ end of IO operation. It is a dummy.
 sub eof
 {
     my ($self) = @_;
+
+    # XXX-TODO: > ? >= ? OK?
     $self->{_counter} > $self->{_num_elements} ? 1 : 0;
 }
 
diff --git a/fml/lib/IO/Adapter/ErrorStatus.pm b/fml/lib/IO/Adapter/ErrorStatus.pm
index d294e777..0a11f5f1 100644
--- a/fml/lib/IO/Adapter/ErrorStatus.pm
+++ b/fml/lib/IO/Adapter/ErrorStatus.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: ErrorStatus.pm,v 1.7 2003/08/23 15:33:16 fukachan Exp $
+# $FML: ErrorStatus.pm,v 1.8 2004/01/24 09:03:56 fukachan Exp $
 #
 
 package IO::Adapter::ErrorStatus;
@@ -19,7 +19,7 @@ require Exporter;
 
 =head1 NAME
 
-IO::Adapter::ErrorStatus - error handling component
+IO::Adapter::ErrorStatus - error handling component.
 
 =head1 SYNOPSIS
 
diff --git a/fml/lib/IO/Adapter/NIS.pm b/fml/lib/IO/Adapter/NIS.pm
index 95ce1bf7..6d904cd2 100644
--- a/fml/lib/IO/Adapter/NIS.pm
+++ b/fml/lib/IO/Adapter/NIS.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: NIS.pm,v 1.22 2003/08/23 15:33:16 fukachan Exp $
+# $FML: NIS.pm,v 1.23 2004/01/24 09:00:53 fukachan Exp $
 #
 
 package IO::Adapter::NIS;
@@ -19,7 +19,7 @@ use IO::Adapter::Array;
 
 =head1 NAME
 
-IO::Adapter::NIS - NIS map operations
+IO::Adapter::NIS - NIS map operations.
 
 =head1 SYNOPSIS
 
@@ -62,6 +62,7 @@ sub configure
 
     # XXX-TODO: UNIX only.
     # XXX-TODO: we call "ypmatch" but should use full-path if could.
+    # XXX-TODO: who validate $key value ?
     # emulate an array on memory
     my $key        = $me->{_name};
     my (@x)        = split(/:/, `ypmatch $key group.byname`);
diff --git a/fml/lib/IO/Adapter/UnixGroup.pm b/fml/lib/IO/Adapter/UnixGroup.pm
index e5100833..bbddcf7e 100644
--- a/fml/lib/IO/Adapter/UnixGroup.pm
+++ b/fml/lib/IO/Adapter/UnixGroup.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: UnixGroup.pm,v 1.20 2003/08/23 15:33:16 fukachan Exp $
+# $FML: UnixGroup.pm,v 1.21 2004/01/24 09:00:53 fukachan Exp $
 #
 
 package IO::Adapter::UnixGroup;
@@ -19,7 +19,7 @@ use IO::Adapter::Array;
 
 =head1 NAME
 
-IO::Adapter::UnixGroup - IO wrapper to read /etc/group
+IO::Adapter::UnixGroup - IO wrapper to read /etc/group.
 
 =head1 SYNOPSIS