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