Config::JSON(3pm)

💖 Config::JSON — the manual page, but make it cute 💖

okay bestie, gather round, because we're about to talk about Config::JSON, a whole JSON based config file system, and honestly? it's giving organized. it's giving structured. it's giving "my config files finally make sense." ✨

this is the Config::JSON page from the User Contributed Perl Documentation, and we're keeping every single crumb of it, no cap. 🍓

---

🌸 VERSION 🌸

version 1.5202 — that's the one, that's the vibe check passed. 💅

---

✨ SYNOPSIS ✨

here's the little taste test, the main character intro, the way you actually use it:

use Config::JSON;

my $config = Config::JSON->create($pathToFile);
my $config = Config::JSON->new($pathToFile);
my $config = Config::JSON->new(pathToFile=>$pathToFile);

my $element = $config->get($directive);

$config->set($directive,$value);

$config->delete($directive);
$config->deleteFromHash($directive, $key);
$config->deleteFromArray($directive, $value);

$config->addToHash($directive, $key, $value);
$config->addToArray($directive, $value);

my $path = $config->pathToFile;
my $filename = $config->getFilename;

🎀 Example Config File 🎀

look at her. she's beautiful. she's JSON but with comments, which is illegal in normal JSON and yet here we are, slaying:

# config-file-type: JSON 1
{
   "dsn" : "DBI:mysql:test",
   "user" : "tester",
   "password" : "xxxxxx",

   # some colors to choose from
   "colors" : [ "red", "green", "blue" ],

   # some statistics
   "stats" : {
           "health" : 32,
           "vitality" : 11
   },

   # including another file
   "includes" : ["macros.conf"]
}

---

🦋 DESCRIPTION 🦋

so this package parses config files that are written in JSON. and it also does some non-JSON stuff, like letting you put comments in the files, which is honestly iconic of it. 😌

if you wanna see it out in the wild doing its thing, it's the config file system used in WebGUI <http://www.webgui.org/>. she's employed. she's working. 💼

💭 Why? 💭

why build yet another config file system, you ask? okay so, there are a whole bunch of reasons, and they're all valid, so let me lay them out:

• they used to use other config file parsers and kept running into limitations. annoying. 🙄
• they already use JSON in their app, so storing config files as JSON means using less memory, because the JSON parser is already chilling in memory anyway.
• with JSON you can have any number of hierarchical data structures represented in the config file, whereas most config files give you only one level of hierarchy, if any at all. one level? in this economy?? 💀
• JSON parses faster than XML and YAML.
• JSON is easier to read and edit than XML.
• many other config file systems let you read a config file but give you no mechanism or utilities to write back to it. JSON said "no, we do both."
• JSON is taint safe.
• JSON is easily parsed by languages other than Perl when that needs to happen. multilingual queen. 🌈

👑 Multi-level Directives 👑

you can of course access a directive called "foo", but since the config is basically a hash, you can traverse multiple elements of the hash when specifying a directive name by just delimiting each level with a slash, like "foo/bar". for example you may:

my $vitality = $config->get("stats/vitality");
$config->set("stats/vitality", 15);

and you can do this wherever you specify a directive name. periodt.

🙈 Comments 🙈

you can put comments in the config file as long as # is the first non-space character on the line. cute, right?

but lowkey — if you use this API to write to the config file, your comments will be eliminated. gone. deleted. not me losing my little notes. 😭

🧚 Includes 🧚

there's a special directive called "includes", which is an array of include files that may be brought in to the config. and here's the tea: even the files you include can have an "includes" directive, so you can do hierarchical includes. it's includes all the way down, bestie.

any directive in the main file takes precedence over the directives in the includes. likewise, the files listed first in the "includes" directive have precedence over the files that come after it. and when writing to the files, the same precedence is followed. consistent. we love a system with rules. 💅

if you're setting a new directive that doesn't currently exist, it will only be written to the main file.

if a directive is deleted, it will be deleted from all files, including the includes. yeah. all of them. dramatic but fair. 💀

---

🌟 INTERFACE 🌟

addToArray ( directive, value )

adds a value to an array directive in the config file. adding! to the array! ✨

• directive — the name of the array.
• value — the value to add.

addToArrayBefore ( directive, insertBefore, value )

inserts a value into an array immediately before another item. if that item can't be found, it inserts at the beginning of the array. no item? front of the line, babe.

