MARC::Transform(3pm)

📦 version 0.003009, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 MARC::Transform 💖

okay bestie, so this is MARC::Transform from the User Contributed Perl Documentation section, aka section 3pm — it's a Perl module that transforms a MARC record using a YAML configuration file. let's get into it 🫶

🌸 NAME 🌸

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

🎀 VERSION 🎀

Version 0.003009 — yes, that's the actual number, she's precise like that 💅

🌈 SYNOPSIS 🌈

okay so first, the 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";

and here's 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

and the 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

like, look at that glow-up 😭✨ the record literally got a makeover.

💜 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.

no cap, everything lives in the YAML. the YAML is the main character here 👑

🦋 METHOD 🦋

✨ `new()` ✨

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

This is the only method you'll use. fr fr, just the one. 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 a rule is) 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);

bestie this is the "show me your work" mode and honestly? iconic for debugging 🔥

🧚 Define YAML configuration file encoding 🧚

You can force use of a specific encoding to open YAML configuration file by specifying it in the fifth optional argument like this (e.g. for an UTF-8 file)

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

or like this (e.g. for an Latin1 file)

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

🌟 YAML 🌟

🎀 Basis 🎀

YAML is divided in rules (separated by --- ), each rule is executed one after the other, rules without condition will always 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").

so important: the condition has to be true within one single field, not spread across two different fields. no mixing and matching 🙅‍♀️

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:
create
duplicatefield
forceupdate
forceupdatefirst
update
updatefirst
execute
delete

