.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "YAML::PP::Schema::Merge 3"
.TH YAML::PP::Schema::Merge 3 2024-02-14 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
YAML::PP::Schema::Merge \- Enabling YAML merge keys for mappings
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&    use YAML::PP;
\&    my $yp = YAML::PP\->new( schema => [qw/ + Merge /] );
\&
\&    my $yaml = <<\*(AqEOM\*(Aq;
\&    \-\-\-
\&    \- &CENTER { x: 1, y: 2 }
\&    \- &LEFT { x: 0, y: 2 }
\&    \- &BIG { r: 10 }
\&    \- &SMALL { r: 1 }
\&
\&    # All the following maps are equal:
\&
\&    \- # Explicit keys
\&      x: 1
\&      y: 2
\&      r: 10
\&      label: center/big
\&
\&    \- # Merge one map
\&      << : *CENTER
\&      r: 10
\&      label: center/big
\&
\&    \- # Merge multiple maps
\&      << : [ *CENTER, *BIG ]
\&      label: center/big
\&
\&    \- # Override
\&      << : [ *BIG, *LEFT, *SMALL ]
\&      x: 1
\&      label: center/big
\&    EOM
\&    my $data = $yp\->load_string($yaml);
\&    # $data\->[4] == $data\->[5] == $data\->[6] == $data\->[7]
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
See <https://yaml.org/type/merge.html> for the specification.
.PP
Quote:
.PP
"Specify one or more mappings to be merged with the current one.
.PP
The \f(CW\*(C`<<\*(C'\fR merge key is used to indicate that all the keys of one or more
specified maps should be inserted into the current map. If the value associated
with the key is a single mapping node, each of its key/value pairs is inserted
into the current mapping, unless the key already exists in it. If the value
associated with the merge key is a sequence, then this sequence is expected to
contain mapping nodes and each of these nodes is merged in turn according to its
order in the sequence. Keys in mapping nodes earlier in the sequence override
keys specified in later mapping nodes."
.PP
The implementation of this in a generic way is not trivial, because we also
have to handle duplicate keys, and YAML::PP allows you to write your own
handler for processing mappings.
.PP
So the inner API of that is not stable at this point.
.PP
Note that if you enable this schema, a plain scalar `<<` will be seen as
special anywhere in your document, so if you want a literal `<<`, you have
to put it in quotes.
.PP
Note that the performed merge is not a "deep merge". Only top-level keys are
merged.
.SH METHODS
.IX Header "METHODS"
.IP register 4
.IX Item "register"
Called by YAML::PP::Schema