/ 
Data-Smile-XS-0.001000
/ Data::Smile::XS

NAME

Data::Smile::XS - XS encoder/decoder for Smile data

SYNOPSIS

use Data::Smile::XS qw(
  encode_smile decode_smile dump_smile load_smile
);

my $bytes = encode_smile( { hello => 'world' } );
my $data  = decode_smile( $bytes );

dump_smile( 'example.smile', { answer => 42 } );
my $round_trip = load_smile( 'example.smile' );

DESCRIPTION

This module provides a fast XS implementation of Smile serialisation. It exports four optional functions:

  • encode_smile

  • decode_smile

  • dump_smile

  • load_smile

All option arguments are optional hashrefs. Passing any other kind of reference for options throws an exception.

FUNCTIONS

encode_smile( $data, \%options )

Encodes a Perl data structure into Smile bytes and returns a byte string.

Recognised options:

  • write_header (boolean, default true)

    Include the 4-byte Smile header (:) \n and flags byte) before the payload.

  • shared_names (boolean, default true)

    Enable shared key-name back references while encoding object/hash keys.

  • shared_values (boolean, default true when write_header is true; default false when write_header is false and shared_values is not explicitly set)

    Enable shared short-string value back references while encoding.

  • canonical (boolean, default false)

    If true, encode hashes/objects with keys sorted lexically.

    This is slower, but should (in theory) result in byte-identical output every time, given the same input.

Unknown option keys throw an exception.

decode_smile( $bytes, \%options )

Decodes Smile bytes into Perl data and returns the resulting structure.

Recognised options:

  • use_bigint (boolean, default true)

    Decode integer values outside native integer range as Math::BigInt objects (when available).

  • require_header (boolean, default false)

    Require the Smile document header to be present. If true and no header is found, decoding throws an exception.

  • json_bool (boolean, default true)

    If true, decode booleans as JSON::PP booleans (JSON::PP::true and JSON::PP::false) when available. If false, decode booleans as native Perl booleans.

Unknown option keys throw an exception.

dump_smile( $file, $data, \%options )

Encodes $data using encode_smile and writes the bytes to $file. Returns true on success and false on write/close failure.

$file may be:

  • a filename string

  • an open writable filehandle

  • a Path::Tiny object

  • a Path::Class::File object

The \%options hashref is passed through to encode_smile, so it accepts the same options and defaults: write_header, shared_names, shared_values, and canonical.

load_smile( $file, \%options )

Reads Smile bytes from $file, decodes them with decode_smile, and returns the resulting data structure.

$file may be:

  • a filename string

  • an open readable filehandle

  • a Path::Tiny object

  • a Path::Class::File object

The \%options hashref is passed through to decode_smile, so it accepts the same options and defaults: use_bigint, require_header, and json_bool.

BUGS

Please report any bugs to https://github.com/tobyink/p5-data-smile-xs/issues.

SEE ALSO

Data::Smile, Data::Smile::PP, https://github.com/FasterXML/smile-format-specification/blob/master/smile-specification.md (Smile format specification), https://en.wikipedia.org/wiki/Smile_(data_interchange_format).

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

This software is copyright (c) 2026 by Toby Inkster.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.