Stéphane Delaune > MARC-Transform-0.003004 > MARC::Transform

Download:
MARC-Transform-0.003004.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.003004   Source  

NAME ^

MARC::Transform - Perl module to transform a MARC record using a YAML configuration file

VERSION ^

Version 0.003004

SYNOPSIS ^

Perl script:

    use MARC::Transform;

    # For this synopsis, we create a small record:
    my $record = MARC::Record->new();
    $record->insert_fields_ordered( MARC::Field->new( 
                                    '501', '', '', 
                                    'a' => 'foo', 
                                    'b' => '1', 
                                    'c' => 'bar', 
                                    'd' => 'bor' ) );

    print "--init record--\n". $record->as_formatted ."\n";

    # We transform our record with our YAML configuration file
    # with its absolute path (or relative if called 
    # from the right path ) :
    $record = MARC::Transform->new ( $record, "/path/conf.yaml" );

    # You can also define your YAML into a variable:
    my $yaml="delete : f501d\n";
    # and use it to transform the record:
    $record = MARC::Transform->new ( $record, $yaml );

    print "\n--transformed record--\n". $record->as_formatted ."\n";

conf.yaml:

    ---
    condition : $f501a eq "foo"
    create :
     f502a : New 502a subfield's value
    update :
      $f501b : \&LUT("$this")
    LUT :
     1 : first
     2 : second value in this LUT (LookUp Table)
    ---
    delete : f501c

Result (with $record->as_formatted):

    --init record--
    LDR                         
    501    _afoo
           _b1
           _cbar
           _dbor
    
    --transformed record--
    LDR                         
    501    _afoo
           _bfirst
    502    _aNew 502a subfield's value

DESCRIPTION ^

This is a Perl module to transform a MARC record using a YAML configuration file.

It allows you to create , update , delete , duplicate fields and subfields of a record. You can also use scripts and lookup tables. You can specify conditions to execute these actions.

All conditions, actions, functions and lookup tables are defined in the YAML.

MARC::Transform use MARC::Record.

METHOD ^

new()

    $record = MARC::Transform->new($record, "/path/conf.yaml" );

This is the only method you'll use. It takes a MARC::Record object and a YAML path as arguments. You can also define your YAML into a variable and use it to transform the record like this :

    my $yaml="delete : f501d\n";
    $record = MARC::Transform->new ( $record, $yaml );

Optional hash reference

As we will see in more detail below, it is possible to add a hash reference (named $mth into yaml) as the third optional argument.

    my $record = MARC::Record->new(); my $hashref = {'var' => 'foo'};
    my $yaml = 'create :
     f500a : $$mth{"var"}
    ';
    $record = MARC::Transform->new($record,$yaml,$hashref);
    #the new 500$a subfield's value is "foo"

Verbose mode

Each YAML rule (see basis below to understand what is a rule) generates a script that is evaluated, in the record, for each field and subfield specified in the condition (If there is a condition). By adding a fourth optional argument 1 to the method, it displays the generated script. This can be useful to understand what is happening:

    $record = MARC::Transform->new($record,"/path/conf.yaml",0,1);

YAML ^

Basis

- YAML is divided in rules (separated by --- ), each rule is executed one after the other, rules whithout condition will allways be executed:

    ---
    condition : $f501a eq "foo"
    create :
     f600a : new field value
    ---
    delete : f501c
    ---

- conditions are written in perl, which allows great flexibility. They must be defined with condition :

    condition : ($f501a=~/foo/ and $f503a=~/bar/) or ($f102a eq "bib")
    # if a 501$a and 503$a contain foo and bar, or if a 102$a = bib

- Conditions test records field by field (only for fields defined in the condition)

For example, this means, that if we have more '501' fields in the record, if our condition is $f501a eq "foo" and $f501b eq "bar", that condition will be true only if a '501' field has a 'a' subfield = "foo" AND a 'b' subfield = 'bar' (it will be false if there is a '501' field with a 'a' subfield = "foo" and ANOTHER '501' field with a 'b' subfield = "bar").

