NAME

Chandra::Store - Persistent key-value storage for Chandra apps

SYNOPSIS

use Chandra::Store;

my $store = Chandra::Store->new(name => 'myapp');

$store->set('theme', 'dark');
my $theme = $store->get('theme');               # 'dark'
my $val   = $store->get('missing', 'default');  # 'default'

$store->set('window.width', 800);
$store->set('window.height', 600);
my $w      = $store->get('window.width');       # 800
my $window = $store->get('window');             # { width => 800, height => 600 }

$store->has('theme');                           # 1
$store->delete('theme');

$store->set_many({
    'ui.font_size' => 14,
    'ui.sidebar'   => 1,
    'recent_files' => ['/path/a', '/path/b'],
});

my $all = $store->all;
$store->clear;

# Manual save mode — batch multiple writes into one disk write
my $s = Chandra::Store->new(name => 'myapp', auto_save => 0);
$s->set('x', 1)->set('y', 2)->set('z', 3);
$s->save;

# Reload picks up external changes
$s->reload;

# Via Chandra::App
my $app = Chandra::App->new(title => 'My App', ...);
my $store = $app->store;     # name derived from app title

DESCRIPTION

Chandra::Store provides persistent key-value storage for Chandra desktop applications, backed by a JSON file at ~/.chandra/<name>/store.json by default.

Keys support dot notation for nested structures (e.g. window.width). Writes are atomic: data is written to a .tmp.PID file then renamed into place. File locking (flock) prevents corruption from concurrent processes.

METHODS

new(%args)

Chandra::Store->new(name => 'myapp')
Chandra::Store->new(path => '/explicit/path/store.json')
Chandra::Store->new(name => 'myapp', auto_save => 0)

Either name or path is required. name stores the file at ~/.chandra/<name>/store.json. Parent directories are created automatically.

auto_save defaults to 1. When enabled, every mutating call (set, delete, set_many, clear) triggers an immediate disk write.

get($key [, $default])

Return the value for $key. Supports dot notation to reach nested values. Returns $default (or undef) if the key does not exist.

set($key, $value)

Set $key to $value. Dot notation creates intermediate hashes as needed. Croaks if an intermediate segment exists but is not a hash. Returns $self for chaining.

has($key)

Returns 1 if $key exists, 0 otherwise. Supports dot notation.

delete($key)

Delete $key. Supports dot notation; sibling keys are unaffected. Returns $self.

set_many(\%pairs)

Set multiple keys in a single call. When auto_save is on, writes to disk once after all keys are set rather than once per key. Returns $self.

all()

Returns a reference to the internal data hash (not a copy). Top-level keys only; nested structures are hashrefs.

clear()

Remove all keys. Writes {} to disk if auto_save is on. Returns $self.

save()

Write the current in-memory state to disk. Use with auto_save = 0> for manual control over when writes occur. Returns $self.

reload()

Re-read the store file from disk, replacing in-memory state. Useful when another process may have modified the file. Returns $self.

path()

Returns the absolute path to the backing JSON file.

auto_save([$bool])

Getter/setter for the auto_save flag. With no argument returns the current value. With an argument sets it and returns $self.

SEE ALSO

Chandra, Chandra::App

cpanm Chandra

perl -MCPAN -e shell
install Chandra