.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "TOML::Tiny 3pm" .TH TOML::Tiny 3pm "2021-09-19" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" TOML::Tiny \- a minimal, pure perl TOML parser and serializer .SH "VERSION" .IX Header "VERSION" version 0.15 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use TOML::Tiny qw(from_toml to_toml); \& \& binmode STDIN, \*(Aq:encoding(UTF\-8)\*(Aq; \& binmode STDOUT, \*(Aq:encoding(UTF\-8)\*(Aq; \& \& # Decoding TOML \& my $toml = do{ local $/; }; \& my ($parsed, $error) = from_toml $toml; \& \& # Encoding TOML \& say to_toml({ \& stuff => { \& about => [\*(Aqother\*(Aq, \*(Aqstuff\*(Aq], \& }, \& }); \& \& # Object API \& my $parser = TOML::Tiny\->new; \& my $data = $parser\->decode($toml); \& say $parser\->encode($data); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\f(CW\*(C`TOML::Tiny\*(C'\fR implements a pure-perl parser and generator for the \&\s-1TOML\s0 data format. It conforms to \s-1TOML\s0 v1.0 (with a few caveats; see \*(L"strict\*(R"). .PP \&\f(CW\*(C`TOML::Tiny\*(C'\fR strives to maintain an interface compatible to the \s-1TOML\s0 and TOML::Parser modules, and could even be used to override \f(CW$TOML::Parser\fR: .PP .Vb 2 \& use TOML; \& use TOML::Tiny; \& \& local $TOML::Parser = TOML::Tiny\->new(...); \& say to_toml(...); .Ve .SH "EXPORTS" .IX Header "EXPORTS" \&\f(CW\*(C`TOML::Tiny\*(C'\fR exports the following to functions for compatibility with the \&\s-1TOML\s0 module. See \*(L"\s-1FUNCTIONS\*(R"\s0 in \s-1TOML\s0. .SS "from_toml" .IX Subsection "from_toml" Parses a string of \f(CW\*(C`TOML\*(C'\fR\-formatted source and returns the resulting data structure. Any arguments after the first are passed to TOML::Tiny::Parser's constructor. .PP If there is a syntax error in the \f(CW\*(C`TOML\*(C'\fR source, \f(CW\*(C`from_toml\*(C'\fR will die with an explanation which includes the line number of the error. .PP .Vb 1 \& my $result = eval{ from_toml($toml_string) }; .Ve .PP Alternately, this routine may be called in list context, in which case syntax errors will result in returning two values, \f(CW\*(C`undef\*(C'\fR and an error message. .PP .Vb 1 \& my ($result, $error) = from_toml($toml_string); .Ve .PP Additional arguments may be passed after the toml source string; see \*(L"new\*(R". .PP \fI\s-1GOTCHAS\s0\fR .IX Subsection "GOTCHAS" .IP "Big integers and floats" 4 .IX Item "Big integers and floats" \&\f(CW\*(C`TOML\*(C'\fR supports integers and floats larger than what many perls support. When \&\f(CW\*(C`TOML::Tiny\*(C'\fR 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: .Sp .Vb 5 \& my $toml = TOML::Tiny\->new( \& inflate_float => sub{ \& return do_something_else_with_floats( $_[0] ); \& }; \& ); .Ve .SS "to_toml" .IX Subsection "to_toml" Encodes a hash ref as a \f(CW\*(C`TOML\*(C'\fR\-formatted string. .PP .Vb 1 \& my $toml = to_toml({foo => {\*(Aqbar\*(Aq => \*(Aqbat\*(Aq}}); \& \& # [foo] \& # bar="bat" .Ve .PP \fImapping perl to \s-1TOML\s0 types\fR .IX Subsection "mapping perl to TOML types" .PP table .IX Subsection "table" .ie n .IP """HASH"" ref" 4 .el .IP "\f(CWHASH\fR ref" 4 .IX Item "HASH ref" .PP array .IX Subsection "array" .ie n .IP """ARRAY"" ref" 4 .el .IP "\f(CWARRAY\fR ref" 4 .IX Item "ARRAY ref" .PP boolean .IX Subsection "boolean" .ie n .IP """\e0"" or ""\e1""" 4 .el .IP "\f(CW\e0\fR or \f(CW\e1\fR" 4 .IX Item "0 or 1" .PD 0 .IP "JSON::PP::Boolean" 4 .IX Item "JSON::PP::Boolean" .IP "Types::Serializer::Boolean" 4 .IX Item "Types::Serializer::Boolean" .PD .PP numeric types .IX Subsection "numeric types" .PP These are tricky in perl. When encountering a \f(CW\*(C`Math::Big[Int|Float]\*(C'\fR, that representation is used. .PP If the value is a defined (non-ref) scalar with the \f(CW\*(C`SVf_IOK\*(C'\fR or \f(CW\*(C`SVf_NOK\*(C'\fR 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: .PP .Vb 2 \& number => 0 + $number, \& string => "" . $string, .Ve .IP "Math::BigInt" 4 .IX Item "Math::BigInt" .PD 0 .IP "Math::BigFloat" 4 .IX Item "Math::BigFloat" .IP "numerical scalars" 4 .IX Item "numerical scalars" .PD .PP datetime .IX Subsection "datetime" .IP "RFC3339\-formatted string" 4 .IX Item "RFC3339-formatted string" e.g., \f(CW"1985\-04\-12T23:20:50.52Z"\fR .IP "DateTime" 4 .IX Item "DateTime" DateTimes are formatted as \f(CW\*(C`RFC3339\*(C'\fR, as expected by \f(CW\*(C`TOML\*(C'\fR. However, \&\f(CW\*(C`TOML\*(C'\fR supports the concept of a \*(L"local\*(R" time zone, which strays from \&\f(CW\*(C`RFC3339\*(C'\fR by allowing a datetime without a time zone offset. This is represented in perl by a \f(CW\*(C`DateTime\*(C'\fR with a \fBfloating time zone\fR. .PP string .IX Subsection "string" .PP All other non-ref scalars are treated as strings. .SH "OBJECT API" .IX Header "OBJECT API" .SS "new" .IX Subsection "new" .IP "inflate_datetime" 4 .IX Item "inflate_datetime" By default, \f(CW\*(C`TOML::Tiny\*(C'\fR treats \s-1TOML\s0 datetimes as strings in the generated data structure. The \f(CW\*(C`inflate_datetime\*(C'\fR parameter allows the caller to provide a routine to intercept those as they are generated: .Sp .Vb 1 \& use DateTime::Format::RFC3339; \& \& my $parser = TOML::Tiny\->new( \& inflate_datetime => sub{ \& my ($dt_string) = @_; \& # DateTime::Format::RFC3339 will set the resulting DateTime\*(Aqs 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); \& }, \& ); .Ve .IP "inflate_boolean" 4 .IX Item "inflate_boolean" By default, boolean values in a \f(CW\*(C`TOML\*(C'\fR document result in a \f(CW1\fR or \f(CW0\fR. If Types::Serialiser is installed, they will instead be \f(CW\*(C`Types::Serialiser::true\*(C'\fR or \f(CW\*(C`Types::Serialiser::false\*(C'\fR. .Sp If you wish to override this, you can provide your own routine to generate values: .Sp .Vb 10 \& my $parser = TOML::Tiny\->new( \& inflate_boolean => sub{ \& my $bool = shift; \& if ($bool eq \*(Aqtrue\*(Aq) { \& return \*(AqThe Truth\*(Aq; \& } else { \& return \*(AqA Lie\*(Aq; \& } \& }, \& ); .Ve .IP "inflate_integer" 4 .IX Item "inflate_integer" \&\s-1TOML\s0 integers are 64 bit and may not match the size of the compiled perl's internal integer type. By default, \f(CW\*(C`TOML::Tiny\*(C'\fR coerces numbers that fit within a perl number by adding \f(CW0\fR. For bignums, a Math::BigInt is returned. This may be overridden by providing an inflation routine: .Sp .Vb 6 \& my $parser = TOML::Tiny\->new( \& inflate_integer => sub{ \& my $parsed = shift; \& return sprintf \*(Aqthe number "%d"\*(Aq, $parsed; \& }; \& ); .Ve .IP "inflate_float" 4 .IX Item "inflate_float" \&\s-1TOML\s0 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 \f(CW\*(C`NaN\*(C'\fR and \&\f(CW\*(C`inf\*(C'\fR may also be returned. You can override this by specifying an inflation routine. .Sp .Vb 6 \& my $parser = TOML::Tiny\->new( \& inflate_float => sub{ \& my $parsed = shift; \& return sprintf \*(Aq"%0.8f" is a float\*(Aq, $parsed; \& }; \& ); .Ve .IP "strict" 4 .IX Item "strict" \&\f(CW\*(C`strict\*(C'\fR imposes some miscellaneous strictures on \f(CW\*(C`TOML\*(C'\fR input, such as disallowing trailing commas in inline tables and failing on invalid \s-1UTF8\s0 input. .Sp \&\fBNote:\fR \f(CW\*(C`strict\*(C'\fR was previously called \f(CW\*(C`strict_arrays\*(C'\fR. Both are accepted for backward compatibility, although enforcement of homogenous arrays is no longer supported as it has been dropped from the spec. .SS "decode" .IX Subsection "decode" Decodes \f(CW\*(C`TOML\*(C'\fR and returns a hash ref. Dies on parse error. .SS "encode" .IX Subsection "encode" Encodes a perl hash ref as a \f(CW\*(C`TOML\*(C'\fR\-formatted string. .SS "parse" .IX Subsection "parse" Alias for \f(CW\*(C`decode\*(C'\fR to provide compatibility with \f(CW\*(C`TOML::Parser\*(C'\fR when overriding the parser by setting \f(CW$TOML::Parser\fR. .SH "DIFFERENCES FROM TOML AND TOML::Parser" .IX Header "DIFFERENCES FROM TOML AND TOML::Parser" \&\f(CW\*(C`TOML::Tiny\*(C'\fR differs in a few significant ways from the \s-1TOML\s0 module, particularly in adding support for newer \f(CW\*(C`TOML\*(C'\fR features and strictness. .PP \&\s-1TOML\s0 defaults to lax parsing and provides \f(CW\*(C`strict_mode\*(C'\fR to (slightly) tighten things up. \f(CW\*(C`TOML::Tiny\*(C'\fR defaults to (somehwat) stricter parsing, enabling some extra strictures with \*(L"strict\*(R". .PP \&\f(CW\*(C`TOML::Tiny\*(C'\fR supports a number of options which do not exist in \s-1TOML\s0: \&\*(L"inflate_integer\*(R", \*(L"inflate_float\*(R", and \*(L"strict\*(R". .PP \&\f(CW\*(C`TOML::Tiny\*(C'\fR ignores invalid surrogate pairs within basic and multiline strings (\s-1TOML\s0 may attempt to decode an invalid pair). Additionally, only those character escapes officially supported by \s-1TOML\s0 are interpreted as such by \&\f(CW\*(C`TOML::Tiny\*(C'\fR. .PP \&\f(CW\*(C`TOML::Tiny\*(C'\fR supports stripping initial whitespace and handles lines terminating with a backslash correctly in multilne strings: .PP .Vb 3 \& # TOML input \& x=""" \& foo""" \& \& y="""\e \& how now \e \& brown \e \& bureaucrat.\e \& """ \& \& # Perl output \& {x => \*(Aqfoo\*(Aq, y => \*(Aqhow now brown bureaucrat.\*(Aq} .Ve .PP \&\f(CW\*(C`TOML::Tiny\*(C'\fR includes support for integers specified in binary, octal or hex as well as the special float values \f(CW\*(C`inf\*(C'\fR and \f(CW\*(C`nan\*(C'\fR. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "TOML::Tiny::Grammar" 4 .IX Item "TOML::Tiny::Grammar" Regexp scraps used by \f(CW\*(C`TOML::Tiny\*(C'\fR to parse \s-1TOML\s0 source. .SH "ACKNOWLEDGEMENTS" .IX Header "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. .PP A big thank you to those who have contributed code or bug reports: .IP "ijackson " 4 .IX Item "ijackson " .PD 0 .IP "noctux " 4 .IX Item "noctux " .IP "oschwald " 4 .IX Item "oschwald " .IP "jjatria " 4 .IX Item "jjatria " .PD .SH "AUTHOR" .IX Header "AUTHOR" Jeff Ober .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2021 by Jeff Ober. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.