README.pod

   1 =pod
   2
   3 =encoding UTF-8
   4
   5 =head1 NAME
   6
   7 TOML::Tiny - a minimal, pure perl TOML parser and serializer
   8
   9 =head1 VERSION
  10
  11 version 0.02
  12
  13 =head1 SYNOPSIS
  14
  15   use TOML::Tiny qw(from_toml to_toml);
  16
  17   binmode STDIN,  ':encoding(UTF-8)';
  18   binmode STDOUT, ':encoding(UTF-8)';
  19
  20   # Decoding TOML
  21   my $toml = do{ local $/; <STDIN> };
  22   my ($parsed, $error) = from_toml $toml;
  23
  24   # Encoding TOML
  25   say to_toml({
  26     stuff => {
  27       about => ['other', 'stuff'],
  28     },
  29   });
  30
  31   # Object API
  32   my $parser = TOML::Tiny->new;
  33   my $data = $parser->decode($toml);
  34   say $parser->encode($data);
  35
  36 =head1 DESCRIPTION
  37
  38 C<TOML::Tiny> implements a pure-perl parser and generator for the
  39 L<TOML|https://github.com/toml-lang/toml> data format. It conforms to TOML v5
  40 (with a few caveats; see L</strict_arrays>) with support for more recent
  41 changes in pursuit of v6.
  42
  43 C<TOML::Tiny> strives to maintain an interface compatible to the L<TOML> and
  44 L<TOML::Parser> modules, and could even be used to override C<$TOML::Parser>:
  45
  46   use TOML;
  47   use TOML::Tiny;
  48
  49   local $TOML::Parser = TOML::Tiny->new(...);
  50   say to_toml(...);
  51
  52 =head1 EXPORTS
  53
  54 C<TOML::Tiny> exports the following to functions for compatibility with the
  55 L<TOML> module. See L<TOML/FUNCTIONS>.
  56
  57 =head2 from_toml
  58
  59 Parses a string of C<TOML>-formatted source and returns the resulting data
  60 structure. Any arguments after the first are passed to L<TOML::Tiny::Parser>'s
  61 constructor.
  62
  63 If there is a syntax error in the C<TOML> source, C<from_toml> will die with
  64 an explanation which includes the line number of the error.
  65
  66   my $result = eval{ from_toml($toml_string) };
  67
  68 Alternately, this routine may be called in list context, in which case syntax
  69 errors will result in returning two values, C<undef> and an error message.
  70
  71   my ($result, $error) = from_toml($toml_string);
  72
  73 Homogenous array strictures are enabled by passing C<strict_arrays>:
  74
  75   # Croaks
  76   my $result = from_toml(q{mixed=[1, 2, "three"]})
  77
  78 Additional arguments may be passed after the toml source string; see L</new>.
  79
  80 =head2 to_toml
  81
  82 Encodes a hash ref as a C<TOML>-formatted string.
  83
  84   my $toml = to_toml({foo => {'bar' => 'bat'}});
  85
  86   # [foo]
  87   # bar="bat"
  88
  89 Homogenous array strictures are enabled by passing C<strict_arrays>:
  90
  91   # Croaks
  92   my $toml = to_toml({mixed => [1, 2, "three"]}, strict_arrays => 1);
  93
  94 =head1 OBJECT API
  95
  96 =head2 new
  97
  98 =over
  99
 100 =item inflate_datetime
 101
 102 By default, C<TOML::Tiny> treats TOML datetimes as strings in the generated
 103 data structure. The C<inflate_datetime> parameter allows the caller to provide
 104 a routine to intercept those as they are generated:
 105
 106   use DateTime::Format::RFC3339;
 107
 108   my $parser = TOML::Tiny->new(
 109     inflate_datetime => sub{
 110       my $dt_string = shift;
 111       return DateTime::Format::RFC3339->parse_datetime($dt_string);
 112     },
 113   );
 114
 115 =item inflate_boolean
 116
 117 By default, boolean values in a C<TOML> document result in a C<1> or C<0>.
 118 If L<Types::Serialiser> is installed, they will instead be C<Types::Serialiser::true>
 119 or C<Types::Serialiser::false>.
 120
 121 If you wish to override this, you can provide your own routine to generate values:
 122
 123   my $parser = TOML::Tiny->new(
 124     inflate_boolean => sub{
 125       my $bool = shift;
 126       if ($bool eq 'true') {
 127         return 'The Truth';
 128       } else {
 129         return 'A Lie';
 130       }
 131     },
 132   );
 133
 134 =item strict_arrays
 135
 136 C<TOML v5> specified homogenous arrays. This has since been removed and will no
 137 longer be part of the standard as of C<v6> (as of the time of writing; the
 138 author of C<TOML> has gone back and forth on the issue, so no guarantees).
 139
 140 By default, C<TOML::Tiny> is flexible and supports heterogenous arrays. If you
 141 wish to require strictly typed arrays (for C<TOML>'s definition of "type",
 142 anyway), C<strict_arrays> will produce an error when encountering arrays with
 143 heterogenous types.
 144
 145 =back
 146
 147 =head2 decode
 148
 149 Decodes C<TOML> and returns a hash ref. Dies on parse error.
 150
 151 =head2 encode
 152
 153 Encodes a perl hash ref as a C<TOML>-formatted string. Dies when encountering
 154 an array of mixed types if C<strict_arrays> was set.
 155
 156 =head2 parse
 157
 158 Alias for C<encode> to provide compatibility with C<TOML::Parser> when
 159 overriding the parser by setting C<$TOML::Parser>.
 160
 161 =head1 DIFFERENCES FROM L<TOML> AND L<TOML::Parser>
 162
 163 C<TOML::Tiny> differs in a few significant ways from the L<TOML> module,
 164 particularly in adding support for newer C<TOML> features and strictness.
 165
 166 L<TOML> defaults to lax parsing and provides C<strict_mode> to (slightly)
 167 tighten things up. C<TOML::Tiny> defaults to (somehwat) stricter parsing, with
 168 the exception of permitting heterogenous arrays (illegal in v4 and v5, but
 169 permissible in the upcoming v6); optional enforcement of homogenous arrays is
 170 supported with C<strict_arrays>.
 171
 172 C<TOML::Tiny> ignores invalid surrogate pairs within basic and multiline
 173 strings (L<TOML> may attempt to decode an invalid pair). Additionally, only
 174 those character escapes officially supported by TOML are interpreted as such by
 175 C<TOML::Tiny>.
 176
 177 C<TOML::Tiny> supports stripping initial whitespace and handles lines
 178 terminating with a backslash correctly in multilne strings:
 179
 180   # TOML input
 181   x="""
 182   foo"""
 183
 184   y="""\
 185      how now \
 186        brown \
 187   bureaucrat.\
 188   """
 189
 190   # Perl output
 191   {x => 'foo', y => 'how now brown bureaucrat.'}
 192
 193 C<TOML::Tiny> includes support for integers specified in binary, octal or hex
 194 as well as the special float values C<inf> and C<nan>.
 195
 196 =head1 ACKNOWLEDGEMENTS
 197
 198 Thanks to L<ZipRecruiter|https://www.ziprecruiter.com> for encouraging their
 199 employees to contribute back to the open source ecosystem. Without their
 200 dedication to quality software development this distribution would not exist.
 201
 202 =head1 AUTHOR
 203
 204 Jeff Ober <sysread@fastmail.fm>
 205
 206 =head1 COPYRIGHT AND LICENSE
 207
 208 This software is copyright (c) 2020 by Jeff Ober.
 209
 210 This is free software; you can redistribute it and/or modify it under
 211 the same terms as the Perl 5 programming language system itself.
 212
 213 =cut