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