#!/usr/bin/perl

package Main;
$Main::VERSION = '1.0.2';
# 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, $log) = (0, 1, 0, 'info');
GetOptions( 
    'verbose!' => \$verbose,
    'doit'     => \$doit,
    'help|h'   => \$help,
    'log=s'    => \$log,
);

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,
    log_filename => 'koha-ark.log',
    loglevel     => $log,
    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.2

=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 two commands: clear and update

=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 SYNOPSYS

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

=head1 USAGE

=over

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

=back

=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<--log>

The log level. Info about processing is sent to a file named 'koha-ark.log' in
the current directory. This parameter controls the log level of the info sent
to this file. Values: debug, info, error. By default, 'info'. With 'error',
nothing is logged except fatal errors, like ARK_CONF bad syntax. With 'debug',
a lot of information is produced, like biblio records before/after processing.

=item B<--help|-h>

Print this help page.

=back

=head1 AUTHOR

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

=head1 COPYRIGHT AND LICENSE

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

This is free software, licensed under:

  The GNU General Public License, Version 3, June 2007

=cut
