462a303dede5dab5a21197b90559a2635fdd08ef
[webpac2] / lib / WebPAC / Input.pm
1 package WebPAC::Input;
2
3 use warnings;
4 use strict;
5
6 use lib 'lib';
7
8 use WebPAC::Common;
9 use base qw/WebPAC::Common/;
10 use Data::Dump qw/dump/;
11 use Encode qw/decode from_to/;
12 use YAML;
13
14 =head1 NAME
15
16 WebPAC::Input - read different file formats into WebPAC
17
18 =cut
19
20 our $VERSION = '0.19';
21
22 =head1 SYNOPSIS
23
24 This module implements input as database which have fixed and known
25 I<size> while indexing and single unique numeric identifier for database
26 position ranging from 1 to I<size>.
27
28 Simply, something that is indexed by unmber from 1 .. I<size>.
29
30 Examples of such databases are CDS/ISIS files, MARC files, lines in
31 text file, and so on.
32
33 Specific file formats are implemented using low-level interface modules,
34 located in C<WebPAC::Input::*> namespace which export C<open_db>,
35 C<fetch_rec> and optional C<init> functions.
36
37 Perhaps a little code snippet.
38
39         use WebPAC::Input;
40
41         my $db = WebPAC::Input->new(
42                 module => 'WebPAC::Input::ISIS',
43         );
44
45         $db->open( path => '/path/to/database' );
46         print "database size: ",$db->size,"\n";
47         while (my $rec = $db->fetch) {
48                 # do something with $rec
49         }
50
51
52
53 =head1 FUNCTIONS
54
55 =head2 new
56
57 Create new input database object.
58
59   my $db = new WebPAC::Input(
60         module => 'WebPAC::Input::MARC',
61         recode => 'char pairs',
62         no_progress_bar => 1,
63         input_config => {
64                 mapping => [ 'foo', 'bar', 'baz' ],
65         },
66   );
67
68 C<module> is low-level file format module. See L<WebPAC::Input::ISIS> and
69 L<WebPAC::Input::MARC>.
70
71 C<recode> is optional string constisting of character or words pairs that
72 should be replaced in input stream.
73
74 C<no_progress_bar> disables progress bar output on C<STDOUT>
75
76 This function will also call low-level C<init> if it exists with same
77 parametars.
78
79 =cut
80
81 sub new {
82         my $class = shift;
83         my $self = {@_};
84         bless($self, $class);
85
86         my $log = $self->_get_logger;
87
88         $log->logconfess("code_page argument is not suppored any more.") if $self->{code_page};
89         $log->logconfess("encoding argument is not suppored any more.") if $self->{encoding};
90         $log->logconfess("lookup argument is not suppored any more. rewrite call to lookup_ref") if $self->{lookup};
91         $log->logconfess("low_mem argument is not suppored any more. rewrite it to load_row and save_row") if $self->{low_mem};
92
93         $log->logconfess("specify low-level file format module") unless ($self->{module});
94         my $module_path = $self->{module};
95         $module_path =~ s#::#/#g;
96         $module_path .= '.pm';
97         $log->debug("require low-level module $self->{module} from $module_path");
98
99         require $module_path;
100
101         $self ? return $self : return undef;
102 }
103
104 =head2 open
105
106 This function will read whole database in memory and produce lookups.
107
108  my $store;     # simple in-memory hash
109
110  $input->open(
111         path => '/path/to/database/file',
112         input_encoding => 'cp852',
113         strict_encoding => 0,
114         limit => 500,
115         offset => 6000,
116         stats => 1,
117         lookup_coderef => sub {
118                 my $rec = shift;
119                 # store lookups
120         },
121         modify_records => {
122                 900 => { '^a' => { ' : ' => '^b' } },
123                 901 => { '*' => { '^b' => ' ; ' } },
124         },
125         modify_file => 'conf/modify/mapping.map',
126         save_row => sub {
127                 my $a = shift;
128                 $store->{ $a->{id} } = $a->{row};
129         },
130         load_row => sub {
131                 my $a = shift;
132                 return defined($store->{ $a->{id} }) &&
133                         $store->{ $a->{id} };
134         },
135
136  );
137
138 By default, C<input_encoding> is assumed to be C<cp852>.
139
140 C<offset> is optional parametar to skip records at beginning.
141
142 C<limit> is optional parametar to read just C<limit> records from database
143
144 C<stats> create optional report about usage of fields and subfields
145
146 C<lookup_coderef> is closure to called to save data into lookups
147
148 C<modify_records> specify mapping from subfields to delimiters or from
149 delimiters to subfields, as well as oprations on fields (if subfield is
150 defined as C<*>.
151
152 C<modify_file> is alternative for C<modify_records> above which preserves order and offers
153 (hopefully) simplier sintax than YAML or perl (see L</modify_file_regex>). This option
154 overrides C<modify_records> if both exists for same input.
155
156 C<save_row> and C<load_row> are low-level implementation of store engine. Calling convention
157 is documented in example above.
158
159 C<strict_encoding> should really default to 1, but it doesn't for now.
160
161 Returns size of database, regardless of C<offset> and C<limit>
162 parametars, see also C<size>.
163
164 =cut
165
166 sub open {
167         my $self = shift;
168         my $arg = {@_};
169
170         my $log = $self->_get_logger();
171         $log->debug( "arguments: ",dump( $arg ));
172
173         $log->logconfess("encoding argument is not suppored any more.") if $self->{encoding};
174         $log->logconfess("code_page argument is not suppored any more.") if $self->{code_page};
175         $log->logconfess("lookup argument is not suppored any more. rewrite call to lookup_coderef") if ($arg->{lookup});
176         $log->logconfess("lookup_coderef must be CODE, not ",ref($arg->{lookup_coderef}))
177                 if ($arg->{lookup_coderef} && ref($arg->{lookup_coderef}) ne 'CODE');
178
179         $log->debug( $arg->{lookup_coderef} ? '' : 'not ', "using lookup_coderef");
180
181         $log->logcroak("need path") if (! $arg->{'path'});
182         my $input_encoding = $arg->{'input_encoding'} || $self->{'input_encoding'} || 'cp852';
183
184         # store data in object
185         $self->{$_} = $arg->{$_} foreach grep { defined $arg->{$_} } qw(path offset limit);
186
187         if ($arg->{load_row} || $arg->{save_row}) {
188                 $log->logconfess("save_row and load_row must be defined in pair and be CODE") unless (
189                         ref($arg->{load_row}) eq 'CODE' &&
190                         ref($arg->{save_row}) eq 'CODE'
191                 );
192                 $self->{load_row} = $arg->{load_row};
193                 $self->{save_row} = $arg->{save_row};
194                 $log->debug("using load_row and save_row instead of in-memory hash");
195         }
196
197         my $filter_ref;
198         my $recode_regex;
199         my $recode_map;
200
201         if ($self->{recode}) {
202                 my @r = split(/\s/, $self->{recode});
203                 if ($#r % 2 != 1) {
204                         $log->logwarn("recode needs even number of elements (some number of valid pairs)");
205                 } else {
206                         while (@r) {
207                                 my $from = shift @r;
208                                 my $to = shift @r;
209                                 $from =~ s/^\\x([0-9a-f]{2})/chr(hex($1))/eig;
210                                 $recode_map->{$from} = $to;
211                         }
212
213                         $recode_regex = join '|' => keys %{ $recode_map };
214
215                         $log->debug("using recode regex: $recode_regex");
216                 }
217
218         }
219
220         my $rec_regex;
221         if (my $p = $arg->{modify_file}) {
222                 $log->debug("using modify_file $p");
223                 $rec_regex = $self->modify_file_regexps( $p );
224         } elsif (my $h = $arg->{modify_records}) {
225                 $log->debug("using modify_records ", sub { dump( $h ) });
226                 $rec_regex = $self->modify_record_regexps(%{ $h });
227         }
228         $log->debug("rec_regex: ", sub { dump($rec_regex) }) if ($rec_regex);
229
230         my $class = $self->{module} || $log->logconfess("can't get low-level module name!");
231
232         $arg->{$_} = $self->{$_} foreach qw(offset limit);
233
234         my $ll_db = $class->new(
235                 path => $arg->{path},
236                 input_config => $arg->{input_config} || $self->{input_config},
237 #               filter => sub {
238 #                       my ($l,$f_nr) = @_;
239 #                       return unless defined($l);
240 #                       $l = decode($input_encoding, $l);
241 #                       $l =~ s/($recode_regex)/$recode_map->{$1}/g if ($recode_regex && $recode_map);
242 #                       return $l;
243 #               },
244                 %{ $arg },
245         );
246
247         # save for dump and input_module
248         $self->{ll_db} = $ll_db;
249
250         unless (defined($ll_db)) {
251                 $log->logwarn("can't open database $arg->{path}, skipping...");
252                 return;
253         }
254
255         my $size = $ll_db->size;
256
257         unless ($size) {
258                 $log->logwarn("no records in database $arg->{path}, skipping...");
259                 return;
260         }
261
262         my $from_rec = 1;
263         my $to_rec = $size;
264
265         if (my $s = $self->{offset}) {
266                 $log->debug("offset $s records");
267                 $from_rec = $s + 1;
268         } else {
269                 $self->{offset} = $from_rec - 1;
270         }
271
272         if ($self->{limit}) {
273                 $log->debug("limiting to ",$self->{limit}," records");
274                 $to_rec = $from_rec + $self->{limit} - 1;
275                 $to_rec = $size if ($to_rec > $size);
276         }
277
278         my $strict_encoding = $arg->{strict_encoding} || $self->{strict_encoding}; ## FIXME should be 1 really
279
280         $log->info("processing ", $self->{size} || 'all', "/$size records [$from_rec-$to_rec]",
281                 " encoding $input_encoding ", $strict_encoding ? ' [strict]' : '',
282                 $self->{stats} ? ' [stats]' : '',
283         );
284
285         $self->{size} = 0;
286
287         # read database
288         for (my $pos = $from_rec; $pos <= $to_rec; $pos++) {
289
290                 $log->debug("position: $pos\n");
291
292                 $self->{size}++; # XXX I could move this more down if I didn't want empty records...
293
294                 my $rec = $ll_db->fetch_rec($pos, sub {
295                                 my ($l,$f_nr,$debug) = @_;
296 #                               return unless defined($l);
297 #                               return $l unless ($rec_regex && $f_nr);
298
299                                 return unless ( defined($l) && defined($f_nr) );
300
301                                 my $marc_subfields = $l =~ s/\x1F(\w)/\^$1/g; # fix MARC subfiled delimiters to ^
302
303                                 warn "-=> $f_nr ## |$l|\n" if ($debug);
304                                 $log->debug("-=> $f_nr ## $l");
305
306                                 # codepage conversion and recode_regex
307                                 $l = decode($input_encoding, $l, 1);
308                                 $l =~ s/($recode_regex)/$recode_map->{$1}/g if ($recode_regex && $recode_map);
309
310                                 # apply regexps
311                                 if ($rec_regex && defined($rec_regex->{$f_nr})) {
312                                         $log->logconfess("regexps->{$f_nr} must be ARRAY") if (ref($rec_regex->{$f_nr}) ne 'ARRAY');
313                                         my $c = 0;
314                                         foreach my $r (@{ $rec_regex->{$f_nr} }) {
315                                                 my $old_l = $l;
316                                                 $log->logconfess("expected regex in ", dump( $r )) unless defined($r->{regex});
317                                                 eval '$l =~ ' . $r->{regex};
318                                                 if ($old_l ne $l) {
319                                                         my $d = "|$old_l| -> |$l| "; # . $r->{regex};
320                                                         $d .= ' +' . $r->{line} . ' ' . $r->{file} if defined($r->{line});
321                                                         $d .= ' ' . $r->{debug} if defined($r->{debug});
322                                                         $log->debug("MODIFY $d");
323                                                         warn "*** $d\n" if ($debug);
324
325                                                 }
326                                                 $log->error("error applying regex: ",dump($r), $@) if $@;
327                                         }
328                                 }
329
330                                 $l =~ s/\^(\w)/\x1F$1/g if $marc_subfields;
331
332                                 $log->debug("<=- $f_nr ## |$l|");
333                                 warn "<=- $f_nr ## $l\n" if ($debug);
334                                 return $l;
335                 });
336
337                 $log->debug(sub { dump($rec) });
338
339                 if (! $rec) {
340                         $log->warn("record $pos empty? skipping...");
341                         next;
342                 }
343
344                 # store
345                 if ($self->{save_row}) {
346                         $self->{save_row}->({
347                                 id => $pos,
348                                 row => $rec,
349                         });
350                 } else {
351                         $self->{data}->{$pos} = $rec;
352                 }
353
354                 # create lookup
355                 $arg->{'lookup_coderef'}->( $rec ) if ($rec && $arg->{'lookup_coderef'});
356
357                 # update counters for statistics
358                 if ($self->{stats}) {
359
360                         # fetch clean record with regexpes applied for statistics
361                         my $rec = $ll_db->fetch_rec($pos);
362
363                         foreach my $fld (keys %{ $rec }) {
364                                 $self->{_stats}->{fld}->{ $fld }++;
365
366                                 #$log->logdie("invalid record fild $fld, not ARRAY")
367                                 next unless (ref($rec->{ $fld }) eq 'ARRAY');
368         
369                                 foreach my $row (@{ $rec->{$fld} }) {
370
371                                         if (ref($row) eq 'HASH') {
372
373                                                 foreach my $sf (keys %{ $row }) {
374                                                         next if ($sf eq 'subfields');
375                                                         $self->{_stats}->{sf}->{ $fld }->{ $sf }->{count}++;
376                                                         $self->{_stats}->{sf}->{ $fld }->{ $sf }->{repeatable}++
377                                                                         if (ref($row->{$sf}) eq 'ARRAY');
378                                                 }
379
380                                         } else {
381                                                 $self->{_stats}->{repeatable}->{ $fld }++;
382                                         }
383                                 }
384                         }
385                 }
386
387                 $self->progress_bar($pos,$to_rec) unless ($self->{no_progress_bar});
388
389         }
390
391         $self->{pos} = -1;
392         $self->{last_pcnt} = 0;
393
394         # store max mfn and return it.
395         $self->{max_pos} = $to_rec;
396         $log->debug("max_pos: $to_rec");
397
398         return $size;
399 }
400
401 sub input_module { $_[0]->{ll_db} }
402
403 =head2 fetch
404
405 Fetch next record from database. It will also displays progress bar.
406
407  my $rec = $isis->fetch;
408
409 Record from this function should probably go to C<data_structure> for
410 normalisation.
411
412 =cut
413
414 sub fetch {
415         my $self = shift;
416
417         my $log = $self->_get_logger();
418
419         $log->logconfess("it seems that you didn't load database!") unless ($self->{pos});
420
421         if ($self->{pos} == -1) {
422                 $self->{pos} = $self->{offset} + 1;
423         } else {
424                 $self->{pos}++;
425         }
426
427         my $mfn = $self->{pos};
428
429         if ($mfn > $self->{max_pos}) {
430                 $self->{pos} = $self->{max_pos};
431                 $log->debug("at EOF");
432                 return;
433         }
434
435         $self->progress_bar($mfn,$self->{max_pos}) unless ($self->{no_progress_bar});
436
437         my $rec;
438
439         if ($self->{load_row}) {
440                 $rec = $self->{load_row}->({ id => $mfn });
441         } else {
442                 $rec = $self->{data}->{$mfn};
443         }
444
445         $rec ||= 0E0;
446 }
447
448 =head2 pos
449
450 Returns current record number (MFN).
451
452  print $isis->pos;
453
454 First record in database has position 1.
455
456 =cut
457
458 sub pos {
459         my $self = shift;
460         return $self->{pos};
461 }
462
463
464 =head2 size
465
466 Returns number of records in database
467
468  print $isis->size;
469
470 Result from this function can be used to loop through all records
471
472  foreach my $mfn ( 1 ... $isis->size ) { ... }
473
474 because it takes into account C<offset> and C<limit>.
475
476 =cut
477
478 sub size {
479         my $self = shift;
480         return $self->{size}; # FIXME this is buggy if open is called multiple times!
481 }
482
483 =head2 seek
484
485 Seek to specified MFN in file.
486
487  $isis->seek(42);
488
489 First record in database has position 1.
490
491 =cut
492
493 sub seek {
494         my $self = shift;
495         my $pos = shift;
496
497         my $log = $self->_get_logger();
498
499         $log->logconfess("called without pos") unless defined($pos);
500
501         if ($pos < 1) {
502                 $log->warn("seek before first record");
503                 $pos = 1;
504         } elsif ($pos > $self->{max_pos}) {
505                 $log->warn("seek beyond last record");
506                 $pos = $self->{max_pos};
507         }
508
509         return $self->{pos} = (($pos - 1) || -1);
510 }
511
512 =head2 stats
513
514 Dump statistics about field and subfield usage
515
516   print $input->stats;
517
518 =cut
519
520 sub stats {
521         my $self = shift;
522
523         my $log = $self->_get_logger();
524
525         my $s = $self->{_stats};
526         if (! $s) {
527                 $log->warn("called stats, but there is no statistics collected");
528                 return;
529         }
530
531         my $max_fld = 0;
532
533         my $out = join("\n",
534                 map {
535                         my $f = $_;
536                         die "no field in ", dump( $s->{fld} ) unless defined( $f );
537                         my $v = $s->{fld}->{$f} || die "no s->{fld}->{$f}";
538                         $max_fld = $v if ($v > $max_fld);
539
540                         my $o = sprintf("%4s %d ~", $f, $v);
541
542                         if (defined($s->{sf}->{$f})) {
543                                 my @subfields = keys %{ $s->{sf}->{$f} };
544                                 map {
545                                         $o .= sprintf(" %s:%d%s", $_, 
546                                                 $s->{sf}->{$f}->{$_}->{count},
547                                                 $s->{sf}->{$f}->{$_}->{repeatable} ? '*' : '',
548                                         );
549                                 } (
550                                         # first indicators and other special subfields
551                                         sort( grep { length($_)  > 1 } @subfields ),
552                                         # then subfileds (single char)
553                                         sort( grep { length($_) == 1 } @subfields ),
554                                 );
555                         }
556
557                         if (my $v_r = $s->{repeatable}->{$f}) {
558                                 $o .= " ($v_r)" if ($v_r != $v);
559                         }
560
561                         $o;
562                 } sort { 
563                         if ( $a =~ m/^\d+$/ && $b =~ m/^\d+$/ ) {
564                                 $a <=> $b
565                         } else {
566                                 $a cmp $b
567                         }
568                 } keys %{ $s->{fld} }
569         );
570
571         $log->debug( sub { dump($s) } );
572
573         my $path = 'var/stats.yml';
574         YAML::DumpFile( $path, $s );
575         $log->info( 'created ', $path, ' with ', -s $path, ' bytes' );
576
577         return $out;
578 }
579
580 =head2 dump_ascii
581
582 Display humanly readable dump of record
583
584 =cut
585
586 sub dump_ascii {
587         my $self = shift;
588
589         return unless $self->{ll_db};
590
591         if ($self->{ll_db}->can('dump_ascii')) {
592                 return $self->{ll_db}->dump_ascii( $self->{pos} );
593         } else {
594                 return dump( $self->{ll_db}->fetch_rec( $self->{pos} ) );
595         }
596 }
597
598 =head2 _get_regex
599
600 Helper function called which create regexps to be execute on code.
601
602   _get_regex( 900, 'regex:[0-9]+' ,'numbers' );
603   _get_regex( 900, '^b', ' : ^b' );
604
605 It supports perl regexps with C<regex:> prefix to from value and has
606 additional logic to skip empty subfields.
607
608 =cut
609
610 sub _get_regex {
611         my ($sf,$from,$to) = @_;
612
613         # protect /
614         $from =~ s!/!\\/!gs;
615         $to =~ s!/!\\/!gs;
616
617         if ($from =~ m/^regex:(.+)$/) {
618                 $from = $1;
619         } else {
620                 $from = '\Q' . $from . '\E';
621         }
622         if ($sf =~ /^\^/) {
623                 my $need_subfield_data = '*';   # no
624                 # if from is also subfield, require some data in between
625                 # to correctly skip empty subfields
626                 $need_subfield_data = '+' if ($from =~ m/^\\Q\^/);
627                 return
628                         's/\Q'. $sf .'\E([^\^]' . $need_subfield_data . '?)'. $from .'([^\^]*?)/'. $sf .'$1'. $to .'$2/';
629         } else {
630                 return
631                         's/'. $from .'/'. $to .'/g';
632         }
633 }
634
635
636 =head2 modify_record_regexps
637
638 Generate hash with regexpes to be applied using L<filter>.
639
640   my $regexpes = $input->modify_record_regexps(
641                 900 => { '^a' => { ' : ' => '^b' } },
642                 901 => { '*' => { '^b' => ' ; ' } },
643   );
644
645 =cut
646
647 sub modify_record_regexps {
648         my $self = shift;
649         my $modify_record = {@_};
650
651         my $regexpes;
652
653         my $log = $self->_get_logger();
654
655         foreach my $f (keys %$modify_record) {
656                 $log->debug("field: $f");
657
658                 foreach my $sf (keys %{ $modify_record->{$f} }) {
659                         $log->debug("subfield: $sf");
660
661                         foreach my $from (keys %{ $modify_record->{$f}->{$sf} }) {
662                                 my $to = $modify_record->{$f}->{$sf}->{$from};
663                                 #die "no field?" unless defined($to);
664                                 my $d = "|$from| -> |$to|";
665                                 $log->debug("transform: $d");
666
667                                 my $regex = _get_regex($sf,$from,$to);
668                                 push @{ $regexpes->{$f} }, { regex => $regex, debug => $d };
669                                 $log->debug("regex: $regex");
670                         }
671                 }
672         }
673
674         return $regexpes;
675 }
676
677 =head2 modify_file_regexps
678
679 Generate hash with regexpes to be applied using L<filter> from
680 pseudo hash/yaml format for regex mappings.
681
682 It should be obvious:
683
684         200
685           '^a'
686             ' : ' => '^e'
687             ' = ' => '^d'
688
689 In field I<200> find C<'^a'> and then C<' : '>, and replace it with C<'^e'>.
690 In field I<200> find C<'^a'> and then C<' = '>, and replace it with C<'^d'>.
691
692   my $regexpes = $input->modify_file_regexps( 'conf/modify/common.pl' );
693
694 On undef path it will just return.
695
696 =cut
697
698 sub modify_file_regexps {
699         my $self = shift;
700
701         my $modify_path = shift || return;
702
703         my $log = $self->_get_logger();
704
705         my $regexpes;
706
707         CORE::open(my $fh, $modify_path) || $log->logdie("can't open modify file $modify_path: $!");
708
709         my ($f,$sf);
710
711         while(<$fh>) {
712                 chomp;
713                 next if (/^#/ || /^\s*$/);
714
715                 if (/^\s*(\d+)\s*$/) {
716                         $f = $1;
717                         $log->debug("field: $f");
718                         next;
719                 } elsif (/^\s*'([^']*)'\s*$/) {
720                         $sf = $1;
721                         $log->die("can't define subfiled before field in: $_") unless ($f);
722                         $log->debug("subfield: $sf");
723                 } elsif (/^\s*'([^']*)'\s*=>\s*'([^']*)'\s*$/) {
724                         my ($from,$to) = ($1, $2);
725
726                         $log->debug("transform: |$from| -> |$to|");
727
728                         my $regex = _get_regex($sf,$from,$to);
729                         push @{ $regexpes->{$f} }, {
730                                 regex => $regex,
731                                 file => $modify_path,
732                                 line => $.,
733                         };
734                         $log->debug("regex: $regex");
735                 } else {
736                         die "can't parse: $_";
737                 }
738         }
739
740         return $regexpes;
741 }
742
743 =head1 AUTHOR
744
745 Dobrica Pavlinusic, C<< <dpavlin@rot13.org> >>
746
747 =head1 COPYRIGHT & LICENSE
748
749 Copyright 2005-2006 Dobrica Pavlinusic, All Rights Reserved.
750
751 This program is free software; you can redistribute it and/or modify it
752 under the same terms as Perl itself.
753
754 =cut
755
756 1; # End of WebPAC::Input