view release on metacpan or  search on metacpan

README  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" 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. Comments are removed, variables are substituted, verbatim
    sections become one line again and standard JSON is created. This is
    parsed with JSON (via Data::Roundtrip::json2perl) 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"
        # }