NAME

VUser::ResultSet - Data returned by Extension tasks.

DESCRIPTION

VUser::ResultSets are used to return data from vuser extensions. An extension can also use it return errors.

SYSNOPSIS

 my $rs = VUser::ResultSet->new();
 
 $rs->add_meta(VUser::Meta->new(name => "color", type => "string"));
 $rs->add_meta(VUser::Meta->new(name => "size", type => "integer"));
 
 $rs->add_data(["blue", 10]);
 $rs->add_data(["orange", 6]);
 
 # Returning errors
 $rs->error_code(42);
 $rs->add_error("Unknown question: %s",
    'Life, the universe and everything.');
 
 return $rs;

METHODS

Creating the ResultSet

The following methods are used by extensions to create a result set that may be returned from task functions.

new

Create a new ResultSet object.

add_meta(VUser::Meta)

Meta data about the data the task is returning is required so the client can deal with it in a nice way.

add_data([]|{})

add_data() takes either an array reference or hash ref. If it's an array ref, the array must have the same number of entries as the number of meta data entries added with add_meta(). Values but also be in the same order or there will be much confusion.

If a hash reference is passed, the keys must corespond to the names of the meta data added with add_meta(). (Other keys will be ignored.) The number if values must match the number of meta data entries created with add_meta.

Once add_data() has been called, no more meta data may be added to the ResultSet object.

Returning Errors

You can use a ResultSet to return errors from your extension.

error_code($)

Sets the error code for the result to the passed in integer value. If the value passed to error_code() is not an integer, error_code() will complain and leave the error code unset.

add_error($;@)

Adds an error string to the list of errors. The parameters are passed to sprintf for formatting. See "sprintf" in perlfunc for more details.

errors()

Returns the list of errors set by add_error().

Using a ResultSet

These methods are used by apps that call ExtHandler->run_tasks to get the data out of the returned ResultSet(s).

results(%)

Get the results. The parameter is a hash with the following keys.

order_by

The name of the meta data to sort on, if desired. If it's not defined, the results will be returned in the order the extension added them.

sort_order

Value may be one of 'asc' or 'des'. 'asc' means sort in ascending order, 'des' is descending order. Ascending is the default. This has no effect if order_by is not specified or is an unknown column.

get_metadata

Get the list of meta data for this result set. Each value is a VUser::Meta object.

development notes

The following are notes that I wrote while developing this system. They should match reality but aren't guaranteed to.

task() return values.

Return the following info:

extension name (needed?) result set meta value(s)

result set: { meta = [meta1, meta2, ...] values = [ [0] -> [value1, value2, ...] ... [N] -> [value1, value2, ...] ] colmap = { meta1->name => 0, meta2->name => 1, ..., metaN->name => N-1 } current; pointer to current location in data set. used by next(), previous(), current() number of rows } ===

result set methods: @values = results(order_by => meta->name, direction => asc|des) $value[N] = [value1, value2]; where value1 is the data that corresponds to the meta.

 @values = results_hashrefs(order_by => meta->name, direction => asc|des)
        $value[N] = { meta1->name => value1, meta2->name => value2 }

 @meta = get_columns()
 @meta = get_metadata()

 order_by($meta->name, asc|des); sets the sort order for results*()

Iterator interface (do later)

 reset(); reset current pointer to the beginning of the list

 sort($meta->name, asc|des); sort values by given column. Resets pointer

 next(); move the current pointer and return the result or undef if none
 next_hash(); same as above but return the result as a hash

 current(); return the current result
 current_hash()

 back(); move the current pointer back and return the result or undef
 back_hash()

How to add data to result set?

 add_meta(VUser::Meta)
 add_data([value1, value2, ...])
 add_data({meta1->name => value1, meta2->name => value2, ...})

BUGS

There are currently no checks to verify that the data added with add_data() matches the data type specified with add_meta().

AUTHOR

Randy Smith <perlstalker@vuser.org>

LICENSE

 This file is part of vuser.
 
 vuser is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2 of the License, or
 (at your option) any later version.
 
 vuser is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.
 
 You should have received a copy of the GNU General Public License
 along with vuser; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

cpanm VUser::ACL

perl -MCPAN -e shell
install VUser::ACL