NAME

Requirement - object representing a requirement

AUTHOR

Shane P. McCarron <shane@aptest.com>

COPYRIGHT

Copyright 2002-2011 Applied Testing and Technology, Inc. All Rights Reserved.

SYNOPSIS

use Requirement;

Create an empty requirement
my $req = new Requirement();

# get the value of a field
$value = $req->valueOf(field)

# set the value of a field
$value = $req->valueOf(field, value)

# get/set the location of the requirement
$value = $req->path(value)

# save the Requirement
$res = $req->save();

The Requirement object permits creation of/access to a requirement and its contents. Such objects can be used to create new requirements, read existing requirements, or update existing requirements.

The data structure uses hashs to capture the majority of the field data. However, since field data is "ordered", there is also an index array that keeps track of the order in which the data was read/created, and should be emitted if the save or print methods are called.

DATA STRUCTURE

path

the path to the requirement.

lock

a handle to the lock that is set for the object.

writeable

a boolean that indicates whether the testcase is open read/write. Note that this does not really effect the way in which the file is opened - the file is only opened when it is read in. This controls whether the file can be updated.

reqDB

a handle to an associated requirements database. If defined, the methods will use and update an associated ReqDB object. See ReqDB for more information.

fields->[ ]

an ordered list of field identifiers.

data->

a hash of fields and their values. {data}->{name}

METHODS

new - create a new Requirement object

$req = new Requirement()
$req = new Requirement(suite)
$req = new Requirement(suite, path)
$req = new Requirement(suite, path, readWrite)
$req = new Requirement(suite, path, readWrite, reqDbHandle)
$req = new Requirement(suite, path, readWrite, reqDbHandle, rfields)

suite is the test suite in which we are operating

path is the pathname for the requirement within the suite.

readWrite is a boolean that indicates whether the object should be writeable.

reqDbHandle is a ref to a ReqDB object. If it is not provided, a reqDB will be opened, used, and released automatically.

rfields is a ref to a RFields object. If it is not provided, one will be opened, used, and released automatically.

newByName - open a requirement using its path name

$req = newByName Requirement(suite, path)
$req = newByName Requirement(suite, path, readWrite)
$req = newByName Requirement(suite, path, readWrite, reqDbHandle)

suite is the test suite in which we are operating

path is a relative path name of a requirement file to open.

readWrite is a boolean that indicates whether the object should be writeable.

reqDbHandle is a ref to a ReqDB object. If it is not provided, a reqDB will be opened, used, and released automatically.

rfleids is a ref to a RFields object. If it is not provided, one will be opened, used, and released automatically.

generateCSV - uses Text::CSV_XS to generate CSV data of field values.

$csv = $test->generateCSV(\@fields [,$raw [,bursttables] ]) ;

   where

'fields' is a reference to an array holding field names. These are used
for an initial legend.

