.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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::Perl 3pm"
.TH YAML::PP::Schema::Perl 3pm "2020-09-11" "perl v5.30.3" "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::Perl \- Schema for serializing perl objects and special types
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&    use YAML::PP;
\&    # This can be dangerous when loading untrusted YAML!
\&    my $yp = YAML::PP\->new( schema => [qw/ + Perl /] );
\&    # or
\&    my $yp = YAML::PP\->new( schema => [qw/ Core Perl /] );
\&    my $yaml = $yp\->dump_string(sub { return 23 });
\&
\&    # loading code references
\&    # This is very dangerous when loading untrusted YAML!!
\&    my $yp = YAML::PP\->new( schema => [qw/ + Perl +loadcode /] );
\&    my $code = $yp\->load_string(<<\*(AqEOM\*(Aq);
\&    \-\-\- !perl/code |
\&        {
\&            use 5.010;
\&            my ($name) = @_;
\&            say "Hello $name!";
\&        }
\&    EOM
\&    $code\->("Ingy");
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This schema allows you to load and dump perl objects and special types.
.PP
Please note that loading objects of arbitrary classes can be dangerous
in Perl. You have to load the modules yourself, but if an exploitable module
is loaded and an object is created, its \f(CW\*(C`DESTROY\*(C'\fR method will be called
when the object falls out of scope. File::Temp is an example that can
be exploitable and might remove arbitrary files.
.PP
Dumping code references is on by default, but not loading (because that is
easily exploitable since it's using string \f(CW\*(C`eval\*(C'\fR).
.SS "Tag Styles"
.IX Subsection "Tag Styles"
You can define the style of tags you want to support:
.PP
.Vb 3
\&    my $yp_perl_two_one = YAML::PP\->new(
\&        schema => [qw/ + Perl tags=!!perl+!perl /],
\&    );
.Ve
.ie n .IP """!perl"" (default)" 4
.el .IP "\f(CW!perl\fR (default)" 4
.IX Item "!perl (default)"
Only \f(CW\*(C`!perl/type\*(C'\fR tags are supported.
.ie n .IP """!!perl""" 4
.el .IP "\f(CW!!perl\fR" 4
.IX Item "!!perl"
Only \f(CW\*(C`!!perl/type\*(C'\fR tags are supported.
.ie n .IP """!perl+!!perl""" 4
.el .IP "\f(CW!perl+!!perl\fR" 4
.IX Item "!perl+!!perl"
Both \f(CW\*(C`!perl/type\*(C'\fR and \f(CW\*(C`!!perl/tag\*(C'\fR are supported when loading. When dumping,
\&\f(CW\*(C`!perl/type\*(C'\fR is used.
.ie n .IP """!!perl+!perl""" 4
.el .IP "\f(CW!!perl+!perl\fR" 4
.IX Item "!!perl+!perl"
Both \f(CW\*(C`!perl/type\*(C'\fR and \f(CW\*(C`!!perl/tag\*(C'\fR are supported when loading. When dumping,
\&\f(CW\*(C`!!perl/type\*(C'\fR is used.
.PP
\&\s-1YAML\s0.pm, YAML::Syck and \s-1YAML::XS\s0 are using \f(CW\*(C`!!perl/type\*(C'\fR when dumping.
.PP
\&\s-1YAML\s0.pm and YAML::Syck are supporting both \f(CW\*(C`!perl/type\*(C'\fR and
\&\f(CW\*(C`!!perl/type\*(C'\fR when loading. \s-1YAML::XS\s0 currently only supports the latter.
.SS "Allow only certain classes"
.IX Subsection "Allow only certain classes"
Since v0.017
.PP
Blessing arbitrary objects can be dangerous.  Maybe you want to allow blessing
only specific classes and ignore others.  For this you have to instantiate
a Perl Schema object first and use the \f(CW\*(C`classes\*(C'\fR option.
.PP
Currently it only allows a list of strings:
.PP
.Vb 6
\&    my $perl = YAML::PP::Schema::Perl\->new(
\&        classes => [\*(AqFoo\*(Aq, \*(AqBar\*(Aq],
\&    );
\&    my $yp = YAML::PP::Perl\->new(
\&        schema => [qw/ + /, $perl],
\&    );
.Ve
.PP
Allowed classes will be loaded and dumped as usual. The others will be ignored.
.PP
If you want to allow no objects at all, pass an empty array ref.
.SS "\s-1EXAMPLES\s0"
.IX Subsection "EXAMPLES"
This is a list of the currently supported types and how they are dumped into
\&\s-1YAML:\s0
.IP "array" 4
.IX Item "array"
.Vb 4
\&        # Code
\&        [
\&            qw/ one two three four /
\&        ]
\&
\&
\&        # YAML
\&        \-\-\-
\&        \- one
\&        \- two
\&        \- three
\&        \- four
.Ve
.IP "array_blessed" 4
.IX Item "array_blessed"
.Vb 4
\&        # Code
\&        bless [
\&            qw/ one two three four /
\&        ], "Just::An::Arrayref"
\&
\&
\&        # YAML
\&        \-\-\- !perl/array:Just::An::Arrayref
\&        \- one
\&        \- two
\&        \- three
\&        \- four
.Ve
.IP "circular" 4
.IX Item "circular"
.Vb 4
\&        # Code
\&        my $circle = bless [ 1, 2 ], \*(AqCircle\*(Aq;
\&        push @$circle, $circle;
\&        $circle;
\&
\&
\&        # YAML
\&        \-\-\- &1 !perl/array:Circle
\&        \- 1
\&        \- 2
\&        \- *1
.Ve
.IP "coderef" 4
.IX Item "coderef"
.Vb 5
\&        # Code
\&        sub {
\&            my (%args) = @_;
\&            return $args{x} + $args{y};
\&        }
\&
\&
\&        # YAML
\&        \-\-\- !perl/code |\-
\&          {
\&              use warnings;
\&              use strict;
\&              (my(%args) = @_);
\&              (return ($args{\*(Aqx\*(Aq} + $args{\*(Aqy\*(Aq}));
\&          }
.Ve
.IP "coderef_blessed" 4
.IX Item "coderef_blessed"
.Vb 5
\&        # Code
\&        bless sub {
\&            my (%args) = @_;
\&            return $args{x} \- $args{y};
\&        }, "I::Am::Code"
\&
\&
\&        # YAML
\&        \-\-\- !perl/code:I::Am::Code |\-
\&          {
\&              use warnings;
\&              use strict;
\&              (my(%args) = @_);
\&              (return ($args{\*(Aqx\*(Aq} \- $args{\*(Aqy\*(Aq}));
\&          }
.Ve
.IP "hash" 4
.IX Item "hash"
.Vb 5
\&        # Code
\&        {
\&            U => 2,
\&            B => 52,
\&        }
\&
\&
\&        # YAML
\&        \-\-\-
\&        B: 52
\&        U: 2
.Ve
.IP "hash_blessed" 4
.IX Item "hash_blessed"
.Vb 5
\&        # Code
\&        bless {
\&            U => 2,
\&            B => 52,
\&        }, \*(AqA::Very::Exclusive::Class\*(Aq
\&
\&
\&        # YAML
\&        \-\-\- !perl/hash:A::Very::Exclusive::Class
\&        B: 52
\&        U: 2
.Ve
.IP "refref" 4
.IX Item "refref"
.Vb 4
\&        # Code
\&        my $ref = { a => \*(Aqhash\*(Aq };
\&        my $refref = \e$ref;
\&        $refref;
\&
\&
\&        # YAML
\&        \-\-\- !perl/ref
\&        =:
\&          a: hash
.Ve
.IP "refref_blessed" 4
.IX Item "refref_blessed"
.Vb 4
\&        # Code
\&        my $ref = { a => \*(Aqhash\*(Aq };
\&        my $refref = bless \e$ref, \*(AqFoo\*(Aq;
\&        $refref;
\&
\&
\&        # YAML
\&        \-\-\- !perl/ref:Foo
\&        =:
\&          a: hash
.Ve
.IP "regexp" 4
.IX Item "regexp"
.Vb 3
\&        # Code
\&        my $string = \*(Aqunblessed\*(Aq;
\&        qr{$string}
\&
\&
\&        # YAML
\&        \-\-\- !perl/regexp unblessed
.Ve
.IP "regexp_blessed" 4
.IX Item "regexp_blessed"
.Vb 3
\&        # Code
\&        my $string = \*(Aqblessed\*(Aq;
\&        bless qr{$string}, "Foo"
\&
\&
\&        # YAML
\&        \-\-\- !perl/regexp:Foo blessed
.Ve
.IP "scalarref" 4
.IX Item "scalarref"
.Vb 4
\&        # Code
\&        my $scalar = "some string";
\&        my $scalarref = \e$scalar;
\&        $scalarref;
\&
\&
\&        # YAML
\&        \-\-\- !perl/scalar
\&        =: some string
.Ve
.IP "scalarref_blessed" 4
.IX Item "scalarref_blessed"
.Vb 4
\&        # Code
\&        my $scalar = "some other string";
\&        my $scalarref = bless \e$scalar, \*(AqFoo\*(Aq;
\&        $scalarref;
\&
\&
\&        # YAML
\&        \-\-\- !perl/scalar:Foo
\&        =: some other string
.Ve
.SS "\s-1METHODS\s0"
.IX Subsection "METHODS"
.IP "new" 4
.IX Item "new"
.Vb 5
\&    my $perl = YAML::PP::Schema::Perl\->new(
\&        tags => "!perl",
\&        classes => [\*(AqMyClass\*(Aq],
\&        loadcode => 1,
\&    );
.Ve
.Sp
The constructor recognizes the following options:
.RS 4
.IP "tags" 4
.IX Item "tags"
Default: '\f(CW\*(C`!perl\*(C'\fR'
.Sp
See \*(L"Tag Styles\*(R"
.IP "classes" 4
.IX Item "classes"
Default: \f(CW\*(C`undef\*(C'\fR
.Sp
Since: v0.017
.Sp
Accepts an array ref of class names
.IP "loadcode" 4
.IX Item "loadcode"
Default: 0
.RE
.RS 4
.RE
.IP "register" 4
.IX Item "register"
A class method called by YAML::PP::Schema
.IP "construct_ref, represent_ref" 4
.IX Item "construct_ref, represent_ref"
Perl variables of the type \f(CW\*(C`REF\*(C'\fR are represented in yaml like this:
.Sp
.Vb 3
\&    \-\-\- !perl/ref
\&    =:
\&      a: 1
.Ve
.Sp
\&\f(CW\*(C`construct_ref\*(C'\fR returns the perl data:
.Sp
.Vb 2
\&    my $data = YAML::PP::Schema::Perl\->construct_ref([ \*(Aq=\*(Aq, { some => \*(Aqdata\*(Aq } );
\&    my $data = \e{ a => 1 };
.Ve
.Sp
\&\f(CW\*(C`represent_ref\*(C'\fR turns a \f(CW\*(C`REF\*(C'\fR variable into a \s-1YAML\s0 mapping:
.Sp
.Vb 2
\&    my $data = YAML::PP::Schema::Perl\->represent_ref(\e{ a => 1 });
\&    my $data = { \*(Aq=\*(Aq => { a => 1 } };
.Ve
.IP "construct_scalar, represent_scalar" 4
.IX Item "construct_scalar, represent_scalar"
Perl variables of the type \f(CW\*(C`SCALAR\*(C'\fR are represented in yaml like this:
.Sp
.Vb 2
\&    \-\-\- !perl/scalar
\&    =: string
.Ve
.Sp
\&\f(CW\*(C`construct_scalar\*(C'\fR returns the perl data:
.Sp
.Vb 2
\&    my $data = YAML::PP::Schema::Perl\->construct_ref([ \*(Aq=\*(Aq, \*(Aqstring\*(Aq );
\&    my $data = \e\*(Aqstring\*(Aq;
.Ve
.Sp
\&\f(CW\*(C`represent_scalar\*(C'\fR turns a \f(CW\*(C`SCALAR\*(C'\fR variable into a \s-1YAML\s0 mapping:
.Sp
.Vb 2
\&    my $data = YAML::PP::Schema::Perl\->represent_scalar(\e\*(Aqstring\*(Aq);
\&    my $data = { \*(Aq=\*(Aq => \*(Aqstring\*(Aq };
.Ve
.IP "construct_regex, represent_regex" 4
.IX Item "construct_regex, represent_regex"
\&\f(CW\*(C`construct_regex\*(C'\fR returns a \f(CW\*(C`qr{}\*(C'\fR object from the \s-1YAML\s0 string:
.Sp
.Vb 1
\&    my $qr = YAML::PP::Schema::Perl\->construct_regex(\*(Aqfoo.*\*(Aq);
.Ve
.Sp
\&\f(CW\*(C`represent_regex\*(C'\fR returns a string representing the regex object:
.Sp
.Vb 1
\&    my $string = YAML::PP::Schema::Perl\->represent_regex(qr{...});
.Ve
.IP "evaluate_code, represent_code" 4
.IX Item "evaluate_code, represent_code"
\&\f(CW\*(C`evaluate_code\*(C'\fR returns a code reference from a string. The string must
start with a \f(CW\*(C`{\*(C'\fR and end with a \f(CW\*(C`}\*(C'\fR.
.Sp
.Vb 1
\&    my $code = YAML::PP::Schema::Perl\->evaluate_code(\*(Aq{ return 23 }\*(Aq);
.Ve
.Sp
\&\f(CW\*(C`represent_code\*(C'\fR returns a string representation of the code reference
with the help of B::Deparse:
.Sp
.Vb 1
\&    my $string = YAML::PP::Schema::Perl\->represent_code(sub { return 23 });
.Ve
.IP "construct_glob, represent_glob" 4
.IX Item "construct_glob, represent_glob"
\&\f(CW\*(C`construct_glob\*(C'\fR returns a glob from a hash.
.Sp
.Vb 1
\&    my $glob = YAML::PP::Schema::Perl\->construct_glob($hash);
.Ve
.Sp
\&\f(CW\*(C`represent_glob\*(C'\fR returns a hash representation of the glob.
.Sp
.Vb 1
\&    my $hash = YAML::PP::Schema::Perl\->represent_glob($glob);
.Ve
.IP "object" 4
.IX Item "object"
Does the same as \f(CW\*(C`bless\*(C'\fR:
.Sp
.Vb 1
\&    my $object = YAML::PP::Schema::Perl\->object($data, $class);
.Ve