#!/usr/bin/perl

package Main;
$Main::VERSION = '1.0.5';
# PODNAME: koha-ark
# ABSTRACT: Manage ARK identifiers in a Koha Catalog

use Modern::Perl;
use Pod::Usage;
use Getopt::Long;
use Koha::Contrib::ARK;

binmode(STDOUT, ':encoding(UTF8)');

my ($help, $verbose, $doit, $debug) = (0, 1, 0, 0);
GetOptions( 
    'verbose!' => \$verbose,
    'doit'     => \$doit,
    'help|h'   => \$help,
    'debug'    => \$debug,
);

sub usage {
    pod2usage( -verbose => 2 );
    exit;
} 


usage() if $help || @ARGV != 1;

my $cmd = shift @ARGV;
usage() if $cmd !~ /clear|update|check/;

my $ark = Koha::Contrib::ARK->new(
    cmd          => $cmd,
    debug        => $debug,
    verbose      => $verbose,
    doit         => $doit,
);
$ark->run();

__END__

=pod

=encoding UTF-8

=head1 NAME

koha-ark - Manage ARK identifiers in a Koha Catalog

=head1 VERSION

version 1.0.5

=head1 DESCRIPTION

Process biblio records from a Koha Catalog in order to update its ARK
identifiers. See L<The ARK Identifier
Scheme|https://tools.ietf.org/id/draft-kunze-ark-15.txt>. The processing is
driven by ARK_CONF Koha system preference. It's a json variable. For example:

 {
   "ark": {
     "NMHA": "myspecial.institution.fr",
     "NAAN": "12345",
     "ARK": "http://{NMHA}/ark:/{NAAN}/catalog{id}",
     "koha": {
       "id": { "tag": "099", "letter": "a" },
       "ark": { "tag": "003" }
     }
   }
 }

ARK_CONF system preference must contains several elements:

=over

=item *

B<NMHA> — Name Mapping Authority Hostport. Usually it's a hostname, the
hostname of the Koha system itself, or the hostname of a proxy server (or link
resolver).

=item *

B<NAAN> — Name Assigning Authority Number. It's a number identifying the
institution, ie the Library using Koha. This number is provided for example by
the California Digital Library (CDL),

=item *

B<ARK> — It's a template used to build the ARK. Three placeholders can be used
in the template: C<NMHA> and C<NAAN> from ARK_CONF, and C<id> (Koha
biblio record unique identifier extracted from koha.id field).

=item *

B<koha.id> — The biblio record field which contains Koha unique id
(biblionumber or another id). Contains 2 variables: C<tag> and C<letter>, si it
could be a control or a standard field. For example, C<{"tag": "001"}> or
C<{"tag": "099", "letter": "a"}>.

=item *

B<koha.ark> — The biblio record field used to store the ARK. It could be a
control or standard field. That's this field in which this script will store
the generated field. This is also the field that this script can clear
entirely.

=back

There are three commands: check, clear, and update

=head2 check

Process all biblio records, and check them for: bad ARK, correct ARK in the
wrong field.

=head2 clear

C<koha-ark clear> clears the ARK field (C<koha.ark> variable) in all biblio
records of the Catalog.

=head2 update

C<koha-ark update> processes all biblio that have an empty ARK field. The ARK
field is created with the appropriate ARK identifier. The ARK is build based on
C<ARK> variable from ARK_CONF. For the above ARK_CONF, the biblio record that has
C<9877> biblionumber will have this in 003 field:

 http://myspecial.institution.fr/ark:/12345/biblio9877

=head1 USAGE

=over

=item koha-ark check|clear|update [--doit] [--verbose] [--debug] [--help]

=back

=head1 SYNOPSYS

 koha-ark clear --doit
 koha-ark update --noverbose --doit
 koha-ark update --debug
 koha-ark check

=head1 PARAMETERS

=over

=item B<--doit>

Without this parameter biblio records are not modified in Koha Catalog.

=item B<--verbose>

Enable script verbose mode. Verbose by default. --noverbose disable verbosity.
In verbose mode, a progress bar is displayed.

=item B<--debug>

Info about processing is sent to a file named 'koha-ark.json' in the current
directory. In 'debug' mode, more information is produced.

=item B<--help|-h>

Print this help page.

=back

=head1 RESULT

The result of this script is a JSON file C<koha-ark.log> which reports what has
been done.

For exemple, if ARK_CONF is missing, the file will report the issue:

 {
   "action" : "check"
   "timestamp" : "\"2018-05-11 16:02:15\"",
   "error" : {
      "err_pref_missing" : {
         "msg" : "ARK_CONF preference is missing",
         "id" : "err_pref_missing"
      }
   },
 }

C<koha-ark clear> contains something like this:

 {
   "timestamp" : "2018-05-11 17:18:42",
   "action" : "clear",
   "result" : {
      "count" : "1569",
      "records" : [
         {
            "biblionumber" : "1",
            "what" : {
               "clear" : {
                  "id" : "clear",
                  "msg" : "Clear ARK field"
               }
            }
         },
         ...
   }
 }

C<koha-ark update --debug> contains something like this:

 {
   "timestamp" : "2018-05-11 17:21:02",
   "action" : "update",
   "testmode": 1,
   "result" : {
      "count" : "145282",
      "records" : [
         {         
            "biblionumber" : "1570",
            "what" : {
               "generated" : {
                  "id" : "generated"
                  "msg" : "ARK generated",
                  "more" : "http://myspecial.institution.fr/ark:/12345/catalog1573",
               },
               "add" : {
                  "id" : "add",
                  "msg" : "Add ARK field"
               }
            },
            "record": [ ... ],
            "after": [ ... ]
         },
         ...
      ]
   }
 }

=head1 AUTHOR

Frédéric Demians <f.demians@tamil.fr>

=head1 COPYRIGHT AND LICENSE

This software is Copyright (c) 2020 by Fréderic Demians.

This is free software, licensed under:

  The GNU General Public License, Version 3, June 2007

=cut