- It's possible to run more than one different actions in a single rule:

    ---
    condition : $f501a eq "foo"
    create :
     f600a : new field value
    delete : f501c
    ---

- The order in which actions are written does not matter. Actions will always be executed in the following order:

- Each rule can be divided into sub-rules (separated by - ) similar to 'if,elsif' or 'switch,case' scripts. If the first sub-rule's condition is false, the following sub-rule's condition is tested. When the sub-rule's condition is true (or if a sub-rule has no condition), the following sub-rules are not read.

    ---
    -
     condition : $f501a eq "foo"
     create :
      f502a : value if foo
    -
     condition : $f501a eq "bar"
     create :
      f502a : value elsif bar
    -
     create :
      f502a : value else
    ---
    # It is obvious that if a sub-rule has no condition, it will be
    # considered as an 'else' (following sub-rules will not be read)

- It is not allowed to define more than one similar action into a single (sub-)rule. However, it remains possible to execute a similar action several times in a single rule (refer to the specific syntax of each action in order to see how to do this):

. this is not allowed:

    ---
    delete : f501b
    delete : f501c

. it works:

    ---
    delete :
     - f501b
     - f501c

a small script to test your rules

- it is strongly recommended to test each rule on a test record before using it on a large batch of records. You can create a script (e.g. test.pl) with the contents below (that you will adapt to test your rules) and run it with perl ./test.pl :

    #!/usr/bin/perl
    use MARC::Transform;
    my $record = MARC::Record->new();
    $record->leader('optionnal leader');
    $record->insert_fields_ordered( MARC::Field->new('005', 'controlfield_content'));
    $record->insert_fields_ordered( MARC::Field->new('501', '', '', 'a' => 'foo', 'b' => 'bar') );
    print "\n--init record--\n". $record->as_formatted ."\n";
    my $yaml='---
    condition : $f501a eq "foo"
    create :
     f502a : condition is true
    ';
    $record = MARC::Transform->new($record,$yaml);
    print "\n--transformed record--\n". $record->as_formatted ."\n";

Field's and subfield's naming convention

In actions

- Field's and subfield's names are very important:

In conditions

Run actions only on the condition's fields

We have already seen that to refers to the condition's field in actions, it is possible to define subfields directly. It works only if we define only one field to be tested in the condition. If we ve'got more than one field in condition, their names must also begin with $ to refer them (it works also with a unique field in condition).

For example, if you test $f501a value's in condition:

- this will delete 'c' subfields only in the '501' field which is true in the condition:

    condition : $f501a eq "foo" and defined $f501b
    delete : $f501c

- this will delete 'c' subfields in all '501' fields:

    condition : $f501a eq "foo" and defined $f501b
    delete : f501c

- this will create a new '701' field with a 'c' subfield containing '501$a' subfield's value defined in the condition:

    condition : defined $f501a
    create :
     f701c : $f501a

WARNING: To get subfield's value of the condition's fields, these subfields must be defined in the condition:

- it doesn't work:

    condition : $f501a eq "foo"
    create :
     f701a : $f501c

- it works (create a new '701' field with a subfield 'a' containing the condition's '501$c' subfield's value ):

    condition : $f501a eq "foo" and defined $f501c
    create :
     f701a : $f501c

- this restriction is true only for the subfield's values, but isn't true to specify the fields affected by an action: the example below will create a new 'c' subfield in a field defined in the condition.

    condition : $f501a eq "foo" and $f110a == 2
    create :
     $f501c : new subfield value
    # If there are multiple '501' fields, only the one with a 
    # subfield 'a'='foo' will have a new 'c' subfield created

Actions

create

update

updatefirst

forceupdate and forceupdatefirst

delete

duplicatefield

execute

Use Perl functions and LookUp Tables

You can use Perl functions (subs) and lookup tables (LUT) to define with greater flexibility values that will be created or updated by the actions: create, forceupdate, forceupdatefirst, update and updatefirst.

These functions (and lookup tables) can be written in a rule (in this case they can be used only by this rule) or after the last rule ( after the last ---, can be used in all rules: global_subs and global_LUT ).

