view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

# NAME

Config::JSON::Enhanced - JSON-based config with C/Shell-style comments, verbatim sections and variable substitutions

# VERSION

Version 0.10

# SYNOPSIS

This module provides subroutine `config2perl()` for parsing configuration content,
from files or strings,  based on, what I call, "enhanced JSON" (see section
["ENHANCED JSON FORMAT"](#enhanced-json-format) for more details). Briefly, it is standard JSON which allows:

- `C`-style, `C++`-style, `shell`-style or custom comments.
- Template-style variables (e.g. `<% appdir %>`)
which are substituted with user-specified data during parsing.
- Verbatim sections which are a sort of here-doc for JSON,
allowing strings to span multiple
lines, to contain single and double quotes unescaped,
to contain template-style variables.

This module was created because I needed to include
long shell scripts containing lots of quotes and newlines,
in a configuration file which started as JSON.

The process is simple: so-called "enhanced JSON" is parsed
by [config2perl](https://metacpan.org/pod/config2perl). Comments are removed, variables are
substituted, verbatim sections become one line again
and standard JSON is created. This is parsed with
[JSON](https://metacpan.org/pod/JSON) (via [Data::Roundtrip::json2perl](https://metacpan.org/pod/Data%3A%3ARoundtrip%3A%3Ajson2perl)) to
produce a Perl data structure which is returned.

It has been tested with unicode data
(see `t/070-config2perl-complex-utf8.t`)
with success. But who knows ?!?!

Here is an example:

       use Config::JSON::Enhanced;

       # simple "enhanced" JSON with comments in 3 styles: C,shell,CPP
       my $configdata = <<'EOJ';
        {
           /* 'a' is ... */
           "a" : "abc",
           # b is ...
           "b" : [1,2,3],
           "c" : 12 // c is ...
        }
       EOJ
       my $perldata = config2perl({
           'string' => $configdata,
           'commentstyle' => "C,shell,CPP",
       });
       die "call to config2perl() has failed" unless defined $perldata;
       # the standard JSON:
       # {"a" : "abc","b" : [1,2,3], "c" : 12}


       # this "enhanced" JSON demonstrates the use of variables
       # which will be substituted during the transformation to
       # standard JSON with user-specified data.
       # Notice that the opening and closing tags enclosing variable
       # names can be customised using the 'tags' input parameter,
       # so as to avoid clashes with content in the JSON.
       my $configdata = <<'EOJ';
        {
          "d" : [1,2,<% tempvar0 %>],
          "configfile" : "<%SCRIPTDIR%>/config/myapp.conf",
          "username" : "<% username %>"
           }
        }
       EOJ
       my $perldata = config2perl({
           'string' => $configdata,
           'commentstyle' => "C,shell,CPP",
           # optionally customise the tags enclosing the variables
           # when you want to avoid clashes with other strings in JSON
           #'tags' => ['<%', '%>'], # <<< these are the default values
           # user-specified data to replace the variables in
           # the "enhanced" JSON above:
           'variable-substitutions' => {
               'tempvar0' => 42,
               'username' => getlogin(),
               'SCRIPTDIR' => $FindBin::Bin,
           },
       });
       die "call to config2perl() has failed" unless defined $perldata;
       # the standard JSON
       # (notice how all variables in <%...%> are now replaced):
       # {"d" : [1,2,42],
       #  "username" : "yossarian",
       #  "configfile" : "/home/yossarian/B52/config/myapp.conf"