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 dumpcode => 1,
266 );
267 The constructor recognizes the following options:
269 tags
271 Default: '"!perl"'
272 See "Tag Styles"
274 classes
276 Default: "undef"
277 Since: v0.017
279 Accepts an array ref of class names
281 loadcode
283 Default: 0
284 dumpcode
286 Default: 1
287 my $yp = YAML::PP->new( schema => [qw/ + Perl -dumpcode /] );
289 register
291 A class method called by YAML::PP::Schema
292 construct_ref, represent_ref
294 Perl variables of the type "REF" are represented in yaml like this:
295 --- !perl/ref
297 =:
298 a: 1
299 "construct_ref" returns the perl data:
301 my $data = YAML::PP::Schema::Perl->construct_ref([ '=', { some => 'data' } );
303 my $data = \{ a => 1 };
304 "represent_ref" turns a "REF" variable into a YAML mapping:
306 my $data = YAML::PP::Schema::Perl->represent_ref(\{ a => 1 });
308 my $data = { '=' => { a => 1 } };
309 construct_scalar, represent_scalar
311 Perl variables of the type "SCALAR" are represented in yaml like
312 this:
313 --- !perl/scalar
315 =: string
316 "construct_scalar" returns the perl data:
318 my $data = YAML::PP::Schema::Perl->construct_ref([ '=', 'string' );
320 my $data = \'string';
321 "represent_scalar" turns a "SCALAR" variable into a YAML mapping:
323 my $data = YAML::PP::Schema::Perl->represent_scalar(\'string');
325 my $data = { '=' => 'string' };
326 construct_regex, represent_regex
328 "construct_regex" returns a "qr{}" object from the YAML string:
329 my $qr = YAML::PP::Schema::Perl->construct_regex('foo.*');
331 "represent_regex" returns a string representing the regex object:
333 my $string = YAML::PP::Schema::Perl->represent_regex(qr{...});
335 evaluate_code, represent_code
337 "evaluate_code" returns a code reference from a string. The string
338 must start with a "{" and end with a "}".
339 my $code = YAML::PP::Schema::Perl->evaluate_code('{ return 23 }');
341 "represent_code" returns a string representation of the code
343 reference with the help of B::Deparse:
344 my $string = YAML::PP::Schema::Perl->represent_code(sub { return 23 });
346 construct_glob, represent_glob
348 "construct_glob" returns a glob from a hash.
349 my $glob = YAML::PP::Schema::Perl->construct_glob($hash);
351 "represent_glob" returns a hash representation of the glob.
353 my $hash = YAML::PP::Schema::Perl->represent_glob($glob);
355 object
357 Does the same as "bless":
358 my $object = YAML::PP::Schema::Perl->object($data, $class);
360perl v5.38.0 2023-07-21 YAML::PP::Schema::Perl(3)