Variables

Four types of variables can be used:

$this, and condition's elements

$mth

$mth is the optional hashref add as third optional argument. It can be used in writing (into subs and global_subs) and reading. This allows to interact with the script that calls MARC::Transform.

$record

$record is the current MARC::Record object.

subs

Internal rules

global_subs

LUT

If a value has no match in a LookUp Table, it isn't modified. (unless you have defined a default value with _default_value_ ).

If you want to use more than one LookUp Table in a rule, you must use a global_LUT because it differentiates tables with titles.

Internal rules

global_LUT

$$mth{"_defaultLUT_to_mth_"}

Latest tips and a big YAML example's ^

SEE ALSO ^

AUTHOR ^

Stephane Delaune, (delaune.stephane at gmail.com)

COPYRIGHT ^

Copyright 2011-2013 Stephane Delaune for Biblibre.com, all rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

===========> DOCUMENTATION FRANCAISE ^

- NOM ^

MARC::Transform - Module Perl pour transformer une notice MARC en utilisant un fichier de configuration YAML

- VERSION ^

Version 0.003004

- SYNOPSIS ^

Perl script:

    use MARC::Transform;

    # Pour ce synopsis, nous créons une petite notice:
    my $record = MARC::Record->new();
    $record->insert_fields_ordered( MARC::Field->new( 
                                    '501', '', '', 
                                    'a' => 'foo', 
                                    'b' => '1', 
                                    'c' => 'bar', 
                                    'd' => 'bor' ) );

    print "--notice d'origine--\n". $record->as_formatted ."\n";

    # Nous transformons notre notice avec notre fichier de 
    # configuration YAML avec son chemin absolu ( ou
    # relatif si il est appelé depuis le bon endroit) :
    $record = MARC::Transform->new ( $record, "/path/conf.yaml" );

    # Vous pouvez aussi écrire votre YAML dans une variable:
    my $yaml="delete : f501d\n";
    # et l'utiliser pour transformer la notice:
    $record = MARC::Transform->new ( $record, $yaml );

    print "\n--notice transformée--\n". $record->as_formatted ."\n";

conf.yaml:

    ---
    condition : $f501a eq "foo"
    create :
     f502a : New 502a subfield's value
    update :
      $f501b : \&LUT("$this")
    LUT :
     1 : first
     2 : second value in this LUT (LookUp Table)
    ---
    delete : f501c

Résultat (avec $record->as_formatted):

    --notice d'origine--
    LDR                         
    501    _afoo
           _b1
           _cbar
           _dbor
    
    --notice transformée--
    LDR                         
    501    _afoo
           _bfirst
    502    _aNew 502a subfield's value

- DESCRIPTION ^

C'est un module Perl pour transformer une notice MARC en utilisant un fichier de configuration YAML.

Il permet de créer , mettre à jour , supprimer , dupliquer les champs et les sous-champs d'une notice. Vous pouvez aussi utiliser des scripts et des tables de correspondance. Vous pouvez préciser des conditions pour executer ces actions.

Toutes les conditions, actions, fonctions et tables de correspondance sont définies dans le YAML.

MARC::Transform utilise MARC::Record.

- METHODE ^

- new()

    $record = MARC::Transform->new($record, "/path/conf.yaml" );

C'est la seule méthode que vous utiliserez. Elle prend un objet MARC::Record et le chemin vers un YAML comme arguments. Vous pouvez aussi écrire votre YAML dans une variable et l'utiliser pour transformer la notice comme ceci :

    my $yaml="delete : f501d\n";
    $record = MARC::Transform->new ( $record, $yaml );

- Référence à un hash optionnel

Comme nous allons le voir plus en détail plus bas, il est possible d'ajouter comme troisième argument une référence à un hash (nommé $mth dans le yaml).

    my $record = MARC::Record->new(); my $hashref = {'var' => 'foo'};
    my $yaml = 'create :
     f500a : $$mth{"var"}
    ';
    $record = MARC::Transform->new($record,$yaml,$hashref);
    #la valeur du nouveau sous-champ 500$a est "foo"

