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

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

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

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

   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"

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

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

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

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

$req->init() ;

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

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

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

$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

$boolean = $req->fromDisk();

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

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

$path = $req->path()

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

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

returns 1 if the save succeeded.

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

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

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

returns the value of the field.

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

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

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