/ 
Config-JSON-Enhanced-0.01
River stage one • 1 direct dependent • 1 total dependent
/ README.md

NAME

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

VERSION

Version 0.01

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" for more details). Briefly, it is standard JSON which allows:

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

Here is an example:

 use Config::JSON::Enhanced qw/config2perl/;

 my $configdata = 'EOJ';
 {
     "a" : "abc",
     "b" : {
       /* this is a comment */
       "c" : <%begin-verbatim-section%>
   This is a multiline string
 /* all spaces between the start of the line and
    the first char will be erased.
    Newlines are escaped and kept.
 */
   with "quoted text" and 'this also'
   and comments like /* this */ or
   # this
   will be retained in the string
 /* white space from beginning and end will be erased */

 <%end-verbatim-section%>
       ,
       "d" : [1,2,<% tempvar0 %>],
       "e" : "< % tempvar1 % > user and <%tempvar2%>!"
     }
 }
 EOJ

 my $perldata = config2perl({
     'string' => $configdata,
     'commentstyle' => "C,shell,CPP",
     'variable-substitutions' => {
         # substitutions do not add extra quotes
         'tempvar0' => 42,
         'tempvar1' => 'hello',
         'tempvar2' => 'goodbye',
     },
 });
 die "call to config2perl() has failed" unless defined $perldata;

 # and here is the dump of the perl data structure $perldata
{
  "b" => {
    "d" => [1,2,42],
    "c" => "This is a multiline string\n\nwith \"quoted text\" and 'this also'\nand comments like  or\n# this\nwill be retained in the string\n",
    "e" => "hello user and goodbye!"
  },
  "a" => "abc"
}

EXPORT

SUBROUTINES

config2perl

my $ret = config2perl($params);

Arguments:

Return value:

Given Enhanced JSON content it removes any comments, it replaces all template strings, if any, and then parses what remains as standard JSON into a Perl data structure which is returned.

JSON content to-be-parsed can be specified with one of the following keys in the input parameters hashref ($params):

Additionally, input parameters can contain the following keys:

See section "ENHANCED JSON FORMAT" for details on the format of what I call enhanced JSON.

config2perl returns the parsed content as a Perl data structure on success or undef on failure.

ENHANCED JSON FORMAT

This is JSON with added reasonable, yet completely ad-hoc, enhancements (from my point of view).

These enhancements are:

Verbatim Sections

A Verbaitm Section in this ad-hoc, so-called Enhanced JSON is content enclosed within <%begin-verbatim-section%> and <%end-verbatim-section%> tags. This content may span multiple lines (which when converted to JSON will preserve them by escaping), can contain comments (see the beginning of this section) and can contain template variables to be substituted with user-specified data.

Here is an example of enhanced JSON which contains comments, a verbatim section and template variables:

my $con = <<'EOC';
{
  "long bash script" : ["/usr/bin/bash",
/* This is a verbatim section */
<%begin-verbatim-section%>
  pushd . &> /dev/null
  echo "My 'appdir' is \"<%appdir%>\""
  echo "My current dir: " $(echo $PWD) " and bye"
  popd &> /dev/null
<%end-verbatim-section%>
  ],
  // this is an example of a template variable
  "expected result" : "<% expected-res123 %>"
}
EOC

# Which, can be processed thusly:
my $res = config2perl({
  'string' => $con,
  'commentstyle' => 'C,CPP',
  'variable-substitutions' => {
    'appdir' => Cwd::abs_path($FindBin::Bin),
    'expected-res123' => 42
  },
});
die "call to config2perl() has failed" unless defined $res;

# the dump of $res is:
{
  "expected result" => 42,
  "long bash script" => [
    "/usr/bin/bash",
    "pushd . &> /dev/null\necho \"My 'appdir' is \\\"/home/andreas/PROJECTS/CPAN/Config-JSON-Enhanced/t\\\"\"\necho \"My current dir: \" \$(echo \$PWD) \" and bye\"\npopd &> /dev/null"
  ]
};

AUTHOR

Andreas Hadjiprocopis, <bliako at cpan.org>

BUGS

Please report any bugs or feature requests to bug-config-json-enhanced at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Config-JSON-Enhanced. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Config::JSON::Enhanced

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is Copyright (c) 2023 by Andreas Hadjiprocopis.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)