- Mode verbeux

Chaque règle du YAML (voir les bases plus bas pour comprendre ce qu'est une règle) génère un script qui est évalué, dans la notice, pour chaque champ et sous-champ spécifié dans la condition (si il y a une condition). En ajoutant un quatrième argument optionnel 1 à la méthode, elle affiche le script généré. Cela peut être utile pour comprendre ce qu'il se passe:

    $record = MARC::Transform->new($record,"/path/conf.yaml",0,1);

- YAML ^

- Bases

- Le YAML est divisé en règle (séparées par --- ), chaque règle est exécutée l'une après l'autre, les règles sans condition sont toujours exécutées:

    ---
    condition : $f501a eq "foo"
    create :
     f600a : new field value
    ---
    delete : f501c
    ---

- les conditions sont écrites en perl, ce qui permet une grande flexibilité. Elles doivent être définies avec condition :

    condition : ($f501a=~/foo/ and $f503a=~/bar/) or ($f102a eq "bib")
    # si un 501$a et un 503$a contiennent foo et bar, ou si un 102$a = bib

- Les conditions testent les notices champ par champ (uniquement sur les champs définis dans la condition)

Cela signifie, par exemple, que si nous avons plusieurs champs '501' dans la notice, si notre condition est $f501a eq "foo" and $f501b eq "bar", cette condition sera vrai uniquement si un champ '501' a un sous-champ 'a' = "foo" ET un sous-champ 'b' = 'bar' (elle sera fausse si il y a un champ '501' avec un sous-champ 'a' = "foo" et UN AUTRE champ '501' avec un sous-champ 'b' = "bar").

- Il est possible de lancer plusieurs actions différentes dans une seule règle:

    ---
    condition : $f501a eq "foo"
    create :
     f600a : new field value
    delete : f501c
    ---

- L'ordre dans lequel les actions sont écrites n'a pas d'importance. Les actions seront toujours exécutée dans l'ordre suivant:

- Chaque règle peut être divisée en sous-règles (séparées par - ) similaires à un 'if,elsif' ou un script 'switch,case'. Si la condition de la première sous-règle est fausse, la condition de la sous-règle suivante est testée. Lorsque la condition d'une sous-règle est vraie (ou si un sous-règle n'a pas de condition), les sous-règles suivantes ne sont pas lues.

    ---
    -
     condition : $f501a eq "foo"
     create :
      f502a : value if foo
    -
     condition : $f501a eq "bar"
     create :
      f502a : value elsif bar
    -
     create :
      f502a : value else
    ---
    # Si une sous-règle n'a pas de condition, elle sera considérée
    # comme un 'else' (les sous-règles suivantes ne seront pas lues)

- Il n'est pas permis de définir plus d'une action similaire dans une seule (sous-)règle. Cependant, il reste possible d'exécuter une action similaire plusieurs fois dans une seule règle (se référer à la syntaxe spécifique à chaque action pour voir comment faire cela):

. Cela n'est pas permis:

    ---
    delete : f501b
    delete : f501c

. cela fonctionne:

    ---
    delete :
     - f501b
     - f501c

- un petit script pour tester vos règles

- Il est fortement recommendé de tester chaque règle sur une notice de test avant de l'utiliser sur un large lot de notices. Vous pouvez créer un script (par exemple test.pl) avec le contenu ci-dessous (que vous adapterez pour tester vos règles) et le lancer avec perl ./test.pl :

    #!/usr/bin/perl
    use MARC::Transform;
    my $record = MARC::Record->new();
    $record->leader('optionnal leader');
    $record->insert_fields_ordered( MARC::Field->new('005', 'controlfield_content'));
    $record->insert_fields_ordered( MARC::Field->new('501', '', '', 'a' => 'foo', 'b' => 'bar') );
    print "\n--init record--\n". $record->as_formatted ."\n";
    my $yaml='---
    condition : $f501a eq "foo"
    create :
     f502a : condition is true
    ';
    $record = MARC::Transform->new($record,$yaml);
    print "\n--transformed record--\n". $record->as_formatted ."\n";

