/ 
Kelp-Module-YAML-2.00
River stage zero No dependents
/ Kelp::Module::YAML

NAME

Kelp::Module::YAML - YAML encoder / decoder for Kelp

SYNOPSIS

# in config
modules => [qw(YAML)],
modules_init => {
	YAML => {
		# options for the constructor
	},
},

# in your application
my $encoded = $self->yaml->encode({
	type => 'structure',
	name => [qw(testing yaml)],
});

# Kelp 2.10 encoder factory
my $new_yaml = $self->get_encoder(yaml => 'name');

DESCRIPTION

This is a very straightforward module that enriches the Kelp framework with YAML serialization. It uses YAML::PP behind the scenes.

This module is compatible with Kelp 2.10 encoders feature, so you can use it as a factory for YAML processors by calling get_encoder on the Kelp app object. It registers itself under the name yaml.

METHODS INTRODUCED TO KELP

yaml

my $yaml_facade = $kelp->yaml;

Returns the instance of an yaml facade. You can use this instance to invoke the methods listed below.

METHODS

encode

my $encoded = $kelp->yaml->encode($data);

A shortcut to $kelp->yaml->engine->dump_string

decode

my $decoded = $kelp->yaml->decode($yaml);

A shortcut to $kelp->yaml->engine->load_string

engine

my $yaml_engine = $kelp->yaml->engine;

Returns the instance of YAML::PP

CONFIGURATION

A single special flag exists, kelp_extensions - if passed and true, YAML extensions for Kelp modules will be installed, adding some new methods to base Kelp packages:

  • Kelp::Request

    Adds is_yaml, yaml_param and yaml_content methods, all working like json counterparts.

  • Kelp::Response

    Adds yaml method and an ability for render to turn a reference into YAML with proper content type.

  • Kelp::Test

    Adds yaml_cmp and yaml_content methods, working like their json counterparts.

The rest of the configuration is fed to "new" in YAML::PP.

YAML content type for the extensions is deduced based on content of $Kelp::Module::YAML::content_type and $Kelp::Module::YAML::content_type_re variables and is text/yaml by default.

CAVEATS

While encode and decode methods in the facade will handle call context and multiple YAML documents just fine, the installed extensions to Kelp components will work in a scalar (single-document) mode. To avoid mistakes, yaml_content in request will return undef if there is more than one document in the request, since in scalar context YAML::PP will return just the first one, ignoring the rest of the data.

SEE ALSO

  • Kelp, the framework

AUTHOR

Bartosz Jarzyna, <bbrtj.pro@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2024 by Bartosz Jarzyna

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