TOML::Tiny - a minimal, pure perl TOML parser and serializer
version 0.15
use TOML::Tiny qw(from_toml to_toml); binmode STDIN, ':encoding(UTF-8)'; binmode STDOUT, ':encoding(UTF-8)'; # Decoding TOML my $toml = do{ local $/; <STDIN> }; my ($parsed, $error) = from_toml $toml; # Encoding TOML say to_toml({ stuff => { about => ['other', 'stuff'], }, }); # Object API my $parser = TOML::Tiny->new; my $data = $parser->decode($toml); say $parser->encode($data);
TOML::Tiny implements a pure-perl parser and generator for the TOML data format. It conforms to TOML v1.0 (with a few caveats; see "strict").
TOML::Tiny
TOML::Tiny strives to maintain an interface compatible to the TOML and TOML::Parser modules, and could even be used to override $TOML::Parser:
$TOML::Parser
use TOML; use TOML::Tiny; local $TOML::Parser = TOML::Tiny->new(...); say to_toml(...);
TOML::Tiny exports the following to functions for compatibility with the TOML module. See "FUNCTIONS" in TOML.
Parses a string of TOML-formatted source and returns the resulting data structure. Any arguments after the first are passed to TOML::Tiny::Parser's constructor.
TOML
If there is a syntax error in the TOML source, from_toml will die with an explanation which includes the line number of the error.
from_toml
my $result = eval{ from_toml($toml_string) };
Alternately, this routine may be called in list context, in which case syntax errors will result in returning two values, undef and an error message.
undef
my ($result, $error) = from_toml($toml_string);
Additional arguments may be passed after the toml source string; see "new".
TOML supports integers and floats larger than what many perls support. When TOML::Tiny encounters a value it may not be able to represent as a number, it will instead return a Math::BigInt or Math::BigFloat. This behavior can be overridden by providing inflation routines:
my $toml = TOML::Tiny->new( inflate_float => sub{ return do_something_else_with_floats( $_[0] ); }; );
Encodes a hash ref as a TOML-formatted string.
my $toml = to_toml({foo => {'bar' => 'bat'}}); # [foo] # bar="bat"
HASH
ARRAY
\0
\1
These are tricky in perl. When encountering a Math::Big[Int|Float], that representation is used.
Math::Big[Int|Float]
If the value is a defined (non-ref) scalar with the SVf_IOK or SVf_NOK flags set, the value will be emitted unchanged. This is in line with most other packages, so the normal hinting hacks for typed output apply:
SVf_IOK
SVf_NOK
number => 0 + $number, string => "" . $string,
e.g., "1985-04-12T23:20:50.52Z"
"1985-04-12T23:20:50.52Z"
DateTimes are formatted as RFC3339, as expected by TOML. However, TOML supports the concept of a "local" time zone, which strays from RFC3339 by allowing a datetime without a time zone offset. This is represented in perl by a DateTime with a floating time zone.
RFC3339
DateTime
All other non-ref scalars are treated as strings.
By default, TOML::Tiny treats TOML datetimes as strings in the generated data structure. The inflate_datetime parameter allows the caller to provide a routine to intercept those as they are generated:
inflate_datetime
use DateTime::Format::RFC3339; my $parser = TOML::Tiny->new( inflate_datetime => sub{ my ($dt_string) = @_; # DateTime::Format::RFC3339 will set the resulting DateTime's formatter # to itself. Fallback is the DateTime default, ISO8601, with a possibly # floating time zone. return eval{ DateTime::Format::RFC3339->parse_datetime($dt_string) } || DateTime::Format::ISO8601->parse_datetime($dt_string); }, );
By default, boolean values in a TOML document result in a 1 or 0. If Types::Serialiser is installed, they will instead be Types::Serialiser::true or Types::Serialiser::false.
1
0
Types::Serialiser::true
Types::Serialiser::false
If you wish to override this, you can provide your own routine to generate values:
my $parser = TOML::Tiny->new( inflate_boolean => sub{ my $bool = shift; if ($bool eq 'true') { return 'The Truth'; } else { return 'A Lie'; } }, );
TOML integers are 64 bit and may not match the size of the compiled perl's internal integer type. By default, TOML::Tiny coerces numbers that fit within a perl number by adding 0. For bignums, a Math::BigInt is returned. This may be overridden by providing an inflation routine:
my $parser = TOML::Tiny->new( inflate_integer => sub{ my $parsed = shift; return sprintf 'the number "%d"', $parsed; }; );
TOML floats are 64 bit and may not match the size of the compiled perl's internal float type. As with integers, floats are coerced to numbers and large floats are upgraded to Math::BigFloats. The special strings NaN and inf may also be returned. You can override this by specifying an inflation routine.
NaN
inf
my $parser = TOML::Tiny->new( inflate_float => sub{ my $parsed = shift; return sprintf '"%0.8f" is a float', $parsed; }; );
strict imposes some miscellaneous strictures on TOML input, such as disallowing trailing commas in inline tables and failing on invalid UTF8 input.
strict
Note: strict was previously called strict_arrays. Both are accepted for backward compatibility, although enforcement of homogenous arrays is no longer supported as it has been dropped from the spec.
strict_arrays
Decodes TOML and returns a hash ref. Dies on parse error.
Encodes a perl hash ref as a TOML-formatted string.
Alias for decode to provide compatibility with TOML::Parser when overriding the parser by setting $TOML::Parser.
decode
TOML::Parser
TOML::Tiny differs in a few significant ways from the TOML module, particularly in adding support for newer TOML features and strictness.
TOML defaults to lax parsing and provides strict_mode to (slightly) tighten things up. TOML::Tiny defaults to (somehwat) stricter parsing, enabling some extra strictures with "strict".
strict_mode
TOML::Tiny supports a number of options which do not exist in TOML: "inflate_integer", "inflate_float", and "strict".
TOML::Tiny ignores invalid surrogate pairs within basic and multiline strings (TOML may attempt to decode an invalid pair). Additionally, only those character escapes officially supported by TOML are interpreted as such by TOML::Tiny.
TOML::Tiny supports stripping initial whitespace and handles lines terminating with a backslash correctly in multilne strings:
# TOML input x=""" foo""" y="""\ how now \ brown \ bureaucrat.\ """ # Perl output {x => 'foo', y => 'how now brown bureaucrat.'}
TOML::Tiny includes support for integers specified in binary, octal or hex as well as the special float values inf and nan.
nan
Regexp scraps used by TOML::Tiny to parse TOML source.
Thanks to ZipRecruiter for encouraging their employees to contribute back to the open source ecosystem. Without their dedication to quality software development this distribution would not exist.
A big thank you to those who have contributed code or bug reports:
Jeff Ober <sysread@fastmail.fm>
This software is copyright (c) 2021 by Jeff Ober.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install TOML::Tiny, copy and paste the appropriate command in to your terminal.
cpanm
cpanm TOML::Tiny
CPAN shell
perl -MCPAN -e shell install TOML::Tiny
For more information on module installation, please visit the detailed CPAN module installation guide.