NAME

    MODS::Record - Perl extension for handling MODS records

SYNOPSIS

     use MODS::Record qw(xml_string);
     use open qw(:utf8);
    
     my $mods = MODS::Record->new;
    
     my $collection = MODS::Collection->new;
    
     my $mods = $collection->add_mods(ID => '1234');
    
     $mods->add_abstract("Hello", lang => 'eng');
     $mods->add_abstract("Bonjour", lang => 'fra');
    
     # Set a deeply nested field...
     $mods->add_language()->add_languageTerm('eng');
    
     # Set a list of deeply nested fields...
     $mods->add_location(sub {
        $_[0]->add_physicalLocation('here');
        $_[0]->add_shelfLocator('here too');
        $_[0]->add_url('http://here.org/there');
     });
    
     # Set an inline XML extension...
     $mods->add_accessCondition(xml_string("<x:foo><x:bar>21212</x:bar></x:foo>"));
    
     # Retrieve a field by a filter...
     $mods->get_abstract(lang => 'fra')->body("Bonjour :)");
     $mods->get_abstract(lang => 'fra')->contentType('text/plain');
    
     for ($mods->get_abstract(lang => 'fra')) {
        printf "%s\n" , $_->body;
     }
    
     # Set a field to a new value
     my @newabstract;
     for ($mods->get_abstract) {
        push @newabstract, $_ unless $_->lang eq 'fra';
     }
     $mods->set_abstract(@newabstract);
    
     # Clear all abstracts;
     $mods->set_abstract(undef);
    
     # Serialize
     print $mods->as_json(pretty => 1);
     print $mods->as_xml;
    
     # Deserialize
     my $mods = MODS::Record->from_xml(IO::File->new('mods.xml'));
     my $mods = MODS::Record->from_json(IO::File->new('mods.js'));
    
     my $count = MODS::Record->from_xml(IO::File->new('mods.xml'), sub {
        my $mods = shift;
        ...
     });
    
     my $count = MODS::Record->from_json(IO::File->new('mods.js'), sub {
        my $mods = shift;
        ...
     });

DESCRIPTION

    This module provides MODS (http://www.loc.gov/standards/mods/) parsing
    and creation for MODS Schema 3.5.

METHODS

 MODS::Record->new(%attribs)

 MODS::Collection->new(%attribs)

    Create a new MODS record or collection. Optionally attributes can be
    provided as defined by the MODS specification. E.g.

     $mods = MODS::Record->new(ID='123');

 add_xxx()

    Add a new element to the record where 'xxx' is the name of a MODS
    element (e.g. titleInfo, name, genre, etc). This method returns an
    instance of the added MODS element. E.g.

     $titleInfo = $mods->add_titleInfo; # $titleInfo is a 'MODS::Element::TitleInfo'

 add_xxx($text,%attribs)

    Add a new element to the record where 'xxx' is the name of a MODS
    element. Set the text content of the element to $text and optionally
    provide further attributes. This method returns an instance of the
    added MODS element. E.g.

     $mods->add_abstract("My abstract", lang=>'eng');

 add_xxx(sub { })

    Add a new element to the record where 'xxx' is the name of a MODS
    element. The provided coderef gets as input an instance of the added
    MODS element. This method returns an instance of the added MODS
    element. E.g.

     $mods->add_abstract(sub {
        my $o = shift;
        $o->body("My abstract");
        $o->lang("eng");
     })

 add_xxx($obj)

    Add a new element to the record where 'xxx' is the name of a MODS
    element. The $obj is an instance of a MODS::Element::Xxx class (where
    Xxx is the corresponding MODS element). This method returns an instance
    of the added MODS element. E.g.

     $mods->add_abstract(
         MODS::Element::Abstract->new(_body=>'My abstract', lang=>'eng')
     );

 get_xxx()

 get_xxx(%filter)

 get_xxx(sub { })

    Retrieve an element from the record where 'xxx' is the name of a MODS
    element. This methods return in array context all the matching elements
    or the first match in scalar context. Optionally provide a %filter or a
    coderef filter function. E.g.

     @titles = $mods->get_titleInfo();
     $alt    = $mods->get_titleInfo(type=>'alternate');
     $alt    = $mods->get_titleInfo(sub { shift->type eq 'alternate'});

 set_xxxx()

 set_xxx(undef)

 set_xxx($array_ref)

 set_xxx($xxx1,$xxx2,...)

    Set an element of the record to a new value where 'xxx' is the name of
    a MODS element. When no arguments are provided, then this is a null
    operation. When undef als argument is provided, then the element is
    deleted. To overwrite the existing content of the element an ARRAY
    (ref) of MODS::Element::Xxx can be provided (where 'Xxx' is the
    corresponding MODS element). E.g.

     # Delete all abstracts
     $mods->set_abstract(undef);
    
     # Set all abstracts
     $mods->set_abstract(MODS::Element::Abstract->new(), MODS::Element::Abstract->new(), ...);
     $mods->set_abstract([ MODS::Element::Abstract->new(), MODS::Element::Abstract->new(), ... ]);

 as_xml()

 as_xml(xml_prolog=>1)

    Return the record as XML.

 from_xml($string [, $callback])

 from_xml(IO::Handle [, $callback])

    Parse an XML string or IO::Handle into a MODS::Record. This method
    return the parsed JSON.

    If a callback function is provided then for each MODS element in the
    XML stream the callback will be called. The method returns the number
    of parsed MODS elements.

     E.g.
        my $mods = MODS::Record->from_xml( IO::File->new(...) );
    
        my $count = MODS::Record->from_xml( IO::File->new(...) , sub {
            my $mods = shift;
        } );

 as_json()

 as_json(pretty=>1)

    Return the record as JSON string.

 from_json($string [, $callback])

 from_json(IO::Handle [, $callback])

    Parse and JSON string or JSON::Handle into a MODS::Record. This method
    return the parsed JSON.

    If a callback function is provided then we expect as input a stream of
    JSON strings (each line one JSON string). For each MODS object in the
    JSON stream the callback will be called. The method returns the number
    of parsed strings.

     E.g.
        my $mods = MODS::Record->from_json( IO::File->new(...) );
    
        my $count = MODS::Record->from_json( IO::File->new(...) , sub {
            my $mods = shift;
        } );

SEE ALSO

      * Library Of Congress MODS pages (http://www.loc.gov/standards/mods/)

DESIGN NOTES

      * I'm not a MODS expert

      * I needed a MODS module to parse and create MODS records for our
      institutional repository

      * This module is part of the LibreCat/Catmandu project
      http://librecat.org

      * This module is not created for speed

      * This module doesn't have any notion of ordering of MODS elements
      themselves (e.g. first 'titleInfo', then 'name'). But each
      sub-element keeps its original order (e.g. each 'title' in
      'titleInfo').

      * Heiko Jansen provides at GitHub a Moose-based MODS parser
      https://github.com/heikojansen/MODS--Record

AUTHOR

    Patrick Hochstenbach <Patrick.Hochstenbach at UGent.be>

LICENSE AND COPYRIGHT

    This program is free software; you can redistribute it and/or modify it
    under the terms of either: the GNU General Public License as published
    by the Free Software Foundation; or the Artistic License.

    See http://dev.perl.org/licenses/ for more information.