TOML::Tiny(3pm)

📦
version 0.22 · 6 versions
, in ubuntu stonking

✨ TOML::Tiny ✨

okay bestie, pull up a chair, because we're about to talk about TOML::Tiny — yes, that's the Perl module name (it's filed under TOML::Tiny(3pm) in the manual, iykyk) 💅 — and it is genuinely a minimal, pure perl TOML parser and serializer. no cap.

🌸 VERSION

version 0.22 — that's the one we're talking about, periodt.

🦋 SYNOPSIS

here's the whole vibe in one code block, go nuts:

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);

like… yes. decode, encode, both APIs, all of it right there 💖

🌈 DESCRIPTION

TOML::Tiny is a pure-perl parser and generator for the TOML data format — here, take the link: <https://github.com/toml-lang/toml>. it conforms to TOML v1.0 (with a few caveats, bestie, see "strict" below, don't @ me).

the whole point is that TOML::Tiny strives to maintain an interface compatible to the TOML and TOML::Parser modules, and it could even be used to override $TOML::Parser like the absolute icon it is:

use TOML;
use TOML::Tiny;

local $TOML::Parser = TOML::Tiny->new(...);
say to_toml(...);

so yes, you can just. swap it in. slay 🫶

🎀 EXPORTS

TOML::Tiny exports the following two functions, for compatibility with the TOML module. check "FUNCTIONS" in TOML if you want the origin story.

💫 from_toml

parses a string of TOML-formatted source and gives you back the resulting data structure. any arguments after the first get passed along to TOML::Tiny::Parser's constructor.

if there's a syntax error in the TOML source, from_toml will die with an explanation, and that explanation includes the line number of the error. iconic of it honestly:

my $result = eval{ from_toml($toml_string) };

OR — and this is the good part — you can call it in list context, and then syntax errors come back as two values instead: undef and an error message. no dying, just vibes:

my ($result, $error) = from_toml($toml_string);

additional arguments may be passed after the toml source string; see "new".

🙈 GOTCHAS

Big integers and floats — TOML supports integers and floats larger than what many perls support. when TOML::Tiny runs into a value it may not be able to represent as a number, it will instead return a Math::BigInt or Math::BigFloat. you can override this behaviour by providing inflation routines:

my $toml = TOML::Tiny->new(
  inflate_float => sub{
    return do_something_else_with_floats( $_[0] );
  };
);

crisis averted 💅

⭐ to_toml

encodes a hash ref as a TOML-formatted string:

my $toml = to_toml({foo => {'bar' => 'bat'}});

# [foo]
# bar="bat"

🍓 mapping perl to TOML types

table

  • HASH ref

array

  • ARRAY ref

boolean

  • "\0" or "\1"
  • JSON::PP::Boolean
  • Types::Serializer::Boolean

numeric types

these are tricky in perl, ngl. when encountering a Math::Big[Int|Float], that representation is used.

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:

number => 0 + $number,
string => "" . $string,
  • Math::BigInt
  • Math::BigFloat
  • numerical scalars

datetime

  • RFC3339-formatted string — e.g., "1985-04-12T23:20:50.52Z"
  • DateTime — 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.

string

  • all other non-ref scalars are treated as strings.

👑 OBJECT API

🧚 new

inflate_datetime — by default, TOML::Tiny treats TOML datetimes as strings in the generated data structure. the inflate_datetime parameter lets you hand over a routine to intercept those as they're generated:

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);
  },
);

inflate_boolean — by default, boolean values in a TOML document result in a 1 or 0. if Types::Serialiser is installed, they'll instead be Types::Serialiser::true or Types::Serialiser::false.

wanna override? 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';
    }
  },
);

inflate_integer — 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. override it with an inflation routine:

my $parser = TOML::Tiny->new(
  inflate_integer => sub{
    my $parsed = shift;
    return sprintf 'the number "%d"', $parsed;
  };
);

inflate_float — 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:

my $parser = TOML::Tiny->new(
  inflate_float => sub{
    my $parsed = shift;
    return sprintf '"%0.8f" is a float', $parsed;
  };
);

strict — "strict" imposes some miscellaneous strictures on TOML input, like disallowing trailing commas in inline tables and failing on invalid UTF8 input.

🚨 ok important note bestie: "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. so don't come for me about it 💀

🌟 decode

decodes TOML and returns a hash ref. dies on parse error. no negotiation.

💜 encode

encodes a perl hash ref as a TOML-formatted string.

🌙 parse

alias for "decode", so it stays compatible with TOML::Parser when you're overriding the parser by setting $TOML::Parser. team player behaviour fr fr.

🔥 DIFFERENCES FROM TOML AND TOML::Parser

TOML::Tiny differs in a few significant ways from the TOML module, especially in that it adds support for newer TOML features and strictness. glow up.

  • TOML defaults to lax parsing and provides "strict_mode" to (slightly) tighten things up. TOML::Tiny defaults to (somewhat) stricter parsing, enabling some extra strictures with "strict".
  • 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". the range?? unmatched 💅

🫶 SEE ALSO

TOML::Tiny::Grammar Regexp scraps used by TOML::Tiny to parse TOML source. the little helper doing the heavy lifting, we love her.

🌸 ACKNOWLEDGEMENTS

thanks to ZipRecruiter <https://www.ziprecruiter.com> for encouraging their employees to contribute back to the open source ecosystem. without their dedication to quality software development this distribution would not exist. genuinely so real of them 🥹

a big thank you to those who have contributed code or bug reports:

you all ate. no crumbs. 👑

✨ AUTHOR

Jeff Ober <sysread@fastmail.fm>

this software is copyright (c) 2026 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.

and that's the whole page bestie 💖 this was TOML::Tiny as documented for perl v5.40.1, dated 2026-06-13 — go forth, parse some TOML, and remember: strict mode is your friend 🌟

📦 where this page comes from