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

GOTCHAS

Big integers and floats

"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] );
    };
  );
    

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

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

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) = @_;
      # 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 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, "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;
    };
  );
    

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_arrays

"TOML v0.5" specified homogenous arrays. This has since been removed and will no longer be part of the standard as of "v1.0" (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 "decode" to provide compatibility with "TOML::Parser" when overriding the parser by setting $TOML::Parser.