1use warnings;
2use strict;
3
4package Jifty::JSON;
5
6use base 'Exporter';
7our @EXPORT_OK = qw/jsonToObj objToJson decode_json encode_json/;
8
9use Carp qw//;
10use JSON qw/ -support_by_pp -no_export /;
11
12=head1 NAME
13
14Jifty::JSON -- Wrapper around L<JSON>
15
16=head1 SYNOPSIS
17
18  use Jifty::JSON qw/decode_json encode_json/;
19
20  my $obj  = decode_json(q! { "x": "1", "y": "2", "z": "3" } !);
21  my $json = encode_json($obj);
22
23=head1 DESCRIPTION
24
25Provides a thin wrapper around the L<JSON> 2.xx library, which provides a
26frontend for L<JSON::XS> and L<JSON::PP>.
27
28This module used to wrap L<JSON::Syck> and L<JSON> 1.xx with special-casing for
29outputting JSON with single quoted values.  Single quotes make it easy to
30simply plop JSON into HTML attributes but are in violation of the JSON spec
31which mandates only double quoted strings.
32
33The old behavior is now unsupported and it is recommended that you simply HTML
34escape your entire blob of JSON if you are sticking it in an HTML attribute.
35You can use L<Jifty-E<gt>web-E<gt>escape()|Jifty::Web/escape> to properly
36escape problematic characters for HTML.
37
38=head1 FUNCTIONS
39
40=head2 decode_json JSON, [ARGUMENT HASHREF]
41
42=head2 encode_json JSON, [ARGUMENT HASHREF]
43
44These functions are just like L<JSON>'s, except that you can pass options to
45them like you can with L<JSON>'s C<from_json> and C<to_json> functions.
46
47By default they encode/decode using UTF8 (like L<JSON>'s functions of the same
48name), but you can turn that off by passing C<utf8 =E<gt> 0> in the
49options.  The L<allow_nonref|JSON/allow_nonref> flag is also enabled for
50backwards compatibility with earlier versions of this module.  It allows
51encoding/decoding of values that are not references.
52
53L<JSON> is imported with the C<-support_by_pp> flag in order to support all
54options that L<JSON::PP> provides when using L<JSON::XS> as the backend.  If
55you are concerned with speed, be careful what options you specify as it may
56cause the pure Perl backend to be used.  Read L<JSON/JSON::PP SUPPORT METHODS>
57for more information.
58
59=cut
60
61sub decode_json {
62    JSON::from_json( $_[0], { utf8 => 1, allow_nonref => 1, %{$_[1] || {}} } );
63}
64
65sub encode_json {
66    JSON::to_json( $_[0], { utf8 => 1, allow_nonref => 1, %{$_[1] || {}} } );
67}
68
69=head1 DEPRECATED FUNCTIONS
70
71=head2 jsonToObj JSON, [ARGUMENTS]
72
73=head2 objToJson JSON, [ARGUMENTS]
74
75These functions are deprecated and provided for backwards compatibility.  They
76wrap the appropriate function above, but L<Carp/croak> if you try to set the
77C<singlequote> option.
78
79=cut
80
81sub jsonToObj {
82    my $args = $_[1] || {};
83    Carp::croak("Attempted to set 'singlequote' option, but it is no longer supported.".
84                "  You may need to HTML escape the resulting JSON.".
85                "  Please read the POD of Jifty::JSON and fix your code.")
86        if exists $args->{'singlequote'};
87    decode_json( @_ );
88}
89
90sub objToJson {
91    my $args = $_[1] || {};
92    Carp::croak("Attempted to set 'singlequote' option, but it is no longer supported.".
93                "  You may need to HTML escape the resulting JSON.".
94                "  Please read the POD of Jifty::JSON and fix your code.")
95        if exists $args->{'singlequote'};
96    encode_json( @_ );
97}
98
99=head1 LICENSE
100
101Jifty is Copyright 2005-2010 Best Practical Solutions, LLC.
102Jifty is distributed under the same terms as Perl itself.
103
104=cut
105
1061;
107