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 other than smallish
138 decimal integers are left as-is as perl strings which may be upgraded
139 as needed by the caller.
141 my $parser = TOML::Tiny->new(
142 inflate_integer => sub{
150 TOML floats are 64 bit and may not match the size of the compiled perl's
151 internal float type. By default, integers are left as-is as perl strings which
152 may be upgraded as needed by the caller.
154 my $parser = TOML::Tiny->new(
155 inflate_float => sub{
163 C<TOML v5> specified homogenous arrays. This has since been removed and will no
164 longer be part of the standard as of C<v6> (as of the time of writing; the
165 author of C<TOML> has gone back and forth on the issue, so no guarantees).
167 By default, C<TOML::Tiny> is flexible and supports heterogenous arrays. If you
168 wish to require strictly typed arrays (for C<TOML>'s definition of "type",
169 anyway), C<strict_arrays> will produce an error when encountering arrays with
172 =item no_string_guessing
174 When encoding a Perl scalar it is not always clear what the TOML type
175 of the value is supposed to be. By default, C<TOML::Tiny> will, for
176 unblessed scalars, guess based on the scalar's appearance. Strings
177 that look like numbers, or like datetimes, will be encoded as such.
179 With no_string_guessing, C<TOML::Tiny> will look at the perl innards
180 to find the currently stored value type. If it is a number, the
181 scalar will be encoded as a number. If it's a string, as a string.
182 Dates and times which weren't built with DateTime come out as strings.
184 Specifying C<inflate_float>, C<inflate_integer>, and
185 C<inflate_datetime> is likely to be helpful with this option.
187 =item datetime_formatter
189 When encoding a DateTime object, by default C<TOML::Tiny> will use the
190 default formatter. This is not right for TOML which requires RFC3339.
191 If you have C<DateTime::Format::RFC3339> available, use this instead:
193 my $parser = TOML::Tiny->new(
194 datetime_formatter => DateTime::Format::RFC3339->new(),
201 Decodes C<TOML> and returns a hash ref. Dies on parse error.
205 Encodes a perl hash ref as a C<TOML>-formatted string. Dies when encountering
206 an array of mixed types if C<strict_arrays> was set.
210 Alias for C<decode> to provide compatibility with C<TOML::Parser> when
211 overriding the parser by setting C<$TOML::Parser>.
213 =head1 DIFFERENCES FROM L<TOML> AND L<TOML::Parser>
215 C<TOML::Tiny> differs in a few significant ways from the L<TOML> module,
216 particularly in adding support for newer C<TOML> features and strictness.
218 L<TOML> defaults to lax parsing and provides C<strict_mode> to (slightly)
219 tighten things up. C<TOML::Tiny> defaults to (somehwat) stricter parsing, with
220 the exception of permitting heterogenous arrays (illegal in v4 and v5, but
221 permissible in the upcoming v6); optional enforcement of homogenous arrays is
222 supported with C<strict_arrays>.
224 C<TOML::Tiny> supports a number of options which do not exist in L<TOML>:
225 L</inflate_integer>, L</inflate_float>, and L</strict_arrays>.
227 C<TOML::Tiny> ignores invalid surrogate pairs within basic and multiline
228 strings (L<TOML> may attempt to decode an invalid pair). Additionally, only
229 those character escapes officially supported by TOML are interpreted as such by
232 C<TOML::Tiny> supports stripping initial whitespace and handles lines
233 terminating with a backslash correctly in multilne strings:
246 {x => 'foo', y => 'how now brown bureaucrat.'}
248 C<TOML::Tiny> includes support for integers specified in binary, octal or hex
249 as well as the special float values C<inf> and C<nan>.
255 =item L<TOML::Tiny::Grammar>
257 Regexp scraps used by C<TOML::Tiny> to parse TOML source.
261 =head1 ACKNOWLEDGEMENTS
263 Thanks to L<ZipRecruiter|https://www.ziprecruiter.com> for encouraging their
264 employees to contribute back to the open source ecosystem. Without their
265 dedication to quality software development this distribution would not exist.
269 Jeff Ober <sysread@fastmail.fm>
271 =head1 COPYRIGHT AND LICENSE
273 This software is copyright (c) 2020 by Jeff Ober.
275 This is free software; you can redistribute it and/or modify it under
276 the same terms as the Perl 5 programming language system itself.