NAME

Agni - persistent data and objects

SYNOPSIS

This module requires the PApp module to be installed and working. Please read the LICENSE file: this version of Agni is neither GPL nor BSD licensed).

DESCRIPTION

Agni is the God of the Sun and Fire. The rest is obvious...

Most of these functions are low-level stuff. Better look at the methods of the agni root object (本) first, which has most of the functionality packaged in a nicer way.

FUNCTIONS

path_obj_by_gid $path, $gid

Returns a object by gid in a specified path.

obj_by_name $spec

Loads on object by name. The $spec string consists of an agni path followed by an object name, separated by a slash (/). An additional leading slash will be ignored. Object names are either a numeric GID, or a namespace name and an object name separated by a slash.

A few examples should make it clear:

   root/agni/2         # the attr object, numeric object name
   root/agni/GID/2     # same object, with namespace syntax
   /root/agni/GID/2    # same object, extra slash at the beginning
   root/agni/agni/attr # same object, different namespace

path_gid2name $path, $gid

Tries to return the name of the object, or some other descriptive string, in case the object lacks a name. Does not load the object into memory, but might load other objects in memory.

obj2name $obj

Same as path_gid2name, but works on an existing object.

commit_objs [$gid, $src_path, $dst_path], ...

Commit (copy) objects from one path to another. If $dst_path is undefined or missing, deletes the instance (making higher-path instances visible again).

Currently, $src_path must be the "topmost" path of one object instance. Object instances that are also visible in parent paths are skipped.

It returns a html fragment describing it's operations.

 # delete the root object (gid 1) from the staging path
 Agni::commit_objs [1, $Agni::pathid{"root/staging/"}, undef];

 # kind of read-modify-write for an object
 # 1. get an object into the staging path
 my $sobj = $obj->to_staging_path;
 # 2. modify it
 $sobj->{...} = ...;
 # 3a. either commit it ("save changes"):
 Agni::commit_objs [$sobj->{_gid}, $sobj->{_path}, $obj->{_path}];
 # 3b. or delete it ("cancel"):
 Agni::commit_objs [$sobj->{_gid}, $sobj->{_path}, undef];

agni_exec { BLOCK };

Execute the given perl block in an agni-environment (i.e. database set up correctly etc.).

agni_refresh

Refresh the database connection and the $PApp::NOW timestamp, and also checks for events (e.g. write accesses) done by other agni processes. Usually called within agni_exec after some time has progressed.

Might do other things in the future.

SEE ALSO

The bin/agni commandline tool, the agni online documentation.

AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/