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.06
  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 inflate_integer
 135
 136 TOML integers are 64 bit and may not match the size of the compiled perl's
 137 internal integer type. By default, integers are left as-is as perl strings
 138 which may be upgraded as needed by the caller.
 139
 140   my $parser = TOML::Tiny->new(
 141     inflate_integer => sub{
 142       use bignum;
 143       return 0 + shift;
 144     }
 145   );
 146
 147 =item inflate_float
 148
 149 TOML floats are 64 bit and may not match the size of the compiled perl's
 150 internal float type. By default, integers are left as-is as perl strings which
 151 may be upgraded as needed by the caller.
 152
 153   my $parser = TOML::Tiny->new(
 154     inflate_float => sub{
 155       use bignum;
 156       return 0 + shift;
 157     }
 158   );
 159
 160 =item strict_arrays
 161
 162 C<TOML v5> specified homogenous arrays. This has since been removed and will no
 163 longer be part of the standard as of C<v6> (as of the time of writing; the
 164 author of C<TOML> has gone back and forth on the issue, so no guarantees).
 165
 166 By default, C<TOML::Tiny> is flexible and supports heterogenous arrays. If you
 167 wish to require strictly typed arrays (for C<TOML>'s definition of "type",
 168 anyway), C<strict_arrays> will produce an error when encountering arrays with
 169 heterogenous types.
 170
 171 =back
 172
 173 =head2 decode
 174
 175 Decodes C<TOML> and returns a hash ref. Dies on parse error.
 176
 177 =head2 encode
 178
 179 Encodes a perl hash ref as a C<TOML>-formatted string. Dies when encountering
 180 an array of mixed types if C<strict_arrays> was set.
 181
 182 =head2 parse
 183
 184 Alias for C<decode> to provide compatibility with C<TOML::Parser> when
 185 overriding the parser by setting C<$TOML::Parser>.
 186
 187 =head1 DIFFERENCES FROM L<TOML> AND L<TOML::Parser>
 188
 189 C<TOML::Tiny> differs in a few significant ways from the L<TOML> module,
 190 particularly in adding support for newer C<TOML> features and strictness.
 191
 192 L<TOML> defaults to lax parsing and provides C<strict_mode> to (slightly)
 193 tighten things up. C<TOML::Tiny> defaults to (somehwat) stricter parsing, with
 194 the exception of permitting heterogenous arrays (illegal in v4 and v5, but
 195 permissible in the upcoming v6); optional enforcement of homogenous arrays is
 196 supported with C<strict_arrays>.
 197
 198 C<TOML::Tiny> supports a number of options which do not exist in L<TOML>:
 199 L</inflate_integer>, L</inflate_float>, and L</strict_arrays>.
 200
 201 C<TOML::Tiny> ignores invalid surrogate pairs within basic and multiline
 202 strings (L<TOML> may attempt to decode an invalid pair). Additionally, only
 203 those character escapes officially supported by TOML are interpreted as such by
 204 C<TOML::Tiny>.
 205
 206 C<TOML::Tiny> supports stripping initial whitespace and handles lines
 207 terminating with a backslash correctly in multilne strings:
 208
 209   # TOML input
 210   x="""
 211   foo"""
 212
 213   y="""\
 214      how now \
 215        brown \
 216   bureaucrat.\
 217   """
 218
 219   # Perl output
 220   {x => 'foo', y => 'how now brown bureaucrat.'}
 221
 222 C<TOML::Tiny> includes support for integers specified in binary, octal or hex
 223 as well as the special float values C<inf> and C<nan>.
 224
 225 =head1 SEE ALSO
 226
 227 =over
 228
 229 =item L<TOML::Tiny::Grammar>
 230
 231 Regexp scraps used by C<TOML::Tiny> to parse TOML source.
 232
 233 =back
 234
 235 =head1 ACKNOWLEDGEMENTS
 236
 237 Thanks to L<ZipRecruiter|https://www.ziprecruiter.com> for encouraging their
 238 employees to contribute back to the open source ecosystem. Without their
 239 dedication to quality software development this distribution would not exist.
 240
 241 =head1 AUTHOR
 242
 243 Jeff Ober <sysread@fastmail.fm>
 244
 245 =head1 COPYRIGHT AND LICENSE
 246
 247 This software is copyright (c) 2020 by Jeff Ober.
 248
 249 This is free software; you can redistribute it and/or modify it under
 250 the same terms as the Perl 5 programming language system itself.
 251
 252 =cut