=encoding UTF-8

=head1 NAME

JSON::Create - turn a Perl variable into JSON

=head1 SYNOPSIS

    use JSON::Create 'create_json';
    my %hash = (a => b, c => d);
    my $json = create_json (\%hash);
    # Now $json contains '{"a":"b","c":"d"}', or similar.

=head1 DESCRIPTION

This module produces JSON out of Perl

It currently works for the simple cases of strings, nested hashes and
arrays, but it is in very early testing stages.

=head1 FUNCTIONS

=head2 create_json

    my $json = create_json (\%hash);

Convert a Perl hash or array into JSON.

=head1 CONVERSIONS

=head2 Hashes

Associative arrays are converted to JSON objects. The keys are written
into JSON as strings, with any control characters escaped. The order
of the keys is as they are supplied by Perl.

=head2 Arrays

Arrays are converted to JSON arrays. The order of the array is
identical to the Perl one.

=head2 Scalars

Scalars are converted to strings, JSON integers or JSON floats
depending on what Perl says they contain. 

Bytes of value less than 0x20 are converted into the appropriate JSON
escapes. Currently, no escaping or checking is done for Unicode
bytes.

=head3 The undefined value

Undefined values are mapped to the JSON literal "null".

=head3 Booleans

There is currently no way to produce booleans (JSON "true" and "false"
literals).

=head3 Unicode escapes

There is currently no facility to produce Unicode escapes, except for
control characters (bytes less than 0x20 in value which are not
whitespace or \b).

=head3 Unicode

If any part of the input object is marked as "utf8" (multibyte
characters), every non-ASCII string in the input object needs to be
marked as such, otherwise the module prints a warning and returns an
undefined value. If every part of the input is not marked as "utf8",
this does not happen, but there is also currently no validation of the
output as being in Unicode, so binary strings can pass through without
correction. See also L</BUGS>.

=head2 Regexes

If the scalar contains a regex then JSON::Create lets Perl convert the
regex to a string then adds that. The output depends on the Perl
version.

=head2 Code references and other

A code reference in the input causes the entire return value to be the
undefined value.

=head1 EXPORTS

The module exports nothing except by request. One function,
L</create_json>, is exported on request.

=head1 SEE ALSO

This module is a companion module to the same author's
L<JSON::Parse>. Please see that module's documentation for links to
the JSON standard itself and a summary of the ever-growing list of
JSON modules on CPAN.

=head1 BUGS

JSON is required to be in Unicode, but it's possible to pass
non-Unicode strings through this module by switching off the Perl
UTF-8 flag everywhere, since unmarked binary bytes are currently not
validated independent of Perl's validation, which does not apply to
unmarked strings.

=head1 PERFORMANCE

This module is currently at an early stage of development, so speed is
not a key issue until the module is demonstrably producing correct
outputs.

However, due to user interest, there is a benchmarking script in
F<bench/bench.pl> which compares the performance of the module with
L<JSON::XS> and L<Cpanel::JSON::XS>.

=head1 HISTORY

I started making this module so that, with this and JSON::Parse, I
wouldn't have to ever use any of the existing JSON modules on CPAN
ever again. See also L</SEE ALSO>. The exact time I've spent making
this module is recorded in the file F<timesheet.txt> in the top
directory of the distribution. At the time of version 0.03_02, I've
spent 12 hours and 30 minutes working on this.

=cut


=head1 AUTHOR

Ben Bullock, <bkb@cpan.org>

=head1 COPYRIGHT & LICENCE

This package and associated files are copyright (C) 
2015
Ben Bullock.

You can use, copy, modify and redistribute this package and associated
files under the Perl Artistic Licence or the GNU General Public
Licence.


