File Coverage

blib/lib/Dancer2/Core/Role/Serializer.pm
Criterion Covered Total %
statement 12 13 92.3
branch n/a
condition n/a
subroutine 5 6 83.3
pod 0 2 0.0
total 17 21 80.9


line stmt bran cond sub pod time code
1             package Dancer2::Core::Role::Serializer;
2             # ABSTRACT: Role for Serializer engines
3             $Dancer2::Core::Role::Serializer::VERSION = '1.0.0';
4 24     24   68714 use Moo::Role;
  24         68  
  24         181  
5 24     24   13972 use Dancer2::Core::Types;
  24         75  
  24         279  
6 24     24   335072 use Scalar::Util 'blessed';
  24         80  
  24         11862  
7              
8             with 'Dancer2::Core::Role::Engine';
9              
10             sub hook_aliases {
11             {
12 218     218 0 1195 before_serializer => 'engine.serializer.before',
13             after_serializer => 'engine.serializer.after',
14             }
15             }
16              
17 34     34 0 85 sub supported_hooks { values %{ shift->hook_aliases } }
  34         139  
18              
19 0     0     sub _build_type {'Serializer'}
20              
21             requires 'serialize';
22             requires 'deserialize';
23              
24             has log_cb => (
25             is => 'ro',
26             isa => CodeRef,
27             default => sub { sub {1} },
28             );
29              
30             has content_type => (
31             is => 'ro',
32             isa => Str,
33             required => 1,
34             writer => 'set_content_type'
35             );
36              
37             around serialize => sub {
38             my ( $orig, $self, $content, $options ) = @_;
39              
40             blessed $self && $self->execute_hook( 'engine.serializer.before', $content );
41              
42             $content or return $content;
43              
44             my $data;
45             eval {
46             $data = $self->$orig( $content, $options );
47             blessed $self
48             and $self->execute_hook( 'engine.serializer.after', $data );
49             1;
50             } or do {
51             my $error = $@ || 'Zombie Error';
52             blessed $self
53             and $self->log_cb->( core => "Failed to serialize content: $error" );
54             };
55              
56             return $data;
57             };
58              
59             around deserialize => sub {
60             my ( $orig, $self, $content, $options ) = @_;
61              
62             $content && length $content > 0
63             or return $content;
64              
65             my $data;
66             eval {
67             $data = $self->$orig($content, $options);
68             1;
69             } or do {
70             my $error = $@ || 'Zombie Error';
71             $self->log_cb->( core => "Failed to deserialize content: $error" );
72             };
73              
74             return $data;
75             };
76              
77             1;
78              
79             __END__
80              
81             =pod
82              
83             =encoding UTF-8
84              
85             =head1 NAME
86              
87             Dancer2::Core::Role::Serializer - Role for Serializer engines
88              
89             =head1 VERSION
90              
91             version 1.0.0
92              
93             =head1 DESCRIPTION
94              
95             Any class that consumes this role will be able to be used as a
96             serializer under Dancer2.
97              
98             In order to implement this role, the consumer B<must> implement the
99             methods C<serialize> and C<deserialize>, and should define
100             the C<content_type> attribute value.
101              
102             =head1 ATTRIBUTES
103              
104             =head2 content_type
105              
106             The I<content type> of the object after being serialized. For example,
107             a JSON serializer would have a I<application/json> content type
108             defined.
109              
110             =head1 METHODS
111              
112             =head2 serialize($content, [\%options])
113              
114             The serialize method need to be implemented by the consumer. It
115             receives the serializer class object and a reference to the object to
116             be serialized. Should return the object after being serialized, in the
117             content type defined by the C<content_type> attribute.
118              
119             A third optional argument is a hash reference of options to the
120             serializer.
121              
122             The serialize method must return bytes and therefore has to handle any
123             encoding.
124              
125             =head2 deserialize($content, [\%options])
126              
127             The inverse method of C<serialize>. Receives the serializer class
128             object and a string that should be deserialized. The method should
129             return a reference to the deserialized Perl data structure.
130              
131             A third optional argument is a hash reference of options to the
132             serializer.
133              
134             The deserialize method receives encoded bytes and must therefore
135             handle any decoding required.
136              
137             =head1 CONFIGURATION
138              
139             The B<serializer> configuration variable tells Dancer2 which engine to use.
140              
141             You can change it either in your config.yml file:
142              
143             #Set JSON engine
144             serializer: "JSON"
145              
146             # Prettify JSON output
147             engines:
148             serializer:
149             JSON:
150             pretty: 1
151              
152             To know which engines are availables please see L<Dancer2::Manual/"Serializers">
153              
154             =head1 AUTHOR
155              
156             Dancer Core Developers
157              
158             =head1 COPYRIGHT AND LICENSE
159              
160             This software is copyright (c) 2023 by Alexis Sukrieh.
161              
162             This is free software; you can redistribute it and/or modify it under
163             the same terms as the Perl 5 programming language system itself.
164              
165             =cut