'raw' is a scalar holding either 0 (the values are coded), or 1 (the values
are "raw"

'burstTables' is a boolean.  If true then fields that are in a table will have 
their rows split apart and multiple rows emitted.

generateMarkup - generate an HTML page for the contents of this requirement

generateMarkup walks through all the fields defined in a requirement, emitting the HTML associated with those fields. It does this in SCHEMA order, regardless of the order of the fields in the requirement itself.

$output = $req->generateMarkup(template, showValues, showLabels);

template is the template to populate.

showValues is a boolean flag that indicates whether the values of session variables should be interpolated. If true, values are ONLY interpolated if there is also a session associated with this requirement object.

showLabels is a boolean flag indicating whether field labels should be included in the output.

fieldList is a comma-separated list of field names in which values should be highlited if they are present.

pattern is a reference to a hash describing the pattern to highlight. The hash has three elements; pat is a string; isRE indicates if it is a regular expression; isCaseSensitive indicates if it is case sensitive.

returns the generated output, or undef if the output could not be generated.

generateMarkupWithResults - generate an HTML fragment for the contents of this requirement

generateMarkupWithResults walks through all the fields in a template, emitting the HTML associated with those fields.

$output = $req->generateMarkupWithResults(template, showValues, showLabels, $resAryRef);

template is the template to populate.

showValues is a boolean flag that indicates whether the values of session variables should be interpolated. If true, values are ONLY interpolated if there is also a session associated with this requirement object.

showLabels is a boolean flag indicating whether field labels should be included in the output.

resAryRef is a reference to a list of results associated with a requirement.

returns the generated output, or undef if the output could not be generated.

generateXLS - uses Spreadsheet::Write to generate Excel data of field values.

$count = $req->generateXLS($worksheet, $lastRow, \@fields [,$raw [, $burstTables] ]) ;

worksheet is a reference to a Spreadsheet::WriteExcel worksheet object.

lastRow is the number of the last row in that spreadsheet.

fields is a reference to an array holding field names. These are used for an initial legend.

raw is a scalar holding either 0 (the values are coded), or 1 (the values are "raw"

burstTables is a boolean. If true then fields that are in a table will have their rows split apart and multiple rows emitted.

Returns the number of rows added to the worksheet.

generateXML - generate XML-formatted data $xml = $test->generateXML(\@fields [,$raw]) ;

   where

'fields' is a reference to an array holding field names. These are used 
for element names.

'raw' is a scalar holding either 0 (the values are coded), or 1 (the values
are "raw"

dirtyFlag - accessor for the flag indicating if data has changed.

$req->dirtyFlag();
$req->dirtyFlag(1|0) ;

Calling this method with no arguments will return whether or not any data has changed since the ojbect was originally created.

When ever you DO change part of the object (most notably "data") you should call this method with the true value.

displayID - return a displayable ID

$theID = $req->displayID( [ noPath [, asText [, onClick ] ] ] ) ;

noPath is an optional boolean flag that indicates whether to include the path in the ID. It defaults to false.

asText is an optional boolean flag that indicates whether to return a straight text version of the ID. It defaults to false.

onClick is an optional string to use in an onclick handler for the ID. If supplied, the ID is wrapped in a span with the appropriate onClick text.

Returns a version of the requirement ID that is designed to be displayed.

id - get aggregate ID of requirement

$id = $req->id( [$path] ) ;

path is an optional path for the test suite. If not provided, will grab the path from the object.

Returns the ID of the requirement. This is an aggregate of the path to the requirement, coupled with fields in the requirements schema that are marked as id components.

identifier - get/set the formal identifier of the requirement

$ident = $requirement->identifier(myID);

The identifier is the unique, test suite relative path name for the requirement.

init - initialize the requirement with common data

$req->init() ;

Establishes values for common fields and empty values in all other fields in an empty requirement.

lastValueOf - extract or append the last value of a field in a table

$last = $req->lastValueOf(field) ;
$last = $req->lastValueOf(field, value) ;

Returns the last value of a field. If the field is NOT in a table, just returns the field's value. If the field does not exist, or the field has no value, returns undef.

If a value is supplied, appends a value to the field if it's a table field, otherwise just replaces the value. (Note that it doesn't keep the other fields in the row in sync - that's up to the calling code.)

locked - accessor for requirement locked state

$locked = $req->locked( [state] )

state is the optional state for the locked flag. 1 for locked, 0 for unlocked.

Returns the current state of the flag.

addHistory - add a history entry

$req->addHistory( message [, user ] ) ;

message is a message to put in the history list.

user is an optional username. Defaults to the current user.

Adds an entry to the history table if there is one. Updates the muser and mdate fields to be the current user.

populate - populate all fields of a requirement with content

$req->populate() ;

Selects random values for all menu fields. Creates random text content for text fields, and random paragraphs for textareas. For tables, ensures that there are several rows

fromDisk - get/set the flag for whether the test is from disk or not

$boolean = $req->fromDisk();

Returns a boolean indicating whether or not the test was read from its source file on the disk.

mtime - accessor for the modification time of the source

$time = $req->mtime();
$time = $req->mtime(time);

path - the pathname of the test object

$path = $req->path()

release - release the object

Really a no-op, since this object does not have a database.

clear - clear a requirement's data

$req->clear();
$req->clear( exclusions );

clear() deletes all the data in a requirement, with the exception of the 'id' 'atm_rid' fields. If an arrayref of field names is passed to clear(), those fields are also not cleared.

save - save the requirement object

returns 1 if the save succeeded.

session - accessor for a session handle

Gets/sets a handle to a test session from which variables can be extracted and interpolated into field values during formatting.

UUID - get the UUID for a requirement

$uuid = $req->UUID() ;

returns the value of the UUID field from the requirement. If there is not yet a UUID field, creates a new UUID for the requirement, updates the requirement, and returns that value.

returns undef if the requirement was not opened in write mode or if we no longer have a handle to a requirement database AND we need to create the UUID.

rawValue - get the raw value of a field

$val = $req->rawValue(field);

returns the value of the field.

valueAsList - get the value of a field as a list

@list = $req->valueAsList(field) ;

Returns the value for the field as a list, having split the items up if the field is of the appropriate type.

valueOf - get/set the value of a field

$val = $req->valueOf(field);
$val = $req->valueOf(field, value);

returns the value of the field. If the field was not previously defined, then the value is set AND the field is appended to the ordered list of fields in $req->{fields}.

If the value is a "list" field according to the rfields, then we use the rfields object to reorder the values into a legal set that is in the rfields defined order BEFORE we store it.

valueOfAsText - return the value of a field in text form

$val = $req->valueOfAsText( field ) 

field is the name of a field to get the value for. Ensures the field data is properly formatted, then transforms it into text form laid out as best it can.

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