perl/lib/IDZebra/Data1.pm

   1 #!/usr/bin/perl
   2 # ============================================================================
   3 # Zebra perl API header
   4 # =============================================================================
   5 use strict;
   6 use Carp;
   7 # =============================================================================
   8 package IDZebra::Data1;
   9 use IDZebra;
  10 1;
  11
  12 # -----------------------------------------------------------------------------
  13 # Class constructors and destructor
  14 # -----------------------------------------------------------------------------
  15 sub get {
  16     my ($proto, $handle, $mem) = @_;
  17     my $class = ref($proto) || $proto;
  18     my $self = {};
  19     bless ($self,$class);
  20
  21     $self->{dh} = $handle;
  22     $self->{mem} = $mem;
  23     # data1_destroy is not going to be called, when object is released
  24     $self->{dflag} = 0;
  25
  26     return ($self);
  27 }
  28
  29 sub new {
  30     my ($proto, $mem, $flag) = @_;
  31     my $class = ref($proto) || $proto;
  32     my $self = {};
  33
  34     bless ($self,$class);
  35
  36     unless ($self->{dh} = IDZebra::data1_createx($flag)) {
  37         croak ("Cannot create data1 handle");
  38     }
  39
  40     # data1_destroy going to be called, when object is released
  41     $self->{dflag} = 1;
  42
  43     unless ($self->{mem} = $mem) {
  44         croak ("Missing NMEM handle");
  45     }
  46
  47     return ($self);
  48 }
  49
  50 sub DESTROY {
  51     my $self = shift;
  52     if ($self->{dh}) {
  53         if ($self->{dflag}) { IDZebra::data1_destroy($self->{dh}) }
  54         $self->{dh} = undef;
  55     }
  56 }
  57
  58 # -----------------------------------------------------------------------------
  59 # Profile information
  60 # -----------------------------------------------------------------------------
  61 # Not usable...
  62 sub path_fopen {
  63     my ($self, $file, $mode) = @_;
  64     return (IDZebra::data1_path_fopen ($self->{dh}, $file, $mode));
  65 }
  66
  67 sub tabpath {
  68     my ($self, $path) = @_;
  69     if (defined($path)) { IDZebra::data1_set_tabpath($self->{dh}, $path); }
  70     return (IDZebra::data1_get_tabpath($self->{dh}));
  71 }
  72
  73 sub tabroot {
  74     my ($self, $path) = @_;
  75     if (defined($path)) { IDZebra::data1_set_tabroot($self->{dh}, $path); }
  76     return (IDZebra::data1_get_tabroot($self->{dh}));
  77 }
  78
  79 # -----------------------------------------------------------------------------
  80 # D1 Structure manipulation
  81 # -----------------------------------------------------------------------------
  82 sub mk_root {
  83     my ($self, $name) = @_;
  84     return (IDZebra::data1_mk_root($self->{dh}, $self->{mem}, $name));
  85 }
  86
  87 sub set_root {
  88     my ($self, $node, $name) = @_;
  89     IDZebra::data1_set_root($self->{dh}, $node, $self->{mem}, $name);
  90 }
  91
  92 sub mk_tag {
  93     my ($self, $parent, $tag, @attributes) = @_;
  94     return (IDZebra::data1_mk_tag($self->{dh}, $self->{mem},
  95                                   $tag, \@attributes, $parent));
  96 }
  97
  98 sub tag_add_attr {
  99     my ($self, $node, @attributes) = @_;
 100     IDZebra::data1_tag_add_attr ($self->{dh}, $self->{mem},
 101                                  $node, \@attributes);
 102 }
 103
 104 sub mk_text {
 105     my ($self, $parent, $text) = @_;
 106     return (IDZebra::data1_mk_text($self->{dh}, $self->{mem},
 107                                    $text, $parent));
 108 }
 109
 110 sub mk_comment {
 111     my ($self, $parent, $text) = @_;
 112     return (IDZebra::data1_mk_comment($self->{dh}, $self->{mem},
 113                                    $text, $parent));
 114 }
 115
 116 sub mk_preprocess {
 117     my ($self, $parent, $target, @attributes) = @_;
 118     return (IDZebra::data1_mk_preprocess($self->{dh}, $self->{mem},
 119                                          $target, \@attributes, $parent));
 120 }
 121
 122
 123 sub pr_tree {
 124     my ($self, $node) = @_;
 125     IDZebra::data1_print_tree($self->{dh}, $node);
 126 }
 127
 128 sub free_tree {
 129     my ($self, $node) = @_;
 130     IDZebra::data1_free_tree($self->{dh}, $node);
 131 }
 132
 133 # =============================================================================
 134
 135 __END__
 136
 137 =head1 NAME
 138
 139 IDZebra::Data1 - OO Aproach interface for data1 structures
 140
 141 =head1 SYNOPSIS
 142
 143    use IDZebra::Data1;
 144
 145    my $m = IDZebra::nmem_create();
 146    my $d1=IDZebra::Data1->new($m,$IDZebra::DATA1_FLAG_XML);
 147    my $root = $d1->mk_root('ostriches');
 148    my $tag  = $d1->mk_tag($root,'emu',('speed'  => 120,
 149                                        'height' => 110));
 150    $d1->pr_tree($root);
 151
 152 =head1 DESCRIPTION
 153
 154 I never managed to understand data1 entirely. Probably Adam, or someone else from IndexData could write a more deep introduction here. However here are some ideas:
 155
 156 Data1 structures are used in zebra to represent structured data. You can map an xml structure, a marc record, or anything in D1. These structures are built by different filters - this is called "extraction" in zebra's code.
 157
 158 When zebra asks a filter to extract a file, it provides a data1 handle, which can be used to
 159
 160   - reach profile information, provided in zebra.cfg, and other refered
 161     configuration files, (like tab path).
 162
 163   - build data1 structures
 164
 165 In one word, a data1 handle is a kind of context in the d1 API. This handle is represented here as a IDZebra::Data1 object. When you implement a filter, you'll get this object ready for use, otherwise, you'll have to prepare an NMEM handle, and call the constructor:
 166
 167    my $m = IDZebra::nmem_create();
 168    my $dh = IDZebra::Data1->new($m,$IDZebra::DATA1_FLAG_XML);
 169
 170 What is FLAG_XML? I don't know exactly. You don't have to worry about it, it's already set, if you implement a filter.
 171
 172 =head1 PROFILE INFORMATION
 173
 174 =item $d1->tabpath([$path])
 175
 176 Set and/or get the tab path. This is a colon separated list of directories, where different configuration files can be found.
 177
 178 =item $d1->tabroot([$path])
 179
 180 Set and/or get the tab root.
 181
 182 =head1 BUILDING DATA STRUCTURES
 183
 184 It's obvious, that first of all you have to create a root node:
 185
 186    my $r1 = $d1->mk_root('pod');
 187
 188 This is going to initialize the abstract syntax "pod" (trying to open and parse pod.abs). I don't know why exactly, but then, you'll have to create a root tag as well, under the same name.
 189
 190    my $root=$d1->mk_tag($r1,'pod');
 191
 192 Then just continue, to add child nodes, as tags, text nodes... to your structure.
 193
 194 =item $d1->mk_root($name)
 195
 196 Create a root node, with the given name. (name is type in d1 terminology?)
 197
 198 =item $d1->set_root($node, $name)
 199
 200 Makes an existing node into root node, under the given name
 201
 202 =item $d1->mk_tag($parent, $name, [@attributes])
 203
 204 Add a tag to the parent node, with the given name and attributes. For example:
 205
 206    my $tag  = $d1->mk_tag($root,'emu',('speed'  => 120,
 207                                        'height' => 110));
 208
 209 =item $d1->tag_add_attr($node, @attributes)
 210
 211 Add attributes to an existing node
 212
 213 =item $d1->mk_text($parent, $text)
 214
 215 Add a text node to the given parent
 216
 217 =item $d1->mk_comment($parent, $text)
 218
 219 Add a comment node to the given parent
 220
 221 =item $d1->mk_preprocess($parent, $target, $attributes)
 222
 223 ???
 224
 225 =item $d1->pr_tree($node)
 226
 227 Prints data1 tree on STDOUT;
 228
 229 =item $d1->free_tree($node)
 230
 231 Destroys a data1 node structure;
 232
 233 =head1 COPYRIGHT
 234
 235 Fill in
 236
 237 =head1 AUTHOR
 238
 239 Peter Popovics, pop@technomat.hu
 240
 241 =head1 SEE ALSO
 242
 243 IDZebra, Zebra documentation
 244
 245 =cut