/ 
TOML-Tiny-0.04
River stage one • 2 direct dependents • 2 total dependents
/ TOML::Tiny

NAME

TOML::Tiny - a minimal, pure perl TOML parser and serializer

VERSION

version 0.04

SYNOPSIS

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

DESCRIPTION

TOML::Tiny implements a pure-perl parser and generator for the TOML data format. It conforms to TOML v5 (with a few caveats; see "strict_arrays") with support for more recent changes in pursuit of v6.

TOML::Tiny strives to maintain an interface compatible to the TOML and TOML::Parser modules, and could even be used to override $TOML::Parser:

use TOML;
use TOML::Tiny;

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

EXPORTS

TOML::Tiny exports the following to functions for compatibility with the TOML module. See "FUNCTIONS" in TOML.

from_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.

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.

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.

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

Homogenous array strictures are enabled by passing strict_arrays:

# Croaks
my $result = from_toml(q{mixed=[1, 2, "three"]})

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

to_toml

Encodes a hash ref as a TOML-formatted string.

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

# [foo]
# bar="bat"

Homogenous array strictures are enabled by passing strict_arrays:

# Croaks
my $toml = to_toml({mixed => [1, 2, "three"]}, strict_arrays => 1);

OBJECT API

new

inflate_datetime

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:

use DateTime::Format::RFC3339;

my $parser = TOML::Tiny->new(
  inflate_datetime => sub{
    my $dt_string = shift;
    return DateTime::Format::RFC3339->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 will instead be Types::Serialiser::true or 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';
    }
  },
);
inflate_integer

TOML integers are 64 bit and may not match the size of the compiled perl's internal integer type. By default, integers are left as-is as perl strings which may be upgraded as needed by the caller.

my $parser = TOML::Tiny->new(
  inflate_integer => sub{
    use bignum;
    return 0 + shift;
  }
);
inflate_float

TOML floats are 64 bit and may not match the size of the compiled perl's internal float type. By default, integers are left as-is as perl strings which may be upgraded as needed by the caller.

my $parser = TOML::Tiny->new(
  inflate_float => sub{
    use bignum;
    return 0 + shift;
  }
);
strict_arrays

TOML v5 specified homogenous arrays. This has since been removed and will no longer be part of the standard as of v6 (as of the time of writing; the author of TOML has gone back and forth on the issue, so no guarantees).

By default, TOML::Tiny is flexible and supports heterogenous arrays. If you wish to require strictly typed arrays (for TOML's definition of "type", anyway), strict_arrays will produce an error when encountering arrays with heterogenous types.

decode

Decodes TOML and returns a hash ref. Dies on parse error.

encode

Encodes a perl hash ref as a TOML-formatted string. Dies when encountering an array of mixed types if strict_arrays was set.

parse

Alias for encode to provide compatibility with TOML::Parser when overriding the parser by setting $TOML::Parser.

DIFFERENCES FROM TOML AND 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, with the exception of permitting heterogenous arrays (illegal in v4 and v5, but permissible in the upcoming v6); optional enforcement of homogenous arrays is supported with strict_arrays.

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.

ACKNOWLEDGEMENTS

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.

AUTHOR

Jeff Ober <sysread@fastmail.fm>

COPYRIGHT AND LICENSE

This software is copyright (c) 2020 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.