/ 
JSON-WithComments-0.001
River stage zero No dependents
/ JSON::WithComments

NAME

JSON::WithComments - Parse JSON content with embedded comments

VERSION

version 0.001

SYNOPSIS

use JSON::WithComments;

my $content = <<JSON;
/*
 * This is a block-comment in the JavaScript style, the default.
 */
{
    // Line comments are also recognized
    "username" : "rjray",  // As are side-comments
    // This should probably be hashed:
    "password" : "C0mputer!"
}
JSON

my $json = JSON::WithComments->new;
my $hashref = $json->decode($json);

DESCRIPTION

NOTE: This is an early release, and should be considered alpha-quality. The interface is subject to change in future versions.

JSON::WithComments is a simple wrapper around the JSON module that pre-processes any JSON input before decoding it. The pre-processing is simple: based on the style of comments that the object is configured for, it strips all comments of that style it finds, before passing the remaining content to the decode method of the parent class.

The motivation for this was simple: with JSON becoming more and more popular as a configuration format, some tools have started adding as-hoc support for comments into their JSON parsers. This allows documentation to be a part of these (sometimes quite large) JSON files. This module slightly extends the concept by allowing you to opt for different styles of comments.

The JSON module itself allows for shell-style (Perl-style) comments via use of the relaxed method. IF YOU ONLY NEED PERL-STYLE COMMENTS, you can get that from JSON directly. The advantage that this module offers is the flexibility of also recognizing JavaScript-style comments.

Comment Styles

The JSON::WithComments module will support the following named styles of comments:

javascript

This is the default, and recognizes both line comments denoted by //, and block comments denoted by /* followed at some point by */. This is also the style used by C/C++, but as JSON itself is based in the JavaScript world, this style is referred to as javascript.

perl

This is an optional style that can be specified either by setting the default style perl via the -default_comment_style import option, or by using the comment_style method. This style recognizes line comments delimited by a # character, and does not have a block-style comment.

Comment delimiters may be prefixed with a backslash character (\) to prevent their removal. This may be needed if the delimiter character(s) appear in a string, for example.

IMPORT OPTIONS

The class provides an import method which will process any arguments specific to this class, before passing everything else to the parent class. Currently, there is only one option recognized:

-default_comment_style style

Set a different default comment style. If not given, the default is javascript. Must be one of perl or javascript, otherwise it dies via croak.

SUBROUTINES/METHODS

This class provides the following methods:

comment_style

This method takes a single value and sets it to be the new comment style for the calling object. The new value must be one of the named styles listed above. If an unknown style is specified, the method dies using croak. The return value is the object reference itself.

get_comment_style

Returns the current comment style, or the default comment style if the calling object does not have its own style set.

decode

This method takes one argument, the JSON text to parse. The text is first scrubbed of comments, then passed to the superclass decode method.

At present, this module does not facilitate the import of the non-method functions that JSON provides.

DIAGNOSTICS

The JSON module reports parsing errors by throwing an exception (dying) and reporting the character offset within the string at which the error occurred. This module attempts to preserve that behavior by replacing comments with an equal-length string of spaces. As such, if you see a parsing error that refers to character 1023, the comments should not interfere with your ability to go to character 1023 via your preferred text editor and see the actual source of the error.

Additionally, trying to set the comment-style to an unknown value (either in the comment_style method or at import time) will result in an exception.

CAVEATS

Comments are not an official feature of JSON, so by using comments with JSON data you are limiting the range of tools that you can use with that data. If in the future a new JSON standard is published that supports comments, this module will have to be updated (or deprecated) accordingly.

BUGS

As this is alpha software, the likelihood of bugs is pretty close to 100%. Please report any issues you find to either the CPAN RT instance or to the GitHub issues page:

SUPPORT

LICENSE AND COPYRIGHT

This file and the code within are copyright (c) 2017 by Randy J. Ray.

Copying and distribution are permitted under the terms of the Artistic License 1.0 or the GNU GPL 1. See the file LICENSE in the distribution of this module.

AUTHOR

Randy J. Ray <rjray@blackperl.com>