NAME
Config::JSON - flat, JSON-backed read-write configuration
TABLE OF CONTENTS
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::JSON::X::NoSuchKey exception. If $key is Whatever, returns
the entire config hash.
If config file could not be read, fails
with Config::JSON::X::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::JSON::X::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::JSON::X::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::JSON::X::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.