ReqCollection
ReqCollection |
|
ReqCollection - class representing a subset of requirements
Shane P. McCarron <shane@aptest.com>
Copyright 2002-2007 Applied Testing and Technology, Inc. All Rights Reserved.
use ReqCollection ;
# create an empty collection
my $coll = new ReqCollection();
# get the settings for a selector
$setRef = $coll->selector($field);
# set the value of a selector
$value = $coll->selector($field, $value);
# find requirements that match
@list = $coll->search() ;
A ReqCollection is similar to a TestSession. It is used to create ephemeral subsets when performing requirement searches.
$tableStr = $coll->buildSelectorTable( reqsel, allowNS, showSpecials) ;
reqsel is a reference to a set of selectors
allowNS is a boolean - if true, non-selectable fields are included.
showSpecials is a boolean. If true, then special modifies are show as well.
showDynamic is a boolean. If true, then fields that can have dynamic selectors will show those options. Defaults to false.
Returns a table that includes all of the selectors, with any items in the passed in selector set pre-selected.
$coll->collname();
$coll->collname(value);
returns the name of the collection.
$session->ctime();
$session->ctime(value);
returns the creation time
$coll->field(fname);
returns a reference to the descriptors for the requested field. If no field name is passed in, returns a reference to the entire collection of fields.
$output = $coll->fieldSelection($field, $currentSelection, $allowNonSelectable, $showSpecials, $showLabels);
field is the field to present
currentSelection is a reference to an array of existing selections or a comma-separated string of current selections.
allowNonSelectable is a boolean that indicates whether even non-selectable fields should be presented (for use in report and edit selectors).
showSpecials is a boolean that indicates whether the special isCS and isRE selectors should also be shown on items that support those flags.
showLabels is a boolean that indicates whether the prompt should be supplied. If so, then the prompt and request are emitted as table cells. If not, then the input fields are just emitted as markup.
showDynamic is a boolean that indicates whether fields that can have dynamic selectors should show these as options. The default is false.
returns an input field appropriate for the field. If $field is empty, returns an empty string. If the field doesn't exist, returns undef. if field is not selectable, returns an empty string.
@flist = $coll->flist() ;
Returns an array of field names.
$val = $session->idsAsStrings();
$val = $session->idsAsStrings( 1 );
If set to true, ID field selectors are treated just like normal strings. If set to false, it does its usual special handling of ID selectors.
Returns the current value (default 0).
$session->mtime();
$session->mtime(value);
returns the last modification time.
$coll->numreqs();
$coll->numreqs(value);
While you can set the number of requirements in the collection with this method, it is generally not a good idea unless you really know what you are doing.
Returns the number of requirements in the session
$val = $session->orAmongFields();
$val = $session->orAmongFields(true | false);
If this flag is set to true, then the selectTests function will do an OR among the selectors instead of requiring AND among the selectors.
Returns the current value.
returns a path to a saved collection. NOTE THAT AT THIS TIME THERE IS NO MECHANISM TO SAVE REQUIREMENT COLLECTIONS.
$coll->print();
$coll->print(reqNum);
returns the string-ified version of the entire session, or just the contents of requirement reqNum, if specified.
$coll->refresh();
This method will rerun the _getReqs logic and grab any new requirements that match the original criteria and are NOT marked as disabled already in the object. It will also remove any requirements that no longer match the selection criteria, including removing them from the "disabled" collection.
$ridx = $coll->reqById( id );
returns the requirement index corresponding to the given name
$ridx = $coll->reqByUUID( uuid );
returns the requirement index corresponding to the given uuid
@list = $session->reqList();
returns an ordered list of req IDs.
$coll->reqRecord(num, dataHash);
num is the ordinal of the requirement in the record.
dataHash is a hash of fields for the requirement record. If you "undef" a field, then its contents will be removed.
Defined attributes for a requirement record include:
returns the handle to the requirement record. If num is not defined, returns the handle to all requirement records.
$result = $set->save(dbmFlag, collName);
dbmFlag - a boolean that indicates whether it should be a DBM or not. note that this is currently ignored - test sets are always serialized objects, not DBM files.
collName - the name to use for a new collection.
Returns 1 on success, and 0 on failure.
NOTE THAT THERE IS CURRENTLY NO MECHANISM FOR SAVING COLLECTIONS IN THE PRODUCT.
$coll->selector(reqField, value);
returns pointer to selector
if reqField is not defined, then it returns a reference to a hash of all the selectors. The value of each hash element is an array of selected values for that field.
$val = $coll->searchAndReplace();
$val = $coll->searchAndReplace( 1 );
If this flag is set to true, then the selectReqs function will allow pattern matching and case sensitivity for menu fields, and will treat 'any' as a regular non-special value. Will also expand username to full names for matching.
Returns the current value (default 0).
$coll->selectReqs( [ collection [, sortIt [, resRef ] ] );
collection is an optional arrayref of requirement IDs to select from.
sortIt is an optional boolean that indicates whether to sort the results. If not provided, defaults to true.
resRef is an optional reference to a hash of requirement data including lists of results. The hash is keyed by UUID. If provided, this reference is passed on to _getReqs, where it is used to filter if there are filters defined for the various categories of results.
returns the number of tests selected.
$suff = $coll->suffix() ;
$suff = $coll->suffix($newsuff) ;
Returns the current suffix, after updating it if the suffix is supplied. The suffix is appended to input field variable names if, for example, the fields are being put into a complex form that reflects multiple requirements.
$coll->sortKeys();
$coll->sortKeys(\@keys);
Gets/sets the ordered list of keys on which the session should be sorted.
Each item starts with a + or a -, indicating whether the sort on that field is ascending or descending.
Note that the sort key is NOT persistent!
$res = stringMatch(value, reference) ;
value is the string to check.
reference is a reference to a single selector.
Returns true if the selector criteria matches the value.
ReqCollection::Field - class representing a requirement collection field
$field = new ReqCollection::Field(name) ;
Creates a field object. Returns a reference to the created object.
Copyright © 2000-2007 Applied Testing and Technology, Inc. All rights reserved.