NAME

Config::JSON - flat, JSON-backed read-write configuration

TABLE OF CONTENTS

• SYNOPSIS
• DESCRIPTION
• SINGLE CONFIG FILE MODE
  • EXPORTED SUBROUTINES
    • jconf
    • jconf-write
• PER-CALL CONFIG FILE MODE
  • EXPORTED SUBROUTINES
    • jconf
    • jconf-write
• EXCEPTIONS
  • Config::NoSuchKey
  • Config::Open
• MULTI-THREAD/PROCESS SAFETY
• CAVEATS
• REPOSITORY
• BUGS
• AUTHOR
• LICENSE

SYNOPSIS

    use Config::JSON; # uses './config.json' by default
    say jconf('foo')//'no such option'; # "no such option"
    say jconf-write('foo', 'bar');
    say jconf 'foo'; # "bar"
    say jconf-write('foo', {bar => [<a b c>]});
    say jconf('foo').perl; # ${:bar($["a", "b", "c"])}

Custom config files:

    use Config::JSON 'meow.json';
    say jconf 'foo';

    use Config::JSON '';  # <-- empty string is required
    say jconf 'meow.json'.IO, 'foo'; # specify file during calls

DESCRIPTION

Simple read-write configuration, using JSON saved in a file. By design, the
API provides flat key/value structure only, but you’re free to save nested
structures under the keys.

SINGLE CONFIG FILE MODE

The configuration file to use is specified on the use line:

    use Config::JSON;               # default './config.json'
    use Config::JSON 'foo.json';    # custom './foo.json'
    use Config::JSON 'foo.json'.IO; # also OK

If the file doesn’t exist, it will be automatically created. If you wish to
create it manually, its outer data structure must be a JSON object:

    constant $file = 'foo.json'.IO;
    BEGIN $file.spurt: '{ "meow": 42 }';
    use Config::JSON $file;
    say jconf 'meow'; # 42

EXPORTED SUBROUTINES

jconf

    multi jconf (Whatever --> Mu);
    multi jconf (Str:D $key --> Mu);

Reads config file and looks up $key in the config hash. Returns its value
if it :exists, otherwise, fails
with Config::NoSuchKey exception. If $key is Whatever, returns
the entire config hash.

If config file could not be read, fails
with Config::Open exception.

jconf-write

    sub jconf-write (Str:D $key, Mu $value --> Nil);

Saves $value under $key, possibly overwriting previously-existing value.
Reads the config from file before writing.

If config file could not be read or written,
fails
with Config::Open exception.

PER-CALL CONFIG FILE MODE

    use Config::JSON '';  # no auto config file; pass filename to each call
                          # of config read/write routines instead

EXPORTED SUBROUTINES

Note that these are not available in single-config-file mode.

jconf

    multi jconf (IO::Path:D $file, Whatever --> Mu);
    multi jconf (IO::Path:D $file, Str:D $key --> Mu);

Same as jconf for single-config-file version, except takes the
name of the config file as the first argument.

jconf-write

    sub jconf-write (IO::Path:D $file, Str:D $key, Mu $value --> Nil);

Same as jconf-write for single-config-file mode, except takes the
name of the config file as the first argument.

EXCEPTIONS

Config::NoSuchKey

    has Str:D      $.key  is required;
    has IO::Path:D $.file is required;
    method message {
        "Key `$!key` is not present in the config file `$!file.absolute()`"
    }

Config::Open

    has Exception:D $.e    is required;
    has IO::Path:D  $.file is required;
    method message {
        "Received $!e.^name() with message `$!e.message()` while trying to"
        ~ " open config file `$!file.absolute()`"
    }

MULTI-THREAD/PROCESS SAFETY

The routines perform advisory locking of the config file on each read and write.

CAVEATS

Rakudo’s bug R#1370 prevents
use of this module in precompiled modules when using default config file
or specifying one on the use line. Use no precompilation
pragma to work-around it.

Using empty string on use line and specifying config file’s name to each
routine does not trigger this bug.

REPOSITORY

Fork this module on GitHub:
https://github.com/raku-community-modules/Config-JSON

BUGS

To report bugs or request features, please use
https://github.com/raku-community-modules/Config-JSON/issues

AUTHOR

Zoffix Znet (http://perl6.party/)

LICENSE

You can use and distribute this module under the terms of the
The Artistic License 2.0. See the LICENSE file included in this
distribution for complete details.

The META6.json file of this distribution may be distributed and modified
without restrictions or attribution.