Added method Hash2grs into GRS1 module.

[simpleserver-moved-to-github.git] / GRS1.pm

diff --git a/GRS1.pm b/GRS1.pm
index a06b0ec..2f322ac 100644 (file)
--- a/GRS1.pm
+++ b/GRS1.pm
@@ -5,18 +5,50 @@ use IO::Handle;
 use Carp;
 
 
+
 sub new {
-       my $class = shift;
+       my ($class, $href, $map) = @_;
        my $self = {};
 
        $self->{ELEMENTS} = [];
-       $self->{FH} = *STDOUT;          ## Default output handle is STDOUT
+       $self->{FH} = *STDOUT;                          ## Default output handle is STDOUT
+       $self->{MAP} = $map;
        bless $self, $class;
+       if (defined($href) && ref($href) eq 'HASH') {
+               if (!defined($map)) {
+                       croak "Usage: new Net::Z3950::GRS1($href, $map);";
+               }       
+               $self->Hash2grs($href);
+       }
 
        return $self;
 }
 
 
+sub Hash2grs {
+       my ($self, $href, $mapping) = @_;
+       my $key;
+       my $content;
+       my $aref;
+
+       $mapping = defined($mapping) ? $mapping : $self->{MAP};
+       foreach $key (keys %$href) {
+               $content = $href->{$key};
+               if (!defined($aref = $mapping->{$key})) {
+                       print STDERR "Hash2grs: Unmapped key: '$key'\n";
+                       next;
+               }
+               if (ref($content) eq 'HASH') {                                  ## Subtree?
+                       my $subtree = new Net::Z3950::GRS1($content);
+                       $self->AddElement($aref->[0], $aref->[1], &Net::Z3950::GRS1::ElementData::Subtree, $subtree);
+               } elsif (ref($content) eq '') {                                 ## Regular string?
+                       $self->AddElement($aref->[0], $aref->[1], &Net::Z3950::GRS1::ElementData::String, $content);
+               } else {
+                       print STDERR "Hash2grs: Unsupported content type\n";
+                       next;
+               }
+       }
+}
 sub GetElementList {
        my $self = shift;
 
@@ -197,17 +229,85 @@ Net::Z3950::Record::GRS1 - Perl package used to encode GRS-1 records.
 
 =head1 SYNOPSIS
 
-  use Net::Z3950::Record::GRS1;
+  use Net::Z3950::GRS1;
 
   my $a_grs1_record = new Net::Z3950::Record::GRS1;
   my $another_grs1_record = new Net::Z3950::Record::GRS1;
 
   $a_grs1_record->AddElement($type, $value, $content);
-  $a_grs1_record->render();
+  $a_grs1_record->Render();
 
 =head1 DESCRIPTION
 
-Here goes the documentation. I guess, you'll have to wait for it!
+This Perl module helps you to create and manipulate GRS-1 records (generic record syntax).
+So far, you have only access to three methods:
+
+=head2 new
+
+Creates a new GRS-1 object,
+
+  my $grs1 = new Net::Z3950::GRS1;
+
+=head2 AddElement
+
+Lets you add entries to a GRS-1 object. The method should be called this way,
+
+  $grs1->AddElement($type, $value, $which, $content);
+
+where $type should be an integer, and $value is free text. The $which argument should
+contain one of the constants listed in Appendix A. Finally, $content contains the "thing"
+that should be stored in this entry. The structure of $content should match the chosen
+element data type. For
+
+  $which == Net::Z3950::GRS1::ElementData::String;
+
+$content should be some kind of scalar. If on the other hand,
+
+  $which == Net::Z3950::GRS1::ElementData::Subtree;
+
+$content should be a GRS1 object.
+
+=head3 Render
+
+This method digs through the GRS-1 data structure and renders the record. You call it
+this way,
+
+  $grs1->Render();
+
+If you want to access the rendered record through a variable, you can do it like this,
+
+  my $record_as_string;
+  $grs1->Render(POOL => \$record_as_string);
+
+If you want it stored in a file, Render should be called this way,
+
+  $grs1->Render(FILE => 'record.grs1');
+
+When no file name is specified, you can choose to stream the rendered record, for instance,
+
+  $grs1->Render(HANDLE => *STDOUT);            ## or
+  $grs1->Render(HANDLE => *STDERR);            ## or
+  $grs1->Render(HANDLE => *MY_HANDLE);
+
+=head1 APPENDIX A
+
+These element data types are specified in the Z39.50 protocol:
+
+  Net::Z3950::GRS1::ElementData::Octets
+  Net::Z3950::GRS1::ElementData::Numeric
+  Net::Z3950::GRS1::ElementData::Date
+  Net::Z3950::GRS1::ElementData::Ext
+  Net::Z3950::GRS1::ElementData::String                        <---
+  Net::Z3950::GRS1::ElementData::TrueOrFalse
+  Net::Z3950::GRS1::ElementData::OID
+  Net::Z3950::GRS1::ElementData::IntUnit
+  Net::Z3950::GRS1::ElementData::ElementNotThere
+  Net::Z3950::GRS1::ElementData::ElementEmpty
+  Net::Z3950::GRS1::ElementData::NoDataRequested
+  Net::Z3950::GRS1::ElementData::Diagnostic
+  Net::Z3950::GRS1::ElementData::Subtree               <---
+
+Only the '<---' marked types are so far supported in this package.
 
 =head1 AUTHOR
 
@@ -222,7 +322,13 @@ Specification of the GRS-1 standard, for instance in the Z39.50 protocol specifi
 =cut
 
 #$Log: GRS1.pm,v $
-#Revision 1.1  2001-03-13 14:17:15  sondberg
+#Revision 1.3  2001-05-17 13:43:04  sondberg
+#Added method Hash2grs into GRS1 module.
+#
+#Revision 1.2  2001/03/13 14:53:15  sondberg
+#Added a few lines of documentation into GRS1.pm.
+#
+#Revision 1.1  2001/03/13 14:17:15  sondberg
 #Added support for GRS-1.
 #