ReqCollection - class representing a subset of requirements


Shane P. McCarron <>


Copyright 2002-2011 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.

new - create a collection

buildSelectorTable - create a table of selector fields

$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.

collname - accessor for the collection name


returns the name of the collection.

ctime - accessor for the creation time


returns the creation time

displayID - get the displayable ID for a requirement

$idString = $coll->displayId($tid [, noPath [, asText [, onClick ] ] ] )

Returns the "name" of the requirement with ATM suffixes removed and whitespace inserted after slashes. Defers to the displayIDByUUID method of reqDB.

idx is the requirement index in the collection.

For other options, see "displayIDByUUID" in ReqDB.

field - get the fieldlist


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.

fieldSelection - return a selection input item for a field

$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 - get a list of collection record fields

@flist = $coll->flist() ;

Returns an array of field names.

idsAsStrings - treat ID fields as text strings?

$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).

mtime - accessor for the modification time


returns the last modification time.

numreqs - accessor for the number of requirements


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

count - accessor for the number of requirements


See numreqs.

orAmongFields - accessor for OR vs. AND in searches

$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.

path - get the path to the collection


print - print the contents of the session


returns the string-ified version of the entire session, or just the contents of requirement reqNum, if specified.

refresh - reset the matching requirements list


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.

release - release the object and anything it opened


Releases any resources aquired while processing.

Returns the result of calling SUPER::release.

reqById - return requirement index # given its name

$ridx = $coll->reqById( id );

returns the requirement index corresponding to the given name

reqByUUID - return requirement index # given its uuid

$ridx = $coll->reqByUUID( uuid );

returns the requirement index corresponding to the given uuid

reqList - retrieve the complete list of req IDs

@list = $session->reqList();

returns an ordered list of req IDs.

reqRecord - accessor for requirement attributes

$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:


the ID of the requirement (relative path to requirement root)


The UUID for the requirement

returns the handle to the requirement record. If num is not defined, returns the handle to all requirement records.

reqUUIDList - retrieve the complete list of req UUIDs

@list = $session->reqUUIDList();

returns an ordered list of req UUIDs.

save - save the collection

$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.


selector - accessor for selector attributes

$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.

searchAndReplace - are we doing search and replace?

$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).

selectReqs - select requirements that match the "selectors"

$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 requirements selected.

suffix - accessor for the suffix to use for fields

$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.

sortKeys - accessor for requirements collection sorting rules


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!

stringMatch - check to see if a string matches

$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.

SQL_createQuery - construct a SQL query for use by _getTests

my $query - $coll->SQL_createQuery();

Returns a query that will return a list of requirements based upon selectors.



ReqCollection::Field - class representing a requirement collection field


new - create a new Field object

$field = new ReqCollection::Field(name) ;

Creates a field object. Returns a reference to the created object.

Copyright © 2000-2013 Applied Testing and Technology, Inc. All rights reserved.