1YAML::PP::Schema::Perl(U3s)er Contributed Perl DocumentatYiAoMnL::PP::Schema::Perl(3)
2
6 YAML::PP::Schema::Perl - Schema for serializing perl objects and
7 special types
8
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 # 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
31 This schema allows you to load and dump perl objects and special types.
32 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 Dumping code references is on by default, but not loading (because that
40 is easily exploitable since it's using string "eval").
41 Tag Styles
43 You can define the style of tags you want to support:
44 my $yp_perl_two_one = YAML::PP->new(
46 schema => [qw/ + Perl tags=!!perl+!perl /],
47 );
48 "!perl" (default)
50 Only "!perl/type" tags are supported.
51 "!!perl"
53 Only "!!perl/type" tags are supported.
54 "!perl+!!perl"
56 Both "!perl/type" and "!!perl/tag" are supported when loading. When
57 dumping, "!perl/type" is used.
58 "!!perl+!perl"
60 Both "!perl/type" and "!!perl/tag" are supported when loading. When
61 dumping, "!!perl/type" is used.
62 YAML.pm, YAML::Syck and YAML::XS are using "!!perl/type" when dumping.
64 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 Allow only certain classes
70 Since v0.017
71 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 Currently it only allows a list of strings:
77 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 Allowed classes will be loaded and dumped as usual. The others will be
86 ignored.
87 If you want to allow no objects at all, pass an empty array ref.
89 EXAMPLES
91 This is a list of the currently supported types and how they are dumped
92 into YAML:
93 array
95 # Code
96 [
97 qw/ one two three four /
98 ]
99 # YAML
102 ---
103 - one
104 - two
105 - three
106 - four
107 array_blessed
109 # Code
110 bless [
111 qw/ one two three four /
112 ], "Just::An::Arrayref"
113 # YAML
116 --- !perl/array:Just::An::Arrayref
117 - one
118 - two
119 - three
120 - four
121 circular
123 # Code
124 my $circle = bless [ 1, 2 ], 'Circle';
125 push @$circle, $circle;
126 $circle;
127 # YAML
130 --- &1 !perl/array:Circle
131 - 1
132 - 2
133 - *1
134 coderef
136 # Code
137 sub {
138 my (%args) = @_;
139 return $args{x} + $args{y};
140 }
141 # YAML
144 --- !perl/code |-
145 {
146 use warnings;
147 use strict;
148 (my(%args) = @_);
149 (return ($args{'x'} + $args{'y'}));
150 }
151 coderef_blessed
153 # Code
154 bless sub {
155 my (%args) = @_;
156 return $args{x} - $args{y};
157 }, "I::Am::Code"
158 # 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 hash
170 # Code
171 {
172 U => 2,
173 B => 52,
174 }
175 # YAML
178 ---
179 B: 52
180 U: 2
181 hash_blessed
183 # Code
184 bless {
185 U => 2,
186 B => 52,
187 }, 'A::Very::Exclusive::Class'
188 # YAML
191 --- !perl/hash:A::Very::Exclusive::Class
192 B: 52
193 U: 2
194 refref
196 # Code
197 my $ref = { a => 'hash' };
198 my $refref = \$ref;
199 $refref;
200 # YAML
203 --- !perl/ref
204 =:
205 a: hash
206 refref_blessed
208 # Code
209 my $ref = { a => 'hash' };
210 my $refref = bless \$ref, 'Foo';
211 $refref;
212 # YAML
215 --- !perl/ref:Foo
216 =:
217 a: hash
218 regexp
220 # Code
221 my $string = 'unblessed';
222 qr{$string}
223 # YAML
226 --- !perl/regexp unblessed
227 regexp_blessed
229 # Code
230 my $string = 'blessed';
231 bless qr{$string}, "Foo"
232 # YAML
235 --- !perl/regexp:Foo blessed
236 scalarref
238 # Code
239 my $scalar = "some string";
240 my $scalarref = \$scalar;
241 $scalarref;
242 # YAML
245 --- !perl/scalar
246 =: some string
247 scalarref_blessed
249 # Code
250 my $scalar = "some other string";
251 my $scalarref = bless \$scalar, 'Foo';
252 $scalarref;
253 # YAML
256 --- !perl/scalar:Foo
257 =: some other string
258 METHODS
260 new
261 my $perl = YAML::PP::Schema::Perl->new(
262 tags => "!perl",
263 classes => ['MyClass'],
264 loadcode => 1,
265 );
266 The constructor recognizes the following options:
268 tags
270 Default: '"!perl"'
271 See "Tag Styles"
273 classes
275 Default: "undef"
276 Since: v0.017
278 Accepts an array ref of class names
280 loadcode
282 Default: 0
283 register
285 A class method called by YAML::PP::Schema
286 construct_ref, represent_ref
288 Perl variables of the type "REF" are represented in yaml like this:
289 --- !perl/ref
291 =:
292 a: 1
293 "construct_ref" returns the perl data:
295 my $data = YAML::PP::Schema::Perl->construct_ref([ '=', { some => 'data' } );
297 my $data = \{ a => 1 };
298 "represent_ref" turns a "REF" variable into a YAML mapping:
300 my $data = YAML::PP::Schema::Perl->represent_ref(\{ a => 1 });
302 my $data = { '=' => { a => 1 } };
303 construct_scalar, represent_scalar
305 Perl variables of the type "SCALAR" are represented in yaml like
306 this:
307 --- !perl/scalar
309 =: string
310 "construct_scalar" returns the perl data:
312 my $data = YAML::PP::Schema::Perl->construct_ref([ '=', 'string' );
314 my $data = \'string';
315 "represent_scalar" turns a "SCALAR" variable into a YAML mapping:
317 my $data = YAML::PP::Schema::Perl->represent_scalar(\'string');
319 my $data = { '=' => 'string' };
320 construct_regex, represent_regex
322 "construct_regex" returns a "qr{}" object from the YAML string:
323 my $qr = YAML::PP::Schema::Perl->construct_regex('foo.*');
325 "represent_regex" returns a string representing the regex object:
327 my $string = YAML::PP::Schema::Perl->represent_regex(qr{...});
329 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 my $code = YAML::PP::Schema::Perl->evaluate_code('{ return 23 }');
335 "represent_code" returns a string representation of the code
337 reference with the help of B::Deparse:
338 my $string = YAML::PP::Schema::Perl->represent_code(sub { return 23 });
340 construct_glob, represent_glob
342 "construct_glob" returns a glob from a hash.
343 my $glob = YAML::PP::Schema::Perl->construct_glob($hash);
345 "represent_glob" returns a hash representation of the glob.
347 my $hash = YAML::PP::Schema::Perl->represent_glob($glob);
349 object
351 Does the same as "bless":
352 my $object = YAML::PP::Schema::Perl->object($data, $class);
354perl v5.34.0 2022-01-21 YAML::PP::Schema::Perl(3)