git.rot13.org Git - webpac2/blob - lib/WebPAC/Input.pm

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