source: gsdl/trunk/perllib/plugins/NulPlugin.pm@ 15865

###########################################################################
#
# NULPlug.pm -- Plugin for dummy (.nul) files
#
# A component of the Greenstone digital library software from the New
# Zealand Digital Library Project at the University of Waikato, New
# Zealand.
#
# Copyright (C) 2005 Katherine Don
# Copyright (C) 2005 New Zealand Digital Library Project
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
#
###########################################################################

# NULPlug - a plugin for dummy files

# This is a simple Plugin for importing dummy files, along with
# their metadata.  A fictional document will
# be created for every such file, and the metadata added to it.

# This is used mainly for the null files resulting from exploding metadata
# databases

package NULPlug;

use BasPlug;

use strict;
no strict 'refs'; # allow filehandles to be variables and viceversa

sub BEGIN {
    @NULPlug::ISA = ('BasPlug');
}

my $arguments = 
    [ { 'name' => "process_exp",
    'desc' => "{BasPlug.process_exp}",
    'type' => "regexp",
    'reqd' => "no",
    'deft' => &get_default_process_exp() },
      { 'name' => "assoc_field",
    'desc' => "{NULPlug.assoc_field}",
    'type' => "string",
    'deft' => "",
    'reqd' => "no" },
      { 'name' => "add_metadata_as_text",
    'desc' => "{NULPlug.add_metadata_as_text}",
    'type' => "flag" },
      { 'name' => "remove_namespace_for_text",
    'desc' => "{NULPlug.remove_namespace_for_text}",
    'type' => "flag" }
      ];

my $options = { 'name'     => "NULPlug",
        'desc'     => "{NULPlug.desc}",
        'abstract' => "no",
        'inherits' => "yes",
                 'args'     => $arguments };


sub new {
    my ($class) = shift (@_);
    my ($pluginlist,$inputargs,$hashArgOptLists) = @_;
    push(@$pluginlist, $class);

    if(defined $arguments){ push(@{$hashArgOptLists->{"ArgList"}},@{$arguments});}
    if(defined $options) { push(@{$hashArgOptLists->{"OptList"}},$options)};

    my $self = new BasPlug($pluginlist, $inputargs, $hashArgOptLists);
    
    return bless $self, $class;
}

sub get_default_process_exp {
    return '(?i)\.nul$';
}

# The NULPlug read() function. This function does all the right
# things to make general options work for a given plugin.  NULPlug
# overrides read() because there is no need to read the actual text of
# the file in, because the contents of the file is not text...
#
#
# Return number of files processed, undef if can't process 
#
# Note that $base_dir might be "" and that $file might include directories

sub read {
    my $self = shift (@_);
    my ($pluginfo, $base_dir, $file, $metadata, $processor, $maxdocs, $total_count, $gli) = @_;

    my $outhandle = $self->{'outhandle'};

    #check for associate_ext, blocking etc
    my ($block_status,$filename) = $self->read_block(@_);    
    return $block_status if ((!defined $block_status) || ($block_status==0));

    print STDERR "<Processing n='$file' p='NULPlug'>\n" if ($gli);
    print $outhandle "NULPlug processing \"$filename\"\n"
        if $self->{'verbosity'} > 1;

    #if there's a leading directory name, eat it...
    $file =~ s/^.*[\/\\]//;
    
    # create a new document
    my $doc_obj = new doc ($filename, "indexed_doc");
    my $top_section = $doc_obj->get_top_section();

    $doc_obj->set_OIDtype ($processor->{'OIDtype'}, $processor->{'OIDmetadata'});    
    #$doc_obj->set_OIDtype ("incremental");
    $doc_obj->add_utf8_metadata($top_section, "Plugin", "$self->{'plugin_type'}");
    $doc_obj->add_metadata($top_section, "Source", $file); # set the filename as Source metadata to be consistent with other plugins

    $doc_obj->add_utf8_metadata($top_section, "FileSize", (-s $filename));

    # the metadata NoText is used to suppress the dummy text 'This document has no text.'
    $doc_obj->add_metadata ($top_section, "NoText",    "1");

    my $assoc_field = $self->{'assoc_field'} || "null_file";
    $doc_obj->add_metadata ($top_section, $assoc_field, $file);
    
     if ($self->{'cover_image'}) {
    $self->associate_cover_image($doc_obj, $filename);
    }

    # include any metadata passed in from previous plugins 
    my $section = $doc_obj->get_top_section();
    $self->extra_metadata ($doc_obj, $section, $metadata);
    
    # format the metadata passed in (presumably from metadata.xml)
    my $text = "";
    if ($self->{'add_metadata_as_text'}) {
    $text = &metadatautil::format_metadata_as_table($metadata, $self->{'remove_namespace_for_text'});
    } else {
    #create an empty text string so we don't break downstream plugins 
    $text = &gsprintf::lookup_string("{BasPlug.dummy_text}",1);
    }
    $self->title_fallback($doc_obj,$section,$file);
    
    # do plugin specific processing of doc_obj
    unless (defined ($self->process(\$text, $pluginfo, $base_dir, $file, $metadata, $doc_obj))) {
    print STDERR "<ProcessingError n='$file'>\n" if ($gli);
    return -1;
    }

    # do any automatic metadata extraction
    $self->auto_extract_metadata ($doc_obj);

    # add an OID
    $doc_obj->set_OID();
    $doc_obj->add_utf8_text($section, $text);
    
    # process the document
    $processor->process($doc_obj);

    $self->{'num_processed'} ++;
    return 1;
}


# NULPlug processing of doc_obj.  In practice we don't need to do
# anything here because the read function takes care of everything.

sub process {
    my $self = shift (@_);
    my ($textref, $pluginfo, $base_dir, $file, $metadata, $doc_obj) = @_;
    my $outhandle = $self->{'outhandle'};
    
    return 1;
}


1;