the way you write them is a vibe, the way they run is the law 💅

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('optional 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";

bestie PLEASE test on a test record first. running rules straight onto a big batch of records is giving chaos gremlin energy 😭💀

🦋 Field's and subfield's naming convention 🦋

✨ In actions ✨

Field's and subfield's names are very important:
They must begin with the letter f followed by the 3-digit field name (e.g. f099), followed, for the subfields, by their letter or digit (e.g. f501b).
Controlfields names begin with the letter f followed by 3-digit lower than 010 followed by underscore (e.g. f005_).
Indicators must begin with the letter i, followed by the 3-digit field name followed by the indicator's position (1 or 2) (e.g. i0991).
In actions, you can define a subfield directly (or an indicator with i1 or i2). Depending on context, it refers to the condition's field (if we define only one field to be tested in the condition), or to the field currently being processed in action:

---
condition : $f501a eq "foo"
create :
 b : new 'b' subfield's value in unique condition's field (501)
 f600 :
  i1 : 1
  a : new subfield (a) in this new 600 field
---

💅 In conditions 💅

In conditions, Field's and subfield's naming convention follow the same rules that actions, but they must be preceded by a dollar signs $ (e.g. $f110c for a subfield or $i0991 for an indicator).
The record leader can be defined with $ldr.
It's possible to test only one character's value in subfields or leader. To do this, you have to add the this character's position from 0 to 99:

#to test the 3rd char. in leader and the 12e char. in '501$a':
condition : $ldr2 eq "t" and $f501a11 eq "z"

🧚 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 ✨ (the moment u've been waiting for, bestie)

🎀 create

As the name suggests, this action lets u create brand new fields and subfields. yes. new. fresh out the box. 💅
Syntax:

# basic:
create :
 <subfield name> : <value>

# to create two subfields (in one field) with same name:
create :
 <subfield name> :
  - <value>
  - <value>

# advanced:
create :
 <field name> :
  <subfield name> :
   - <value>
   - <value>
  <subfield name> : <value>

Example:

---
condition : $f501a eq "foo"
create :
 b : new subfield's value on the condition's field
 f502a : this is the subfield's value of a new 502 field
 f502b :
  - this is the first 'b' value of another new 502
  - this is the 2nd 'b' value of this another new 502
 f600 :
  a :
   - first 'a' subfield of this new 600 field
   - second 'a' subfield of this new 600 field
  b : the 600b value

result (with $record->as_formatted):

--init record--
LDR
501    _afoo
       _b1
       _cbar
--transformed record--
LDR
501    _afoo
       _b1
       _cbar
       _bnew subfield's value on the condition's field
502    _bthis is the first 'b' value of another new 502
       _bthis is the 2nd 'b' value of this another new 502
502    _athis is the subfield's value of a new 502 field
600    _afirst 'a' subfield of this new 600 field
       _asecond 'a' subfield of this new 600 field
       _bthe 600b value

be careful bestie 😭 you NEED to use lists if u wanna create several subfields with the same name in one field:

# does not work:
create :
 f502b : value
 f502b : value

fr fr, that does NOT work. lists only. iykyk. 🫶

🌸 update

This action lets u update fields that already exist. it updates all the specified subfields of all the specified fields — (but if the specified field is a condition's field, then it'll be the only one getting updated, main character energy only 💅)
Syntax:

# basic:
update :
 <subfield name> : <value>

# advanced:
update :
 <subfield name> : <value>
 <subfield name> : <value>
 <field name> :
  <subfield name> : <value>
  <subfield name> : <value>

Example:

---
condition : $f502a eq "second a"
update :
 b : updated value of all 'b' subfields in the condition field
 f502c : updated value of all 'c' subfields into all '502' fields
 f501 :
  a : updated value of all 'a' subfields into all '501' fields
  b : $f502a is the 502a condition's field's value

result (with $record->as_formatted):

--init record--
LDR
501    _afoo
       _b1
       _cbar
502    _afirst a
       _asecond a
       _bbbb
       _cccc1
       _cccc2
502    _apoto
502    _btruc
       _cbidule
--transformed record--
LDR
501    _aupdated value of all 'a' subfields into all '501' fields
       _bsecond a is the 502a condition's field's value
       _cbar
502    _afirst a
       _asecond a
       _bupdated value of all 'b' subfields in the condition field
       _cupdated value of all 'c' subfields into all '502' fields
       _cupdated value of all 'c' subfields into all '502' fields
502    _apoto
502    _btruc
       _cupdated value of all 'c' subfields into all '502' fields

🦋 updatefirst

This action is identical to update, except it only updates the first subfield of the specified fields. first come, first served, periodt. ✨
Syntax: aside from the action's name, it's the same as the update's syntax
Example:

---
condition : $f502a eq "second a"
updatefirst :
 b : updated value of first 'b' subfields in the condition's field
 f502c : updated value of first 'c' subfields into all '502' fields
 f501 :
  a : updated value of first 'a' subfields into all '501' fields
  b : $f502a is the value of 502a conditionnal field

result (with $record->as_formatted):

--init record--
LDR
501    _afoo
       _b1
       _cbar
502    _afirst a
       _asecond a
       _bbbb
       _cccc1
       _cccc2
502    _apoto
502    _btruc
       _cbidule
--transformed record--
LDR
501    _aupdated value of first 'a' subfields into all '501' fields
       _bsecond a is the value of 502a conditionnal field
       _cbar
502    _afirst a
       _asecond a
       _bupdated value of first 'b' subfields in the condition's field
       _cupdated value of first 'c' subfields into all '502' fields
       _cccc2
502    _apoto
502    _btruc
       _cupdated value of first 'c' subfields into all '502' fields

💜 forceupdate and forceupdatefirst

If the specified subfields exist: these actions are identical to the update and the updatefirst actions
If the specified subfields don't exist: these actions are identical to the create action
Syntax: aside from the action's name, it's the same as the update's syntax
Example:

---
condition : $f502a eq "second a"
forceupdate :
 b : 'b' subfield's value in the condition's field
 f502c : '502c' value's
 f503 :
  a : '503a' value's
  b : $f502a is the 502a condition's value

result (with $record->as_formatted):

--init record--
LDR
501    _afoo
       _b1
       _cbar
502    _btruc
       _cbidule
502    _apoto
502    _afirst a
       _asecond a
       _bbbb
       _ccc1
       _ccc2
--transformed record--
LDR
501    _afoo
       _b1
       _cbar
502    _btruc
       _c'502c' value's
502    _apoto
       _c'502c' value's
502    _afirst a
       _asecond a
       _b'b' subfield's value in the condition's field
       _c'502c' value's
       _c'502c' value's
503    _a'503a' value's
       _bsecond a is the 502a condition's value
--transformed record if we had used forceupdatefirst--
LDR
501    _afoo
       _b1
       _cbar
502    _btruc
       _c'502c' value's
502    _apoto
       _c'502c' value's
502    _afirst a
       _asecond a
       _b'b' subfield's value in the condition's field
       _c'502c' value's
       _ccc2
503    _a'503a' value's
       _bsecond a is the value of 502a conditionnal field

🍓 delete

As the name suggests (again, iconically literal), this action lets u delete fields and subfields. bye bye 👋
Syntax:

# basic:
delete : <field or subfield name>

# advanced:
delete :
 - <field or subfield name>
 - <field or subfield name>

Example:

---
condition : $f501a eq "foo"
delete : $f501
---
condition : $f501a eq "bar"
delete : b
---
delete : f502
---
delete :
 - f503
 - f504a

result (with $record->as_formatted):

--init record--
LDR
501    _abar
       _bbb1
       _bbb2
501    _afoo
502    _apata
502    _apoto
503    _apata
504    _aata1
       _aata2
       _btbbt
--transformed record--
LDR
501    _abar
504    _btbbt

🧚 duplicatefield

As the name suggests, this action lets u duplicate entire fields. twin energy. two of everything. 👑
Syntax:

# basic:
duplicatefield : <field name> > <field name>

# advanced:
duplicatefield :
 - <field name> > <field name>
 - <field name> > <field name>

Example:

---
condition : $f008_ eq "controlfield_contentb"
duplicatefield : $f008 > f007
---
condition : $f501a eq "bar"
duplicatefield : $f501 > f400
---
condition : $f501a eq "foo"
duplicatefield :
 - f501 > f401
 - $f501 > f402
 - f005 > f006

result (with $record->as_formatted):

--init record--
LDR
005     controlfield_content2
005     controlfield_content1
008     controlfield_contentb
008     controlfield_contenta
501    _afoo
501 12 _abar
       _bbb1
       _bbb2
--transformed record--
LDR
005     controlfield_content2
005     controlfield_content1
006     controlfield_content1
006     controlfield_content2
007     controlfield_contentb
008     controlfield_contentb
008     controlfield_contenta
400 12 _abar
       _bbb1
       _bbb2
401 12 _abar
       _bbb1
       _bbb2
401    _afoo
402    _afoo
501    _afoo
501 12 _abar
       _bbb1
       _bbb2

💀 execute

This action is your "just write the Perl yourself" button — it lets you define Perl code that gets run with eval. 🪄
Syntax:

# basic:
execute : <perl code>

# advanced:
execute :
 - <perl code>
 - <perl code>

Example:

---
condition : $f501a eq "bar"
execute :
 - warn("f501a eq $f501a")
 - warn("barbar")
---
-
 condition : $f501a eq "foo"
 execute : \&warnfoo("f501a eq $f501a")
-
 subs : >
    sub warnfoo { my $string = shift;warn $string; }

result (in stderr):

f501a eq bar at (eval 30) line 6, <$yamls> line 1.
barbar at (eval 30) line 7, <$yamls> line 1.
f501a eq foo at (eval 33) line 2, <$yamls> line 1.

🌸 Use Perl functions and LookUp Tables 🌸

Bestie, this is the glow-up section. You can use Perl functions (subs) and lookup tables (LUT) to define, with way more flexibility, the values that get created or updated by the actions: create, forceupdate, forceupdatefirst, update and updatefirst. 💅

These functions (and lookup tables) can be written inside a rule — in which case only that one rule can use them — or after the last rule (like, after the last ---), in which case every rule can use them: that's global_subs and global_LUT. 🌈

💜 Variables

Four types of variables can be used:

$this, and condition's elements

variables pointing on the condition's subfield's values are those we have already seen in Chapter 'Run actions only on condition fields' (e.g. $f110c)
$this: this is the variable to use to pointing to the value of current subfield. $this can also be used outside a sub or a LUT.

Example (N.B.: sub 'fromo2e' converts 'o' to 'e'):

---
-
 condition : $f501a eq "foo"
 create :
  c : \&fromo2e("$f501a")
 update :
  d : this 501d value's is $this
  b : \&fromo2e("$this")
-
 subs: >
    sub fromo2e { my $string=shift; $string =~ s/o/e/g; $string; }

result (with "$record->as_formatted"):

--init record--
LDR
501    _afoo
       _bboo
       _ddoo
--transformed record--
LDR
501    _afoo
       _bbee
       _d this 501d value's is doo
       _cfee

$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 interaction with the script that calls MARC::Transform. 🫶

Syntaxe: $$mth{foo}
Example in a perl script :

my $record = MARC::Record->new();
$record->leader('optional leader');
print "--init record--\n". $record->as_formatted;
my %mth;
$mth{"inc"}=1;
$mth{"var"}="a string";
my $yaml = '
---
condition : $$mth{"var"} eq "a string"
forceupdate :
 f500a : $$mth{"var"}
---
-
 execute : \&testa()
-
 subs: >
    sub testa { $$mth{"inc"}++; }
---
forceupdate :
 f600a : \&testb()
---
global_subs: >
    sub testb { $$mth{"inc"}++;$$mth{"inc"}; }
';
$record = MARC::Transform->new($record,$yaml,\%mth);
print "\n--transformed record-- ".$mth{"inc"}." : \n". $record->as_formatted ."\n";

result :

--init record--
LDR optional leader
--transformed record-- 3 :
LDR optional leader
500    _aa string
600    _a3

$record

$record is the current MARC::Record object. 🎀

🦋 subs

Internal rules

Syntax:

#full rule:
---
-
 <method invocation syntax in the actions values, in sub-rule(s)>
-
 subs: >
    <one or more Perl subs>
---

# method invocation syntax:
\&<sub name>("<arguments>")

Example:

---
-
 condition : $f501a eq "foo" and defined $f501d
 update :
  b : \&convertbaddate("$this")
  c : \&trim("$f501d")
-
 subs: >
    sub convertbaddate {
        #this function convert date like "21/2/98" to "1998-02-28"
        my $in = shift;
        if ($in =~/^(\d{1,2})\/(\d{1,2})\/(\d{2}).*/)
        {
            my $day=$1;
            my $month=$2;
            my $year=$3;
            if ($day=~m/^\d$/) {$day="0".$day;}
            if ($month=~m/^\d$/) {$month="0".$month;}
            if (int($year)>12)
            {$year="19".$year;}
            else {$year="20".$year;}
            return "$year-$month-$day";
        }
        else
        {
            return $in;
        }
    }

    sub trim {
        # This function removes ",00" at the end of a string
        my $in = shift;
        $in=~s/,00$//;
        return $in;
    }

result (with "$record->as_formatted"):

--init record--
LDR
501    _afoo
       _b8/12/10
       _cboo
       _d40,00
--transformed record--
LDR
501    _afoo
       _b2010-12-08
       _c40
       _d40,00

global_subs

Syntax:

---
global_subs: >
    <one or more Perl subs>

# method invocation syntax:
\&<sub name>("<arguments>")

Example:

---
condition : $f501a eq "foo"
update :
 b : \&return_record_encoding()
 c : \&trim("$this")
---
global_subs: >
 sub return_record_encoding {
     $record->encoding();
 }

 sub trim {
     # This function removes ",00" at the end of a string
     my $in = shift;
     $in=~s/,00$//;
     return $in;
 }

result (with "$record->as_formatted" ):

--init record--
LDR
501    _afoo
       _bbar
       _c40,00
--transformed record--
LDR
501    _afoo
       _bMARC-8
       _c40

🌈 LUT

Heads up bestie: 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

Syntax:

#full rule:
---
-
 <LUT invocation syntax in the actions values, inside sub-rule(s)>
-
 LUT :
   <starting value> : <final value>
   <starting value> : <final value>
   _default_value_ : optional default value
---

# LUT invocation syntax:
\&LUT("<starting value>")

Example:

---
-
 condition : $f501b eq "bar"
 create :
  f604a : \&LUT("$f501b")
 update :
  c : \&LUT("$this")
-
 LUT :
  1 : first
  2 : second
  bar : openbar

result (with "$record->as_formatted" ):

--init record--
LDR
501    _bbar
       _c1
--transformed record--
LDR
501    _bbar
       _cfirst
604    _aopenbar

⭐ global_LUT

Syntax:

---
global_LUT:
 <LUT title> :
  <starting value> : <final value>
  <starting value> : <final value>
  _default_value_ : valeur par defaut optionnelle
 <LUT title> :
  <starting value> : <final value>
  <starting value> : <final value>

# global_LUT invocation syntax:
\&LUT("<starting value>","<LUT title>")

Example:

---
update :
 f501a : \&LUT("$this","numbers")
 f501b : \&LUT("$this","cities")
 f501c : \&LUT("$this","cities")
---
global_LUT:
 cities:
  NY : New York
  SF : San Fransisco
  TK : Tokyo
  _default_value_ : unknown city
 numbers:
  1 : one
  2 : two

result (with "$record->as_formatted" ):

--init record--
LDR
501    _a1
       _a3
       _bfoo
       _cSF
--transformed record--
LDR
501    _aone
       _a3
       _bunknown city
       _cSan Fransisco

💖 `$$mth{"_defaultLUT_to_mth_"}`

Note: if you call MARC::Transform with the third parameter, the module filled its key named "_defaultLUT_to_mth_" in case you want to keep, in the calling script, track of the values and types (named "lookuptableforthis" for non-global's LUT) unmatched. $$mth{"_defaultLUT_to_mth_"} is cleared each time MARC::Transform->new is called.
If we recall the above example with :

my %mth;
$record = MARC::Transform->new($record,$yaml,\%mth);
print $mth{"_defaultLUT_to_mth_"}->{"cities"}[0];
print "\n".Data::Dumper::Dumper $mth{"_defaultLUT_to_mth_"};

will return in stdout :

foo
$VAR1 = {
          'numbers' => [
                         '3'
                       ],
          'cities' => [
                        'foo'
                      ]
        };

try this if you want to get the content of $mth{"_defaultLUT_to_mth_"} instead of the line containing Data::Dumper::Dumper :

...and if you want to actually see what's sitting inside your _defaultLUT_to_mth_ hash, this little loop is the move — it walks every key $k, then every value in the arrayref hanging off that key, and prints them all as $k : $value:

foreach my $k (keys(%{$mth{"_defaultLUT_to_mth_"}}))
{
    foreach my $value(@{$mth{"_defaultLUT_to_mth_"}->{"$k"}})
    { print "$k : $value \n"; }
}

Vibe check your LUTs, bestie. It's giving debugging main character energy. 💅

✨ Latest tips and a big YAML example's ✨

The YAML Error: Stream does not end with newline character glow-up — okay so if your script throws this, it's lowkey easy to fix. If you define your YAML inside a variable, it must end with a new blank line. If you give a path to your YAML file instead and it's still acting up, it's probably not good: try an absolute path. 🫶
Restriction: the specific case of double-quotes (") and dollar signs ($) — in YAML these characters are interpreted differently. So to use them in a string context, you'll need to replace them in your YAML with "#_dbquote_#" (that's for ") and "#_dollars_#" (that's for $):
- Example:

---
condition : $f501a eq "I want #_dbquote_##_dollars_##_dbquote_#"
create :
 f604a : "#_dbquote_#$f501a#_dbquote_# contain a #_dollars_# sign"

result (with "$record->as_formatted"):

--init record--
LDR
501    _aI want "$"
--transformed record--
LDR
501    _aI want "$"
604    _a"I want "$"" contain a $ sign

Restriction: existence checks, not absence checks — you can test if a field or subfield exists, but it is inadvisable to test its absence. Not the move, bestie. 🙈
Example: copy-paste privileges — feel free to copy the examples in this documentation. Just be aware that four space characters were added at the beginning of each example's line to make them display better for the POD interpreter. So if you copy/paste them into your YAML configuration file, be sure to remove the first four characters of each line (e.g. with vim, :%s/^\s\s\s\s//g).
This yaml was called like this: my %mth; $mth{"var"}="a string"; $record = MARC::Transform->new($record,$yaml,\%mth);

---
condition : $f501a eq "foo"
create :
 f502a : this is the value of a subfield of a new 502 field
---
condition : $f401a=~/foo/
create :
 b : new value of the 401 condition's field
 f600 :
  a :
   - first a subfield of this new 600 field
   - second a subfield of this new 600 field
   - $$mth{"var"}
  b : the 600b value
execute : \&reencodeRecordtoUtf8()
---
-
 condition : $f501a =~/foo/ and $f503a =~/bar/
 forceupdate :
  $f503b : mandatory b in condition's field
  f005_ : mandatory 005
  f006_ : \&return_record_encoding()
  f700 :
   a : the a subfield of this mandatory 700 field
   b : \&sub1("$f503a")
 forceupdatefirst :
  $f501b : update only the first b in condition's field 501
-
 condition : $f501a =~/foo/
 execute : \&warnfoo("f501a contain foo")
-
 subs : >
    sub return_record_encoding { $record->encoding(); }
    sub sub1 {my $string=shift;$string =~ s/a/e/g;return $string;}
    sub warnfoo { my $string = shift;warn $string; }
---
-
 condition : $f501b2 eq "o"
 update :
  c : updated value of all c in condition's field
  f504a : updated value of all 504a if exists
  f604 :
   b : \&LUT("$this")
   c : \&LUT("NY","cities")
 updatefirst :
  f604a : update only the first a in 604
-
 condition : $f501c eq "1"
 delete : $f501
-
 LUT :
   1 : first
   2 : second
   bar : openbar
---
delete :
 - f401a
 - f005
---
condition : $ldr2 eq "t"
execute : \&SetRecordToLowerCase($record)
---
condition : $f008_ eq "controlfield_content8b"
duplicatefield :
 - $f008 > f007
 - f402 > f602
delete : f402
---
global_subs: >
    sub reencodeRecordtoUtf8 {
        $record->encoding( 'UTF-8' );
    }
    sub warnfee {
        my $string = shift;warn $string;
    }
global_LUT:
 cities:
  NY : New York
  SF : San Fransisco
 numbers:
  1 : one
  2 : two

result (with "$record->as_formatted"):

--init record--
LDR optional leader
005     controlfield_content
008     controlfield_content8a
008     controlfield_content8b
106    _aVaLuE
401    _aafooa
402  2 _aa402a2
402 1  _aa402a1
501    _c1
501    _afoo
       _afoao
       _b1
       _bbaoar
       _cbig
503    _afee
       _ababar
504    _azut
       _asisi
604    _afoo
       _afoo
       _bbar
       _ctruc

--transformed record--
LDR optional leader
006     UTF-8
007     controlfield_content8b
008     controlfield_content8a
008     controlfield_content8b
106    _aVaLuE
401    _bnew value of the 401 condition's field
501    _c1
501    _afoo
       _afoao
       _bupdate only the first b in condition's field 501
       _bbaoar
       _cupdated value of all c in condition's field
502    _athis is the value of a subfield of a new 502 field
503    _afee
       _ababar
       _bmandatory b in condition's field
504    _aupdated value of all 504a if exists
       _aupdated value of all 504a if exists
600    _aa string
       _afirst a subfield of this new 600 field
       _asecond a subfield of this new 600 field
       _bthe 600b value
602 1  _aa402a1
602  2 _aa402a2
604    _aupdate only the first a in 604
       _afoo
       _bopenbar
       _cNew York
700    _athe a subfield of this mandatory 700 field
       _bbeber

🔗 SEE ALSO

MARC::Record (<http://search.cpan.org/perldoc?MARC::Record>)
MARC::Field (<http://search.cpan.org/perldoc?MARC::Field>)
MARC::Loader (<http://search.cpan.org/perldoc?MARC::Loader>)
YAML (<http://search.cpan.org/perldoc?YAML>)
Library Of Congress MARC pages (<http://www.loc.gov/marc/>)

The definitive source for all things MARC. 👑

👑 AUTHOR

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

📜 COPYRIGHT

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

💖 DOCUMENTATION FRANCAISE 💖

(oui bestie, we're going multilingual — the whole French translation is right here and we're keeping every word of it 🥐)

🇫🇷 NOM

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

🇫🇷 VERSION

Version 0.003009

🇫🇷 SYNOPSIS

Perl script:

use MARC::Transform;

# Pour ce synopsis, nous creons 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 appele depuis le bon endroit) :
$record = MARC::Transform->new ( $record, "/path/conf.yaml" );

# Vous pouvez aussi ecrire 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 transformee--\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

Resultat (avec "$record->as_formatted"):

--notice d'origine--
LDR
501    _afoo
       _b1
       _cbar
       _dbor

--notice transformee--
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 creer , mettre a 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 preciser des conditions pour executer ces actions.

Toutes les conditions, actions, fonctions et tables de correspondance sont definies dans le YAML.

MARC::Transform utilise MARC::Record.

💅 `new()` 💅

okay so bestie, real talk: this is literally the only method you will ever use. that's it. one method. iconic behaviour honestly. 🫶

it takes a MARC::Record object and the path to a YAML file as its arguments. and if you don't feel like making a whole file, you can also write your YAML straight into a variable and use that to transform the record, like this:

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

Reference a un hash optionnel 🔑

so like we're gonna see this in more detail further down, but you can slide a reference to a hash in as the third argument (it's called $mth inside the yaml, cute right?):

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 🗣️

every single rule in your YAML (peep the bases section below if you're like "what is a rule") generates a script that gets eval'd against the record, for every field and subfield named in the condition (if there even is a condition). add an optional fourth argument of 1 and it'll print out the generated script for you. super handy when you're sitting there like "girl what is happening":

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

Definir l'encodage du fichier de configuration YAML 🔤

you can force the YAML config file to open in a specific encoding by saying so in the fifth optional argument. like this (for a UTF-8 file):

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

or like this (for a Latin1 file):

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

🌸 - YAML 🌸

🎀 - Bases 🎀

the YAML is split up into rules (separated by ---), and every rule runs one after the other. rules with no condition? they always run, no questions asked:

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

conditions are written in perl, which is lowkey why they're so flexible. they have to be declared with 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

conditions test records field by field (only on the fields you actually named in the condition)

which means, for example, that if we've got several 501 fields in the record and our condition is $f501a eq "foo" and $f501b eq "bar", that condition is only true if one single 501 field has a a subfield = "foo" AND a b subfield = 'bar'. it's false if there's a 501 with a = "foo" and a whole OTHER 501 with b = "bar". no mixing and matching, bestie. 💀

you can run several different actions inside a single rule:

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

the order you write the actions in? literally doesn't matter. they always execute in this order:
- create
- duplicatefield
- forceupdate
- forceupdatefirst
- update
- updatefirst
- execute
- delete
every rule can be split into sub-rules (separated by -), basically an if,elsif situation or a switch,case script. if the first sub-rule's condition is false, the next sub-rule's condition gets tested. the moment a sub-rule's condition is true (or a sub-rule has no condition at all), the following sub-rules are not read. periodt.

---
-
 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-regle n'a pas de condition, elle sera consideree
# comme un 'else' (les sous-regles suivantes ne seront pas lues)

you are not allowed to define more than one similar action in a single (sub-)rule. that said, you can still run a similar action several times in one rule (go check the syntax specific to each action to see how):
- this is NOT allowed:

---
delete : f501b
delete : f501c

this works:

---
delete :
 - f501b
 - f501c

un petit script pour tester vos regles 🧪
it is strongly recommended that you test every rule on a test record before you unleash it on a whole big batch of records. you can make a script (say, test.pl) with the content below (adapt it to test your own rules) and run it with perl ./test.pl:

#!/usr/bin/perl
use MARC::Transform;
my $record = MARC::Record->new();
$record->leader('optional 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
field and subfield names are SO important, like genuinely:
- they have to start with the letter f followed by the 3 digits of the field name (for example f099), followed, for subfields, by their letter or digit (for example f501b).
- control field names start with the letter f followed by 3 digits less than 010 followed by an underscore (for example f005_).
- indicators have to start with the letter i, followed by the 3 digits of the field name followed by the indicator's position (1 or 2) (for example i0991).
- in the actions, you can define a subfield directly (or an indicator with i1 or i2). depending on the context, it refers to the condition's field (if we only defined one field to test in the condition), or to the field currently being processed in the action:

---
condition : $f501a eq "foo"
create :
 b : new 'b' subfield's value in unique condition's field (501)
 f600 :
  i1 : 1
  a : new subfield (a) in this new 600 field
---

Dans les conditions
- in conditions, the field and subfield naming convention follows the same rules as the actions, except they have to be preceded by the dollar symbol $ (for example $f110c for a subfield or $i0991 for an indicator).
- the record's leader can be referenced with $ldr.
- you can test the value of a single character inside subfields or the leader. to do that, you append the position of that character, starting from 0 up to 99:

#pour tester le 3e caractere du leader et le 12e dans le 501$a:
condition : $ldr2 eq "t" and $f501a11 eq "z"

Lancer des actions uniquement sur les champs de la condition 🎯

we already saw that to refer to the condition's field inside actions, you can just define the subfields directly. that only works if you defined only one field to test in the condition. if you've got more than one field in the condition, then to refer to them, their names have to start with $ too (this also works with a single field in the condition, btw).

for example, if you're testing the value of $f501a in the condition:

this deletes the c subfields only in the 501 field that's true in the condition:

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

this deletes the c subfields in all the 501 fields:

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

this creates a new 701 field with a c subfield holding the value of the 501$a subfield defined in the condition:

condition : defined $f501a
create :
 f701c : $f501a

ATTENTION: ⚠️ to get the value of the subfields from the condition's fields, those subfields have to be defined in the condition. no cap.

this does not work:

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

this does work (creates a new 701 field with an a subfield containing the value of the 501$c subfield from the condition):

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

this restriction is only true for subfield values, not for specifying the fields affected by an action: the example below creates a new c subfield in a field defined in the 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' cree

👑 - Actions 👑

⭐ create ⭐

like the name says, this action lets you create new fields and subfields. ✨
syntax:

# basique:
create :
 <nom de sous-champ> : <valeur>

# pour creer deux sous-champs (dans un champ) avec le meme nom:
create :
 <nom de sous-champ> :
  - <valeur>
  - <valeur>

# avancee:
create :
 <nom de champ> :
  <nom de sous-champ> :
   - <valeur>
   - <valeur>
  <nom de sous-champ> : <valeur>

example:

---
condition : $f501a eq "foo"
create :
 b : new subfield's value on the condition's field
 f502a : this is the subfield's value of a new 502 field
 f502b :
  - this is the first 'b' value of another new 502
  - this is the 2nd 'b' value of this another new 502
 f600 :
  a :
   - first 'a' subfield of this new 600 field
   - second 'a' subfield of this new 600 field
  b : the 600b value

result (with $record->as_formatted):

--notice d'origine--
LDR
501    _afoo
      _b1
      _cbar
--notice transformee--
LDR
501    _afoo
      _b1
      _cbar
      _bnew subfield's value on the condition's field
502    _bthis is the first 'b' value of another new 502
      _bthis is the 2nd 'b' value of this another new 502
502    _athis is the subfield's value of a new 502 field
600    _afirst 'a' subfield of this new 600 field
      _asecond 'a' subfield of this new 600 field
      _bthe 600b value

Like, look at it 😭 it's gorgeous. One original record, and boom — new subfields, new fields, everything slotted in exactly where the YAML said.

⚠️ faites attention: vous devez utilisez des listes pour creer plusieurs sous-champs avec le meme nom dans un champ:

# ne fonctionne pas:
create :
 f502b : value
 f502b : value

big red flag bestie — two subfields with the same name = you must use a list. Write it twice like that and it just won't do the thing. The YAML eats the duplicate and you're left standing there like 🧍‍♀️

✨ update ✨

Cette action vous permet de mettre a jour les champs existants. Cette action met a jour tous les sous-champs specifies de tous les champs specifies (si le champ specifie est un champ de la condition, il sera le seul a etre mis a jour )

Okay so update is the glow-up action 💅 — it changes fields that already exist. Every subfield you name gets updated across every field you name. One lil catch: if the field you name is the condition's field, then it's the only one that gets touched. No extras. Just that one. 👑

Syntaxe:

# basique:
update :
 <nom de sous-champ> : <valeur>

# avancee:
update :
 <nom de sous-champ> : <valeur>
 <nom de sous-champ> : <valeur>
 <nom de champ> :
  <nom de sous-champ> : <valeur>
  <nom de sous-champ> : <valeur>

Exemple:

---
condition : $f502a eq "second a"
update :
 b : updated value of all 'b' subfields in the condition field
 f502c : updated value of all 'c' subfields into all '502' fields
 f501 :
  a : updated value of all 'a' subfields into all '501' fields
  b : $f502a is the 502a condition's field's value

resultat (avec $record->as_formatted):

--notice d'origine--
LDR
501    _afoo
      _b1
      _cbar
502    _afirst a
      _asecond a
      _bbbb
      _cccc1
      _cccc2
502    _apoto
502    _btruc
      _cbidule
--notice transformee--
LDR
501    _aupdated value of all 'a' subfields into all '501' fields
      _bsecond a is the 502a condition's field's value
      _cbar
502    _afirst a
      _asecond a
      _bupdated value of all 'b' subfields in the condition field
      _cupdated value of all 'c' subfields into all '502' fields
      _cupdated value of all 'c' subfields into all '502' fields
502    _apoto
502    _btruc
      _cupdated value of all 'c' subfields into all '502' fields

see how every matching subfield got the new value? That's the "all" in "all the subfields". Obsessed 🫶

✨ updatefirst ✨

Cette action est identique a update, excepte qu'elle met a jour seulement le premier sous-champ des champs specifies
Syntaxe: excepte pour le nom de l'action, c'est la meme que la syntaxe de update
Exemple:

---
condition : $f502a eq "second a"
updatefirst :
 b : updated value of first 'b' subfields in the condition's field
 f502c : updated value of first 'c' subfields into all '502' fields
 f501 :
  a : updated value of first 'a' subfields into all '501' fields
  b : $f502a is the value of 502a conditionnal field

resultat (avec $record->as_formatted):

--notice d'origine--
LDR
501    _afoo
      _b1
      _cbar
502    _afirst a
      _asecond a
      _bbbb
      _cccc1
      _cccc2
502    _apoto
502    _btruc
      _cbidule
--notice transformee--
LDR
501    _aupdated value of first 'a' subfields into all '501' fields
      _bsecond a is the value of 502a conditionnal field
      _cbar
502    _afirst a
      _asecond a
      _bupdated value of first 'b' subfields in the condition's field
      _cupdated value of first 'c' subfields into all '502' fields
      _cccc2
502    _apoto
502    _btruc
      _cupdated value of first 'c' subfields into all '502' fields

lowkey the same energy as update, but it only touches the FIRST one it finds. The _cccc2 stayed exactly where it was — untouched, unbothered, thriving 🌸

✨ forceupdate et forceupdatefirst ✨

Si le sous-champ specifie existe: ces actions sont identiques aux actions update et updatefirst
Si le sous-champ specifie n'existe pas: ces actions sont identiques a l'action create
Syntaxe: excepte pour le nom de l'action, c'est la meme que la syntaxe de update
Exemple:

---
condition : $f502a eq "second a"
forceupdate :
 b : 'b' subfield's value in the condition's field
 f502c : '502c' value's
 f503 :
  a : '503a' value's
  b : $f502a is the 502a condition's value

resultat (avec $record->as_formatted):

--notice d'origine--
LDR
501    _afoo
      _b1
      _cbar
502    _btruc
      _cbidule
502    _apoto
502    _afirst a
      _asecond a
      _bbbb
      _ccc1
      _ccc2
--notice transformee--
LDR
501    _afoo
      _b1
      _cbar
502    _btruc
      _c'502c' value's
502    _apoto
      _c'502c' value's
502    _afirst a
      _asecond a
      _b'b' subfield's value in the condition's field
      _c'502c' value's
      _c'502c' value's
503    _a'503a' value's
      _bsecond a is the 502a condition's value
--notice transformee si nous avions utilise forceupdatefirst--
LDR
501    _afoo
      _b1
      _cbar
502    _btruc
      _c'502c' value's
502    _apoto
      _c'502c' value's
502    _afirst a
      _asecond a
      _b'b' subfield's value in the condition's field
      _c'502c' value's
      _ccc2
503    _a'503a' value's
      _bsecond a is the value of 502a conditionnal field

the moment a field like 503 didn't even exist and forceupdate just made it 😭✨ that's the create half of the deal kicking in. No notes, perfection. 👑

✨ delete ✨

Comme son nom l'indique, cette action vous permet de supprimer des champs et sous-champs.
Syntaxe:

# basique:
delete : <nom de champ ou sous-champ>

# avancee:
delete :
 - <nom de champ ou sous-champ>
 - <nom de champ ou sous-champ>

Exemple:

---
condition : $f501a eq "foo"
delete : $f501
---
condition : $f501a eq "bar"
delete : b
---
delete : f502
---
delete :
 - f503
 - f504a

resultat (avec $record->as_formatted):

--notice d'origine--
LDR
501    _abar
      _bbb1
      _bbb2
501    _afoo
502    _apata
502    _apoto
503    _apata
504    _aata1
      _aata2
      _btbbt
--notice transformee--
LDR
501    _abar
504    _btbbt

poof 💀 gone. Whole fields, single subfields, a list of them — delete takes them out. And notice it works even when there's no condition line at all, like that third and fourth block. No condition = just do it 🌈

✨ duplicatefield ✨

Comme son nom l'indique, cette action vous permet de dupliquer des champs entiers.
Syntaxe:

# basique:
duplicatefield : <nom de champ> > <nom de champ>

# avancee:
duplicatefield :
 - <nom de champ> > <nom de champ>
 - <nom de champ> > <nom de champ>

Exemple:

---
condition : $f008_ eq "controlfield_contentb"
duplicatefield : $f008 > f007
---
condition : $f501a eq "bar"
duplicatefield : $f501 > f400
---
condition : $f501a eq "foo"
duplicatefield :
 - f501 > f401
 - $f501 > f402
 - f005 > f006

resultat (avec $record->as_formatted):

--notice d'origine--
LDR
005     controlfield_content2
005     controlfield_content1
008     controlfield_contentb
008     controlfield_contenta
501    _afoo
501 12 _abar
      _bbb1
      _bbb2
--notice transformee--
LDR
005     controlfield_content2
005     controlfield_content1
006     controlfield_content1
006     controlfield_content2
007     controlfield_contentb
008     controlfield_contentb
008     controlfield_contenta
400 12 _abar
      _bbb1
      _bbb2
401 12 _abar
      _bbb1
      _bbb2
401    _afoo
402    _afoo
501    _afoo
501 12 _abar
      _bbb1
      _bbb2

the > arrow is doing so much work here 🦋 left side = the field you're copying, right side = the brand new field it becomes. copy → paste, copy → paste, copy → paste. Iconic. And yes, the original stays put — nothing gets replaced, it's a whole extra field 💖

✨ execute ✨

Cette action vous permet de definir du code Perl qui sera execute avec eval

Vous pouvez executer des fonctions ecrites directement dans le YAML ( pour des details sur l'ecriture de subs perl dans le YAML, referez vous au chapitre suivant: Utiliser des fonctions Perl et des tables des correspondance)

bestie heads up: this one runs your code through eval. So like… it does exactly what you wrote. 💅

Syntaxe:

# basique:
execute : <code perl>

# avancee:
execute :
 - <code perl>
 - <code perl>

Exemple:

---
condition : $f501a eq "bar"
execute :
 - warn("f501a eq $f501a")
 - warn("barbar")
---
-
 condition : $f501a eq "foo"
 execute : \&warnfoo("f501a eq $f501a")
-
 subs : >
    sub warnfoo { my $string = shift;warn $string; }

resultat (dans stderr):

f501a eq bar at (eval 30) line 6, <$yamls> line 1.
barbar at (eval 30) line 7, <$yamls> line 1.
f501a eq foo at (eval 33) line 2, <$yamls> line 1.

and that's your Perl, living its best life inside a YAML file 🧚 Note the output went to stderr, not stdout — that's where warn goes, so don't go looking for it in the regular output, bestie 🙈

Utiliser des fonctions Perl et des tables des correspondance 🎀

okok donc bestie, écoute bien : tu peux utiliser des fonctions Perl (les subs) et des tables de correspondance (LUT, aka LookUp Tables) pour définir avec une flexibilité absolue les valeurs qui vont etre creees ou mises a jour avec les actions : create, forceupdate, forceupdatefirst, update and updatefirst.

Et le plot twist : ces fonctions (et ces tables de correspondance) peuvent etre ecrites dans une regle (dans ce cas elles ne peuvent etre utilisee que par cette regle, no sharing 💅) ou apres la derniere regle (apres le dernier ---, elles peuvent alors etre utilisees dans toutes les regles : global_subs et global_LUT). periodt.

Variables ✨

Quatre types de variables peuvent etre utilises:

$this, et les elements de la condition
- les variables pointant sur la valeur des sous-champs de la condition sont celles que nous avons deja vu dans le chapitre 'Lancer des actions uniquement sur les champs de la condition' (par exemple $f110c)
- $this : c'est la variable a utiliser pour pointer sur la valeur du sous-champ en cours. $this peut aussi etre utilisee dans une sub ou une LUT.

Exemple (N.B. : la sub fromo2e convertit les o en e) :

---
-
 condition : $f501a eq "foo"
 create :
  c : \&fromo2e("$f501a")
 update :
  d : this 501d value's is $this
  b : \&fromo2e("$this")
-
 subs: >
    sub fromo2e { my $string=shift; $string =~ s/o/e/g; $string; }

resultat (avec "$record->as_formatted"):

--notice d'origine--
LDR
501    _afoo
       _bboo
       _ddoo
--notice transformee--
LDR
501    _afoo
       _bbee
       _d this 501d value's is doo
       _cfee

$mth 💜

$mth est l'eventuel hashref passe comme troisieme argument. Il est utilisable en ecriture (dans les subs et les global_subs) et en lecture. Cela permet d'interagir avec le script qui appelle MARC::Transform. Deux sens de circulation, iconique.

Syntaxe : $$mth{foo}
Exemple dans un script perl :

my $record = MARC::Record->new();
$record->leader('optional leader');
print "--init record--\n". $record->as_formatted;
my %mth;
$mth{"inc"}=1;
$mth{"var"}="a string";
my $yaml = '
---
condition : $$mth{"var"} eq "a string"
forceupdate :
 f500a : $$mth{"var"}
---
-
 execute : \&testa()
-
 subs: >
    sub testa { $$mth{"inc"}++; }
---
forceupdate :
 f600a : \&testb()
---
global_subs: >
    sub testb { $$mth{"inc"}++;$$mth{"inc"}; }
';
$record = MARC::Transform->new($record,$yaml,\%mth);
print "\n--transformed record-- ".$mth{"inc"}." : \n". $record->as_formatted ."\n";

resultat :

--init record--
LDR optional leader
--transformed record-- 3 :
LDR optional leader
500    _aa string
600    _a3

$record 📚

$record est l'objet MARC::Record en cours de traitement. Lui, c'est le goat du fichier.

subs 🧚
- A l'interieur des regles
  - Syntaxe :

#regle entiere:
---
-
 <syntaxe d'invocation de la methode dans les valeurs des actions>
-
 subs: >
    <une ou plusieurs subs Perl>
---

# syntaxe d'invocation de la methode:
\&<sub name>("<arguments>")

Exemple :

---
-
 condition : $f501a eq "foo" and defined $f501d
 update :
  b : \&convertbaddate("$this")
  c : \&trim("$f501d")
-
 subs: >
    sub convertbaddate {
        #convertit les dates du type "21/2/98" en "1998-02-28"
        my $in = shift;
        if ($in =~/^(\d{1,2})\/(\d{1,2})\/(\d{2}).*/)
        {
            my $day=$1;
            my $month=$2;
            my $year=$3;
            if ($day=~m/^\d$/) {$day="0".$day;}
            if ($month=~m/^\d$/) {$month="0".$month;}
            if (int($year)>12)
            {$year="19".$year;}
            else {$year="20".$year;}
            return "$year-$month-$day";
        }
        else
        {
            return $in;
        }
    }

    sub trim {
        # Cette fonction enleve ",00" a la fin d'une chaine
        my $in = shift;
        $in=~s/,00$//;
        return $in;
    }

resultat (avec "$record->as_formatted"):

--notice d'origine--
LDR
501    _afoo
       _b8/12/10
       _cboo
       _d40,00
--notice transformee--
LDR
501    _afoo
       _b2010-12-08
       _c40
       _d40,00

global_subs 🌍
- Syntaxe :

---
global_subs: >
    <une ou plusieurs subs Perl>

# syntaxe d'invocation de la methode
\&<sub name>("<arguments>")

Exemple :

---
condition : $f501a eq "foo"
update :
 b : \&return_record_encoding()
 c : \&trim("$this")
---
global_subs: >
 sub return_record_encoding {
     $record->encoding();
 }

 sub trim {
     # Cette fonction enleve ",00" a la fin d'une chaine
     my $in = shift;
     $in=~s/,00$//;
     return $in;
 }

resultat (avec "$record->as_formatted" ):

--notice d'origine--
LDR
501    _afoo
       _bbar
       _c40,00
--notice transformee--
LDR
501    _afoo
       _bMARC-8
       _c40

LUT 🔍

Si une valeur n'a pas de correspondance dans une table de correspondance, elle n'est pas modifiee (a moins que vous n'ayez definit une valeur par defaut avec "_default_value_" ). Elle reste tranquille, elle bouge pas.

Si vous voulez utiliser plus d'une table de correspondance dans une regle, vous devez utiliser une global_LUT car elle differencie les tables avec des titres. Sinon c'est le chaos, et pas le fun genre.

A l'interieur des regles
- Syntaxe :

#regle entiere:
---
-
 <syntaxe d'invocation de la LUT dans les valeurs des actions>
-
 LUT :
   <valeur de depart> : <valeur finale>
   <valeur de depart> : <valeur finale>
   _default_value_ : valeur par defaut optionnelle
---

# syntaxe d'invocation de la LUT:
\&LUT("<valeur de depart>")

Exemple :

---
-
 condition : $f501b eq "bar"
 create :
  f604a : \&LUT("$f501b")
 update :
  c : \&LUT("$this")
-
 LUT :
  1 : first
  2 : second
  bar : openbar

resultat (avec "$record->as_formatted" ):

--notice d'origine--
LDR
501    _bbar
       _c1
--notice transformee--
LDR
501    _bbar
       _cfirst
604    _aopenbar

global_LUT 🌈
- Syntaxe :

---
global_LUT:
 <titre de la LUT> :
  <valeur de depart> : <valeur finale>
  <valeur de depart> : <valeur finale>
  _default_value_ : valeur par defaut optionnelle
 <titre de la LUT> :
  <valeur de depart> : <valeur finale>
  <valeur de depart> : <valeur finale>

# syntaxe d'invocation de la global_LUT:
\&LUT("<valeur de depart>","<titre de la LUT>")

Exemple :

---
update :
 f501a : \&LUT("$this","numbers")
 f501b : \&LUT("$this","cities")
 f501c : \&LUT("$this","cities")
---
global_LUT:
 cities:
  NY : New York
  SF : San Fransisco
  TK : Tokyo
  _default_value_ : unknown city
 numbers:
  1 : one
  2 : two

resultat (avec "$record->as_formatted" ):

--notice d'origine--
LDR
501    _a1
       _a3
       _bfoo
       _cSF
--notice transformee--
LDR
501    _aone
       _a3
       _bunknown city
       _cSan Fransisco

$$mth{"_defaultLUT_to_mth_"} 🙈
- NB : si vous appelez MARC::Transform avec le troisieme parametre, le module en rempli la cle nommee "_defaultLUT_to_mth_" au cas ou vous souhaiteriez conserver, dans le script d'appel, une trace des valeurs et types (nomme "lookuptableforthis" pour les LUT non globales) sans correspondance. $$mth{"_defaultLUT_to_mth_"} est videe a chaque fois que MARC::Transform->new est appele.
- Si nous rappellons l'exemple ci-dessus avec :

my %mth;
$record = MARC::Transform->new($record,$yaml,\%mth);
print $mth{"_defaultLUT_to_mth_"}->{"cities"}[0];
print "\n".Data::Dumper::Dumper $mth{"_defaultLUT_to_mth_"};

cela renverra sur la sortie standard :

foo
$VAR1 = {
          'numbers' => [
                         '3'
                       ],
          'cities' => [
                        'foo'
                      ]
        };

essayez ceci si vous souhaitez recuperer le contenu de $mth{"_defaultLUT_to_mth_"} a la place de la ligne contenant Data::Dumper::Dumper :

foreach my $k (keys(%{$mth{"_defaultLUT_to_mth_"}}))
{
    foreach my $value(@{$mth{"_defaultLUT_to_mth_"}->{"$k"}})
    { print "$k : $value \n"; }
}

- Dernieres astuces et un gros exemple de YAML 🎀✨

okay bestie, final stretch, and it's literally the best part — the tips and the giant YAML flex 💅

Si votre script renvoie une erreur du type "YAML Error: Stream does not end with newline character", c'est simple a corriger. Si vous avez defini votre YAML dans une variable, elle doit se terminer par une nouvelle ligne vide. Si vous avez donner un chemin vers votre fichier, il n'est vraisemblablement pas bon : essayez avec un chemin absolu.
Restriction: le cas specifique des guillemets doubles (") et du symbole dollar ($):

Dans le YAML, ces caracteres sont interpretes differemment. Pour les utiliser dans un contexte de chaine de caractere, vous devrez les remplacer dans le YAML par #_dbquote_# (pour ") et #_dollars_# (pour $):

. Exemple:

---
condition : $f501a eq "I want #_dbquote_##_dollars_##_dbquote_#"
create :
 f604a : "#_dbquote_#$f501a#_dbquote_# contain a #_dollars_# sign"

. resultat (avec $record->as_formatted ):

--notice d'origine--
LDR
501    _aI want "$"
--notice transformee--
LDR
501    _aI want "$"
604    _a"I want "$"" contain a $ sign

Restriction: Vous pouvez tester si un champ ou sous-champ existe, mais il est deconseille de tester son absence.
Exemple: n'hesitez pas a copier les exemples de cette documentation. Faite attention car j'ai ajoute quatre caracteres espace au debut de chaque ligne des exemples pour qu'ils soient mieux affiches par l'interpreteur POD. Si vous les copiez / collez dans votre fichier de configuration YAML, n'oubliez pas de supprimer les quatres premier caracteres de chaque ligne (par exemple avec vim, :%s/^\s\s\s\s//g ).
Ce yaml a ete appelle comme ceci: my %mth; $mth{"var"}="a string"; $record = MARC::Transform->new($record,$yaml,\%mth);

---
condition : $f501a eq "foo"
create :
 f502a : this is the value of a subfield of a new 502 field
---
condition : $f401a=~/foo/
create :
 b : new value of the 401 condition's field
 f600 :
  a :
   - first a subfield of this new 600 field
   - second a subfield of this new 600 field
   - $$mth{"var"}
  b : the 600b value
execute : \&reencodeRecordtoUtf8()
---
-
 condition : $f501a =~/foo/ and $f503a =~/bar/
 forceupdate :
  $f503b : mandatory b in condition's field
  f005_ : mandatory 005
  f006_ : \&return_record_encoding()
  f700 :
   a : the a subfield of this mandatory 700 field
   b : \&sub1("$f503a")
 forceupdatefirst :
  $f501b : update only the first b in condition's field 501
-
 condition : $f501a =~/foo/
 execute : \&warnfoo("f501a contain foo")
-
 subs : >
    sub return_record_encoding { $record->encoding(); }
    sub sub1 {my $string=shift;$string =~ s/a/e/g;return $string;}
    sub warnfoo { my $string = shift;warn $string; }
---
-
 condition : $f501b2 eq "o"
 update :
  c : updated value of all c in condition's field
  f504a : updated value of all 504a if exists
  f604 :
   b : \&LUT("$this")
   c : \&LUT("NY","cities")
 updatefirst :
  f604a : update only the first a in 604
-
 condition : $f501c eq "1"
 delete : $f501
-
 LUT :
   1 : first
   2 : second
   bar : openbar
---
delete :
 - f401a
 - f005
---
condition : $ldr2 eq "t"
execute : \&SetRecordToLowerCase($record)
---
condition : $f008_ eq "controlfield_content8b"
duplicatefield :
 - $f008 > f007
 - f402 > f602
delete : f402
---
global_subs: >
    sub reencodeRecordtoUtf8 {
        $record->encoding( 'UTF-8' );
    }
    sub warnfee {
        my $string = shift;warn $string;
    }
global_LUT:
 cities:
  NY : New York
  SF : San Fransisco
 numbers:
  1 : one
  2 : two

resultat (avec $record->as_formatted ) :

--notice d'origine--
LDR optional leader
005     controlfield_content
008     controlfield_content8a
008     controlfield_content8b
106    _aVaLuE
401    _aafooa
402  2 _aa402a2
402 1  _aa402a1
501    _c1
501    _afoo
       _afoao
       _b1
       _bbaoar
       _cbig
503    _afee
       _ababar
504    _azut
       _asisi
604    _afoo
       _afoo
       _bbar
       _ctruc

--notice transformee--
LDR optional leader
006     UTF-8
007     controlfield_content8b
008     controlfield_content8a
008     controlfield_content8b
106    _aVaLuE
401    _bnew value of the 401 condition's field
501    _c1
501    _afoo
       _afoao
       _bupdate only the first b in condition's field 501
       _bbaoar
       _cupdated value of all c in condition's field
502    _athis is the value of a subfield of a new 502 field
503    _afee
       _ababar
       _bmandatory b in condition's field
504    _aupdated value of all 504a if exists
       _aupdated value of all 504a if exists
600    _aa string
       _afirst a subfield of this new 600 field
       _asecond a subfield of this new 600 field
       _bthe 600b value
602 1  _aa402a1
602  2 _aa402a2
604    _aupdate only the first a in 604
       _afoo
       _bopenbar
       _cNew York
700    _athe a subfield of this mandatory 700 field
       _bbeber

- VOIR AUSSI 🦋

MARC::Record (<http://search.cpan.org/perldoc?MARC::Record>)
MARC::Field (<http://search.cpan.org/perldoc?MARC::Field>)
MARC::Loader (<http://search.cpan.org/perldoc?MARC::Loader>)
YAML (<http://search.cpan.org/perldoc?YAML>)
Library Of Congress MARC pages (<http://www.loc.gov/marc/>)

The definitive source for all things MARC.

- AUTEUR 💖

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

- COPYRIGHT 📜

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

and that's a wrap on the whole page, bestie!! 🫶 you read all the way through, which is main character energy fr fr 🌈✨ this whole thing was generated by perl v5.30.3 back on 2020-10-14, and the page itself is MARC::Transform(3pm) 💅 go forth and transform some records, no cap 👑💀

📦 where this page comes from

debian bookworm: libmarc-transform-perl 0.003009-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
debian trixie: libmarc-transform-perl 0.003009-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu jammy: libmarc-transform-perl 0.003009-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu noble: libmarc-transform-perl 0.003009-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu resolute: libmarc-transform-perl 0.003009-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: libmarc-transform-perl 0.003009-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

MARC::Transform(3pm)

💖 MARC::Transform 💖

🌸 NAME 🌸

🎀 VERSION 🎀

🌈 SYNOPSIS 🌈

💜 DESCRIPTION 💜

🦋 METHOD 🦋

✨ new() ✨

🌸 Optional hash reference 🌸

💅 Verbose mode 💅

🧚 Define YAML configuration file encoding 🧚

🌟 YAML 🌟

🎀 Basis 🎀

🌸 a small script to test your rules 🌸

🦋 Field's and subfield's naming convention 🦋

✨ In actions ✨

💅 In conditions 💅

🧚 Run actions only on the condition's fields 🧚

✨ Actions ✨ (the moment u've been waiting for, bestie)

🎀 create

🌸 update

🦋 updatefirst

💜 forceupdate and forceupdatefirst

🍓 delete

🧚 duplicatefield

💀 execute

🌸 Use Perl functions and LookUp Tables 🌸

💜 Variables

🦋 subs

🌈 LUT

⭐ global_LUT

💖 $$mth{"_defaultLUT_to_mth_"}

✨ Latest tips and a big YAML example's ✨

🔗 SEE ALSO

👑 AUTHOR

📜 COPYRIGHT

💖 DOCUMENTATION FRANCAISE 💖

🇫🇷 NOM

🇫🇷 VERSION

🇫🇷 SYNOPSIS

🇫🇷 DESCRIPTION

💅 new() 💅

🌸 - YAML 🌸

🎀 - Bases 🎀

🦋 - Convention de nommage des champs et des sous-champs 🦋

👑 - Actions 👑

⭐ create ⭐

✨ update ✨

✨ updatefirst ✨

✨ forceupdate et forceupdatefirst ✨

✨ delete ✨

✨ duplicatefield ✨

✨ execute ✨

- Dernieres astuces et un gros exemple de YAML 🎀✨

- VOIR AUSSI 🦋

- AUTEUR 💖

- COPYRIGHT 📜

✨ `new()` ✨

💖 `$$mth{"_defaultLUT_to_mth_"}`

💅 `new()` 💅