/ 
Net-FluidDB-0.03
/ Net::FluidDB

NAME

Net::FluidDB - A Perl interface to FluidDB

SYNOPSIS

use Net::FluidDB;
use Net::FluidDB::Object;
use Net::FluidDB::Tag;
use Net::FluidDB::Namespace;
use Net::FluidDB::Policy;
use Net::FluidDB::Permission;
use Net::FluidDB::User;

# --- FluidDB ----------------------------------

# predefined FluidDB client for playing around, points
# to the sandbox with user test/test
$fdb = Net::FluidDB->new_for_testing;
$fdb = Net::FluidDB->new_for_testing(trace_http => 1);

# FluidDB client pointing to production
$fdb = Net::FluidDB->new(username => 'user', password => 'password');

# FluidDB taking credentials from environment variables
# FLUIDDB_USERNAME and FLUIDDB_PASSWORD
$fdb = Net::FluidDB->new;

# --- Objects ----------------------------------

# create object, with optional about
$object = Net::FluidDB::Object->new(
    fdb   => $fdb,
    about => $unique_about
);
$object->create;
$object->id; # returns the object's ID in FluidDB 

# get object by ID, optionally fetching about
$object = Net::FluidDB::Object->get($fdb, $object_id, about => 1);

# namespaces, tags, and users have objects
$ns->object_id # a UUID
$ns->object    # lazy loaded

# --- Tags -------------------------------------

# create tags
$tag = Net::FluidDB::Tag->new(
   fdb         => $fdb,
   description => $description,
   indexed     => 1,
   path        => $path
);
$tag->create;
$tag->namespace; # lazy loaded

# get tag by path, optionally fetching descrition
$tag = Net::FluidDB::Tag->get($fdb, $tag_path, description => 1);

# tag objects using an existing tag path
$object->tag("fxn/rating", 10);

 # get a tag's value on an object by tag path
$object->tag("fxn/rating"); # => 10

# tag objects using an existing tag object
$object->tag($tag, "foo");

# get a tag's value on an object by tag object
$object->tag($tag); # => "foo"

# sets of strings are passed as arrayrefs of strings, note in the
# example we may get the elements back in different order, that's
# because we store and retrieve sets, not ordered collections
$object->tag($tag, ["a", "b", "c"]);
$object->value($tag); # => ["c", "a", "b"] 

# delete a tag
$tag->delete;

# --- Namespaces -------------------------------

# create a namespace by path
$ns = Net::FluidDB::Namespace->new(
    fdb         => $fdb,
    path        => $path,
    description => $description
);
$ns->create;
$ns->parent # lazy loaded

# delete a namespace
$ns->delete;

# --- Policies ---------------------------------

# raw getter
$policy = Net::FluidDB::Policy->get($fdb, $username, 'namespaces', 'create');

# convenience getter
$policy = Net::FluidDB::Policy->get_create_policy_for_namespaces($fdb, $username);

# checking a policy
$policy->policy('open');
$policy->exceptions(['test']);
$policy->is_open;        # true
$policy->is_closed;      # false
$policy->has_exceptions; # true
$policy->update;

# bulk operations
Net::FluidDB::Policy->open_namespaces;
Net::FluidDB::Policy->close_tags; # sets the exception list to [$self]

# --- Permissions ------------------------------

$perm = Net::FluidDB::Permission->get($fdb, 'namespaces', 'test', 'create');
$perm->policy('open');
$perm->exceptions(['test']);
$perm->is_open;        # true
$perm->is_closed;      # false
$perm->has_exceptions; # true
$perm->update;

# --- User -------------------------------------

$user = Net::FluidDB::User->get($fdb, 'test');
$user->username # => 'test'

DESCRIPTION

Net::FluidDB provides an interface to the FluidDB API.

FluidDB's tagline is "a database with the heart of a wiki". It was launched just a few days ago. Check these pages to know about FluidDB:

The design goal of Net::FluidDB is to offer a complete OO model for FluidDB with a convenience layer on top of it.

ALPHA VERSION & WORK IN PROGRESS

Net::FluidDB is in a very alpha stage:

  • The FluidDB API is partially implemented.

  • The overall interface is taking shape. I consider the basis to be there, but while in alpha the API may change.

  • In particular, since FluidDB is new usage patterns have yet to arise. They may influence the design of the interface.

  • As of this version calls to FluidDB return a status flag. If there was any failure the module only prints the response to STDERR and returns false.

  • The module is underdocumented, to use a generous adjective :-).

AUTHOR

Xavier Noria (FXN), <fxn@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2009 Xavier Noria

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.