7 TOML::Tiny - a minimal, pure perl TOML parser and serializer
15 use TOML::Tiny qw(from_toml to_toml);
17 binmode STDIN, ':encoding(UTF-8)';
18 binmode STDOUT, ':encoding(UTF-8)';
21 my $toml = do{ local $/; <STDIN> };
22 my ($parsed, $error) = from_toml $toml;
27 about => ['other', 'stuff'],
32 my $parser = TOML::Tiny->new;
33 my $data = $parser->decode($toml);
34 say $parser->encode($data);
38 C<TOML::Tiny> implements a pure-perl parser and generator for the
39 L<TOML|https://github.com/toml-lang/toml> data format. It conforms to TOML v5
40 (with a few caveats; see L</strict_arrays>) with support for more recent
41 changes in pursuit of v6.
43 C<TOML::Tiny> strives to maintain an interface compatible to the L<TOML> and
44 L<TOML::Parser> modules, and could even be used to override C<$TOML::Parser>:
49 local $TOML::Parser = TOML::Tiny->new(...);
54 C<TOML::Tiny> exports the following to functions for compatibility with the
55 L<TOML> module. See L<TOML/FUNCTIONS>.
59 Parses a string of C<TOML>-formatted source and returns the resulting data
60 structure. Any arguments after the first are passed to L<TOML::Tiny::Parser>'s
63 If there is a syntax error in the C<TOML> source, C<from_toml> will die with
64 an explanation which includes the line number of the error.
66 my $result = eval{ from_toml($toml_string) };
68 Alternately, this routine may be called in list context, in which case syntax
69 errors will result in returning two values, C<undef> and an error message.
71 my ($result, $error) = from_toml($toml_string);
73 Homogenous array strictures are enabled by passing C<strict_arrays>:
76 my $result = from_toml(q{mixed=[1, 2, "three"]})
78 Additional arguments may be passed after the toml source string; see L</new>.
82 Encodes a hash ref as a C<TOML>-formatted string.
84 my $toml = to_toml({foo => {'bar' => 'bat'}});
89 Homogenous array strictures are enabled by passing C<strict_arrays>:
92 my $toml = to_toml({mixed => [1, 2, "three"]}, strict_arrays => 1);
100 =item inflate_datetime
102 By default, C<TOML::Tiny> treats TOML datetimes as strings in the generated
103 data structure. The C<inflate_datetime> parameter allows the caller to provide
104 a routine to intercept those as they are generated:
106 use DateTime::Format::RFC3339;
108 my $parser = TOML::Tiny->new(
109 inflate_datetime => sub{
110 my $dt_string = shift;
111 return DateTime::Format::RFC3339->parse_datetime($dt_string);
115 =item inflate_boolean
117 By default, boolean values in a C<TOML> document result in a C<1> or C<0>.
118 If L<Types::Serialiser> is installed, they will instead be C<Types::Serialiser::true>
119 or C<Types::Serialiser::false>.
121 If you wish to override this, you can provide your own routine to generate values:
123 my $parser = TOML::Tiny->new(
124 inflate_boolean => sub{
126 if ($bool eq 'true') {
134 =item inflate_integer
136 TOML integers are 64 bit and may not match the size of the compiled perl's
137 internal integer type. By default, integers are left as-is as perl strings
138 which may be upgraded as needed by the caller.
140 my $parser = TOML::Tiny->new(
141 inflate_integer => sub{
149 TOML floats are 64 bit and may not match the size of the compiled perl's
150 internal float type. By default, integers are left as-is as perl strings which
151 may be upgraded as needed by the caller.
153 my $parser = TOML::Tiny->new(
154 inflate_float => sub{
162 C<TOML v5> specified homogenous arrays. This has since been removed and will no
163 longer be part of the standard as of C<v6> (as of the time of writing; the
164 author of C<TOML> has gone back and forth on the issue, so no guarantees).
166 By default, C<TOML::Tiny> is flexible and supports heterogenous arrays. If you
167 wish to require strictly typed arrays (for C<TOML>'s definition of "type",
168 anyway), C<strict_arrays> will produce an error when encountering arrays with
175 Decodes C<TOML> and returns a hash ref. Dies on parse error.
179 Encodes a perl hash ref as a C<TOML>-formatted string. Dies when encountering
180 an array of mixed types if C<strict_arrays> was set.
184 Alias for C<encode> to provide compatibility with C<TOML::Parser> when
185 overriding the parser by setting C<$TOML::Parser>.
187 =head1 DIFFERENCES FROM L<TOML> AND L<TOML::Parser>
189 C<TOML::Tiny> differs in a few significant ways from the L<TOML> module,
190 particularly in adding support for newer C<TOML> features and strictness.
192 L<TOML> defaults to lax parsing and provides C<strict_mode> to (slightly)
193 tighten things up. C<TOML::Tiny> defaults to (somehwat) stricter parsing, with
194 the exception of permitting heterogenous arrays (illegal in v4 and v5, but
195 permissible in the upcoming v6); optional enforcement of homogenous arrays is
196 supported with C<strict_arrays>.
198 C<TOML::Tiny> ignores invalid surrogate pairs within basic and multiline
199 strings (L<TOML> may attempt to decode an invalid pair). Additionally, only
200 those character escapes officially supported by TOML are interpreted as such by
203 C<TOML::Tiny> supports stripping initial whitespace and handles lines
204 terminating with a backslash correctly in multilne strings:
217 {x => 'foo', y => 'how now brown bureaucrat.'}
219 C<TOML::Tiny> includes support for integers specified in binary, octal or hex
220 as well as the special float values C<inf> and C<nan>.
222 =head1 ACKNOWLEDGEMENTS
224 Thanks to L<ZipRecruiter|https://www.ziprecruiter.com> for encouraging their
225 employees to contribute back to the open source ecosystem. Without their
226 dedication to quality software development this distribution would not exist.
230 Jeff Ober <sysread@fastmail.fm>
232 =head1 COPYRIGHT AND LICENSE
234 This software is copyright (c) 2020 by Jeff Ober.
236 This is free software; you can redistribute it and/or modify it under
237 the same terms as the Perl 5 programming language system itself.