• directive — the name of the array.
• insertBefore — the value to search for and base the positioning on.
• value — the value to insert.

addToArrayAfter ( directive, insertAfter, value )

inserts a value into an array immediately after another item. if that item can't be found, it inserts at the end of the array. no item? back of the line, babe.

• directive — the name of the array.
• insertAfter — the value to search for and base the positioning on.
• value — the value to insert.

addToHash ( directive, key, value )

adds a value to a hash directive in the config file.

NOTE: this is really the same as $config->set("directive/key", $value); — like, literally the same thing. just so you know. 🫶

• directive — the name of the hash.
• key — the key to add.
• value — the value to add.

create ( pathToFile )

constructor. creates a new empty config file. brand new. fresh out the box. 🎀

• pathToFile — the path and filename of the file to create.

delete ( directive )

deletes a key from the config file. bye bestie. 👋

• directive — the name of the directive to delete.

deleteFromArray ( directive, value )

deletes a value from an array directive in the config file.

• directive — the name of the array.
• value — the value to delete.

deleteFromHash ( directive, key )

delete a key from a hash directive in the config file.

NOTE: this is really just the same as doing $config->delete("directive/key"); — same energy, different font. 💅

• directive — the name of the hash.
• key — the key to delete.

get ( directive )

returns the value of a particular directive from the config file. the little grabby hands method. 🤲

• directive — the name of the directive to return.

getFilename ( )

returns the filename for this config. just the name, babe. 🎀

pathToFile ( )

returns the filename and path for this config. may also be called as "getFilePath" for backward campatibility sake. (yes, "campatibility" — we're keeping the typo, it's part of her lore. 😌)

includes ( )

returns an array reference of Config::JSON objects that are files included by this config. may also be called as "getIncludes" for backward compatibility sake.

new ( pathToFile )

constructor. builds an object around a config file. wrapping it up like a lil gift. 🎁

• pathToFile — a string representing a path such as "/etc/my-cool-config.conf".

set ( directive, value )

creates a new directive or updates an existing one in the config file. either way, she's serving. ✨

• directive — a directive name.
• value — the value to set the paraemter to. (again with the typo, keeping it, it's iconic.) can be a scalar, hash reference, or array reference.

splitKeyParts ( key )

returns an array of key parts. splitting! separating! organizing! 💅

• key — a key string. could be 'foo' (simple key), 'foo/bar' (a multilevel key referring to the bar key as a child of foo), or 'foo\/bar' (a simple key that contains a slash in the key). don't forget to double escape in your perl code if you have a slash in your key parts like this:

$config->get('foo\\/bar');

write ( )

writes the file to the filesystem. normally you'd never need to call this, because it's called automatically by the other methods when a change occurs. she handles it herself. independent queen. 👑

---

😭 DIAGNOSTICS 😭

here's where things can go wrong, and we must discuss them, because ignoring errors is not the vibe:

• "Couldn't parse JSON in config file" — this means that the config file does not appear to be formatted properly as a JSON file. common mistakes are missing commas or trailing commas on the end of a list. (trailing commas, bestie. they get us every time. 💀)
• "Cannot read config file" — we couldn't read the config file. this usually means that the path specified in the constructor is incorrect. check the path, babes. 🔍
• "Can't write to config file" — we couldn't write to the config file. this usually means that the file system is full, or the that the file is write protected. (yes, "or the that" — the original said it, we're saying it too, it's part of the lore. 🙈)

---

🧸 PREREQS 🧸

the friend group, the entourage, the prerequisites:

• JSON
• Moo
• List::Util
• Test::More
• Test::Deep

---

🫶 SUPPORT 🫶

• Repository — <http://github.com/plainblack/Config-JSON>
• Bug Reports — <http://rt.cpan.org/Public/Dist/Display.html?Name=Config-JSON>

---

💜 AUTHOR 💜

JT Smith <jt-at-plainblack-dot-com> — the icon, the legend, the one who wrote this whole thing. 👑

---

⭐ LEGAL ⭐

Config::JSON is Copyright 2009 Plain Black Corporation (<http://www.plainblack.com/>) and is licensed under the same terms as Perl itself.

---

and that's the whole page, bestie. every flag, every method, every typo, every warning — all of it, preserved and serving looks. 🌈

this was Config::JSON from perl v5.34.0, dated 2022-06-12, and honestly? she ate. no crumbs left. 💅✨🦋