- Convention de nommage des champs et des sous-champs

- Dans les actions

- Les noms des champs et des sous-champs sont très importants:

- Dans les conditions

- Lancer des actions uniquement sur les champs de la condition

Nous avons déjà vu que pour se référer au champ de la condition dans les actions, il est possible de définir les sous-champs directement. Cela fonctionne uniquement si nous avons définis seulement un champ à tester dans la condition. Si nous avons plus d'un champ dans la condition, pour s'y référer, leurs noms doivent aussi commencer par $ (cela fonctionne également avec un champ unique dans la condition).

Par exemple, si vous testez la valeur du $f501a dans la condition:

- cela va supprimer les sous-champs 'c' uniquement dans le champ '501' qui est vrai dans la condition:

    condition : $f501a eq "foo" and defined $f501b
    delete : $f501c

- cela va supprimer les sous-champs 'c' dans tous les champs '501':

    condition : $f501a eq "foo" and defined $f501b
    delete : f501c

- cela va créer un nouveau champ '701' avec un sous-champ 'c' contenant la valeur du sous-champ 501$a défini dans la condition:

    condition : defined $f501a
    create :
     f701c : $f501a

ATTENTION: Pour avoir la valeur des sous-champs des champs de la condition, ces sous-champs doivent être définis dans la condition:

- cela ne fonctionne pas:

    condition : $f501a eq "foo"
    create :
     f701a : $f501c

- cela fonctionne (crée un nouveau champ '701' avec un sous-champ 'a' contenant la valeur du sous-champ 501$c de la condition):

    condition : $f501a eq "foo" and defined $f501c
    create :
     f701a : $f501c

- Cette restriction est vrai uniquement pour les valeurs des sous-champs mais pas pour spécifier les champs affectés par une action : l'exemple ci-dessous va créer un nouveau sous-champ 'c' dans un champ défini dans la condition.

    condition : $f501a eq "foo" and $f110a == 2
    create :
     $f501c : new subfield value
    # Si il y a de multiples champs '501', seuls ceux ayant un
    # sous-champ 'a'='foo' auront un nouveau sous-champ 'c' créé

- Actions

- create

- update

- updatefirst

- forceupdate et forceupdatefirst

- delete

- duplicatefield

- execute

- Utiliser des fonctions Perl et des tables des correspondance

Vous pouvez utiliser des fonctions Perl (subs) et des tables de correspondance (LUT pour LookUp Tables) pour définir avec une plus grande flexibilité les valeurs qui vont être créées ou mises à jour avec les actions: create, forceupdate, forceupdatefirst, update and updatefirst.

Ces fonctions (et tables des correspondance) peuvent être écrites dans une règle (dans ce cas elles ne peuvent être utilisée que par cette règle) ou après la dernière règle ( après le dernier ---, elles peuvent alors être utilisées dans toutes les règles: global_subs et global_LUT ).

- Variables

Quatre types de variables peuvent être utilisés:

- $this, et les éléments de la condition

- $mth

$mth est l'éventuel hashref passé comme troisième argument. Il est utilisable en écriture (dans les subs et les global_subs) et en lecture. Cela permet d'intéragir avec le script qui appelle MARC::Transform.

- $record

$record est l'objet MARC::Record en cours de traitement.

- subs

- A l'intérieur des règles

- global_subs

- LUT

Si une valeur n'a pas de correspondance dans une table de correspondance, elle n'est pas modifiée (à moins que vous n'ayez définit une valeur par défaut avec _default_value_ ).

Si vous voulez utiliser plus d'une table de correspondance dans une règle, vous devez utiliser une global_LUT car elle différencie les tables avec des titres.

- A l'intérieur des règles

- global_LUT

- $$mth{"_defaultLUT_to_mth_"}

- Dernières astuces et un gros exemple de YAML ^

- VOIR AUSSI ^

- AUTEUR ^

Stéphane Delaune, (delaune.stephane at gmail.com)

- COPYRIGHT ^

Copyright 2011-2013 Stephane Delaune for Biblibre.com, all rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

syntax highlighting: