1YAML::PP::Schema::Perl(U3s)er Contributed Perl DocumentatYiAoMnL::PP::Schema::Perl(3)
2
3
4

NAME

6       YAML::PP::Schema::Perl - Schema for serializing perl objects and
7       special types
8

SYNOPSIS

10           use YAML::PP;
11           # This can be dangerous when loading untrusted YAML!
12           my $yp = YAML::PP->new( schema => [qw/ + Perl /] );
13           # or
14           my $yp = YAML::PP->new( schema => [qw/ Core Perl /] );
15           my $yaml = $yp->dump_string(sub { return 23 });
16
17           # loading code references
18           # This is very dangerous when loading untrusted YAML!!
19           my $yp = YAML::PP->new( schema => [qw/ + Perl +loadcode /] );
20           my $code = $yp->load_string(<<'EOM');
21           --- !perl/code |
22               {
23                   use 5.010;
24                   my ($name) = @_;
25                   say "Hello $name!";
26               }
27           EOM
28           $code->("Ingy");
29

DESCRIPTION

31       This schema allows you to load and dump perl objects and special types.
32
33       Please note that loading objects of arbitrary classes can be dangerous
34       in Perl. You have to load the modules yourself, but if an exploitable
35       module is loaded and an object is created, its "DESTROY" method will be
36       called when the object falls out of scope. File::Temp is an example
37       that can be exploitable and might remove arbitrary files.
38
39       Dumping code references is on by default, but not loading (because that
40       is easily exploitable since it's using string "eval").
41
42   Tag Styles
43       You can define the style of tags you want to support:
44
45           my $yp_perl_two_one = YAML::PP->new(
46               schema => [qw/ + Perl tags=!!perl+!perl /],
47           );
48
49       "!perl" (default)
50           Only "!perl/type" tags are supported.
51
52       "!!perl"
53           Only "!!perl/type" tags are supported.
54
55       "!perl+!!perl"
56           Both "!perl/type" and "!!perl/tag" are supported when loading. When
57           dumping, "!perl/type" is used.
58
59       "!!perl+!perl"
60           Both "!perl/type" and "!!perl/tag" are supported when loading. When
61           dumping, "!!perl/type" is used.
62
63       YAML.pm, YAML::Syck and YAML::XS are using "!!perl/type" when dumping.
64
65       YAML.pm and YAML::Syck are supporting both "!perl/type" and
66       "!!perl/type" when loading. YAML::XS currently only supports the
67       latter.
68
69   Allow only certain classes
70       Since v0.017
71
72       Blessing arbitrary objects can be dangerous.  Maybe you want to allow
73       blessing only specific classes and ignore others.  For this you have to
74       instantiate a Perl Schema object first and use the "classes" option.
75
76       Currently it only allows a list of strings:
77
78           my $perl = YAML::PP::Schema::Perl->new(
79               classes => ['Foo', 'Bar'],
80           );
81           my $yp = YAML::PP::Perl->new(
82               schema => [qw/ + /, $perl],
83           );
84
85       Allowed classes will be loaded and dumped as usual. The others will be
86       ignored.
87
88       If you want to allow no objects at all, pass an empty array ref.
89
90   EXAMPLES
91       This is a list of the currently supported types and how they are dumped
92       into YAML:
93
94       array
95                   # Code
96                   [
97                       qw/ one two three four /
98                   ]
99
100
101                   # YAML
102                   ---
103                   - one
104                   - two
105                   - three
106                   - four
107
108       array_blessed
109                   # Code
110                   bless [
111                       qw/ one two three four /
112                   ], "Just::An::Arrayref"
113
114
115                   # YAML
116                   --- !perl/array:Just::An::Arrayref
117                   - one
118                   - two
119                   - three
120                   - four
121
122       circular
123                   # Code
124                   my $circle = bless [ 1, 2 ], 'Circle';
125                   push @$circle, $circle;
126                   $circle;
127
128
129                   # YAML
130                   --- &1 !perl/array:Circle
131                   - 1
132                   - 2
133                   - *1
134
135       coderef
136                   # Code
137                   sub {
138                       my (%args) = @_;
139                       return $args{x} + $args{y};
140                   }
141
142
143                   # YAML
144                   --- !perl/code |-
145                     {
146                         use warnings;
147                         use strict;
148                         (my(%args) = @_);
149                         (return ($args{'x'} + $args{'y'}));
150                     }
151
152       coderef_blessed
153                   # Code
154                   bless sub {
155                       my (%args) = @_;
156                       return $args{x} - $args{y};
157                   }, "I::Am::Code"
158
159
160                   # YAML
161                   --- !perl/code:I::Am::Code |-
162                     {
163                         use warnings;
164                         use strict;
165                         (my(%args) = @_);
166                         (return ($args{'x'} - $args{'y'}));
167                     }
168
169       hash
170                   # Code
171                   {
172                       U => 2,
173                       B => 52,
174                   }
175
176
177                   # YAML
178                   ---
179                   B: 52
180                   U: 2
181
182       hash_blessed
183                   # Code
184                   bless {
185                       U => 2,
186                       B => 52,
187                   }, 'A::Very::Exclusive::Class'
188
189
190                   # YAML
191                   --- !perl/hash:A::Very::Exclusive::Class
192                   B: 52
193                   U: 2
194
195       refref
196                   # Code
197                   my $ref = { a => 'hash' };
198                   my $refref = \$ref;
199                   $refref;
200
201
202                   # YAML
203                   --- !perl/ref
204                   =:
205                     a: hash
206
207       refref_blessed
208                   # Code
209                   my $ref = { a => 'hash' };
210                   my $refref = bless \$ref, 'Foo';
211                   $refref;
212
213
214                   # YAML
215                   --- !perl/ref:Foo
216                   =:
217                     a: hash
218
219       regexp
220                   # Code
221                   my $string = 'unblessed';
222                   qr{$string}
223
224
225                   # YAML
226                   --- !perl/regexp unblessed
227
228       regexp_blessed
229                   # Code
230                   my $string = 'blessed';
231                   bless qr{$string}, "Foo"
232
233
234                   # YAML
235                   --- !perl/regexp:Foo blessed
236
237       scalarref
238                   # Code
239                   my $scalar = "some string";
240                   my $scalarref = \$scalar;
241                   $scalarref;
242
243
244                   # YAML
245                   --- !perl/scalar
246                   =: some string
247
248       scalarref_blessed
249                   # Code
250                   my $scalar = "some other string";
251                   my $scalarref = bless \$scalar, 'Foo';
252                   $scalarref;
253
254
255                   # YAML
256                   --- !perl/scalar:Foo
257                   =: some other string
258
259   METHODS
260       new
261               my $perl = YAML::PP::Schema::Perl->new(
262                   tags => "!perl",
263                   classes => ['MyClass'],
264                   loadcode => 1,
265               );
266
267           The constructor recognizes the following options:
268
269           tags
270               Default: '"!perl"'
271
272               See "Tag Styles"
273
274           classes
275               Default: "undef"
276
277               Since: v0.017
278
279               Accepts an array ref of class names
280
281           loadcode
282               Default: 0
283
284       register
285           A class method called by YAML::PP::Schema
286
287       construct_ref, represent_ref
288           Perl variables of the type "REF" are represented in yaml like this:
289
290               --- !perl/ref
291               =:
292                 a: 1
293
294           "construct_ref" returns the perl data:
295
296               my $data = YAML::PP::Schema::Perl->construct_ref([ '=', { some => 'data' } );
297               my $data = \{ a => 1 };
298
299           "represent_ref" turns a "REF" variable into a YAML mapping:
300
301               my $data = YAML::PP::Schema::Perl->represent_ref(\{ a => 1 });
302               my $data = { '=' => { a => 1 } };
303
304       construct_scalar, represent_scalar
305           Perl variables of the type "SCALAR" are represented in yaml like
306           this:
307
308               --- !perl/scalar
309               =: string
310
311           "construct_scalar" returns the perl data:
312
313               my $data = YAML::PP::Schema::Perl->construct_ref([ '=', 'string' );
314               my $data = \'string';
315
316           "represent_scalar" turns a "SCALAR" variable into a YAML mapping:
317
318               my $data = YAML::PP::Schema::Perl->represent_scalar(\'string');
319               my $data = { '=' => 'string' };
320
321       construct_regex, represent_regex
322           "construct_regex" returns a "qr{}" object from the YAML string:
323
324               my $qr = YAML::PP::Schema::Perl->construct_regex('foo.*');
325
326           "represent_regex" returns a string representing the regex object:
327
328               my $string = YAML::PP::Schema::Perl->represent_regex(qr{...});
329
330       evaluate_code, represent_code
331           "evaluate_code" returns a code reference from a string. The string
332           must start with a "{" and end with a "}".
333
334               my $code = YAML::PP::Schema::Perl->evaluate_code('{ return 23 }');
335
336           "represent_code" returns a string representation of the code
337           reference with the help of B::Deparse:
338
339               my $string = YAML::PP::Schema::Perl->represent_code(sub { return 23 });
340
341       construct_glob, represent_glob
342           "construct_glob" returns a glob from a hash.
343
344               my $glob = YAML::PP::Schema::Perl->construct_glob($hash);
345
346           "represent_glob" returns a hash representation of the glob.
347
348               my $hash = YAML::PP::Schema::Perl->represent_glob($glob);
349
350       object
351           Does the same as "bless":
352
353               my $object = YAML::PP::Schema::Perl->object($data, $class);
354
355
356
357perl v5.34.0                      2022-01-21         YAML::PP::Schema::Perl(3)
Impressum