NAME

VUser::ResultSet - Data returned by Extension tasks.

DESCRIPTION

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.

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*()

Accumulator 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@gmail.com>

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