NAME

ReqFields - class to represent and manipulate requirement schema

AUTHOR

Shane P. McCarron <shane@aptest.com>

COPYRIGHT

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

SYNOPSIS

use ReqFields;

    # create a schema object
    my $rfields = new ReqFields(suiteName);

    # get a handle to the hash of a schema field
    $field = $rfields->field(name);

    # get a handle to a hash of all fields
    $fieldHash = $rfields->field();

    # structure a value in a schema instance
    $output = $rfields->fieldEntry(fieldName, value, edit);

The ReqFields object is a tool to instantiate the schema for a test suite.

METHODS

new - open the ReqFields

$rfields = new ReqFields(suite, edit);

Creates a new schema object.

suite

the name of a test suite to access.

returns a reference to the schema object. Note that if there is no requirements field definition file, an empty object is returned.

edit - get/set the edit flag

$state = $rfields->edit();
    $state = $rfields->edit(boolean);

mode - get/set the mode

$mode = $rfields->mode();
    $mode = $rfields->mode( string );

The mode is one of 'view', 'edit', 'run', 'report'.

multiLists - return a list of multi-select lists

@mlists = $rfields->multiLists() ;

field - get a handle for a field or all fields

$ref = $rfields->field();
    $ref = $rfields->field(name);

fieldList - return a list of defined schema fields

@list = $rfields->flist() ;

Returns the list of fields defined in the schema.

fieldEntryWrap - output an entry, wrapping the content

$output = $rfields->fieldEntryWrap(reqRef, field, value, suffix, fn);

reqRef - reference to a Requirement object

field - the field we are using

value - the value the field has in the test case

suffix - an optional suffix to attach to input elements

fn - pointer to a function to call to wrap each value. The arguments passed to the function are the field name and the value (which may be special in the case of an menu).

fieldEntryVar - output an entry with a special variable suffix

$output = $rfields->fieldEntryVar(test, field, value, suffix, fn);

test - a handle to the test case instance

field - the field we are using

value - the value the field has in the test case

suffix - a suffix to attach to HTML form variable names

fn - the name of a javascript function to call on change

fieldEntry - output an entry for a schema field

$output = $rfields->fieldEntry(test, field, value [, row]);

testcase - reference to a TestCase object

test - a handle to the test case instance

name - the field we are using

value - the value the field has in the test case

row - the row in an inset table. If defined, is used as a suffix for the CGI variable name.

buildSelectorTable - return HTML for an efficiently organised table of selectors

$table = $rfields->buildSelectorTable( currentSelection, allowNonSelectable, showSpecials, showCounts, showDynamic );

The arguments are passed through to fieldSelection().

getSelsFromArgs - build selector collection from an ARGS hash

($testSels, $warnings) = $s->getSelsFromArgs( $hashRef ) ;

hashRef is a reference to a hash of CGI parameters and their values.

If there are any issues with parsing, those issues are pushed into the referenced hash as key_WARNING.

Returns a reference to a hash of selectors suitable for pushing into the selector method, and a string of warnings suitable for displaying (if any).

fieldSelection - return a selection input item for a field

$output = $rfields->fieldSelection( field, currentSelection, allowNonSelectable, showSpecials, showCounts, showDynamic, multiple );

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.

showCounts is a boolean that indicates whether fields that are dynamic counters should be selectable. The default is true.

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.

hRules - set up highlighting rules

$status = $rfields->hRules(field, pattern [, isCaseSensitive [, isRE]]) ;

field is the field to set up rules for.

pattern is the pattern to highlight.

isCaseSensitive indicates the pattern is case sensitive (defaults to no).

isRE indicates the pattern is a regular expression (defaults to no).

Returns 1 if successful, 0 if it failed for some reason, and undef if the field does not exist.

flist - retrieve an ordered list of fields

@list = $rfields->flist();

sortedFlist - get a list of rundata fields ordered by label

@sFlist = $rfields->sortedFlist() ;

Returns a list of field names that are sorted by field label case insensitively.

graphableList - return a list of graphable fields

@slist = $rfields->graphableList( menuOnly [, prefix [, sort ] ] ) ;

menuOnly is a flag that indicates only menu fields should be included in the list. It defaults to false.

prefix is an optional string to attach to the front of the fieldnames.

sort is a flag that indicates the returned list should be sorted by field label. The default is true.

Returns a list of fields that are not hidden and are marked as graphable.

makeValid - method to ensure that the value for a field is valid

$newval = $rfields->makeValid($field, $value);

returns a valid value, which may have been reordered if it is a list field.

nameParts - return a list of fields that are parts of the name

@fList = $rfields->nameParts() ;

Returns an ordered list of the fields that should be used in the displayID of the requirement.

numFields - accessor for the number of fields in a schema

$num = $rfields->numFields();

returns the number of fields defined in a schema

print - print the contents of the ReqFields object field

$rfields->print();
    $rfields->print(field);

returns the string-ified version of the entire database, or just the contents of field

release - release the object

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

selDesc - get a description for a schema selector

$desc = $rfields->selDesc(field, selRef, noShowName, updateDynamic ) ;

field is the name of the field.

selRef is a hash reference to a selector.

noShowName is a boolean. If true, the field name is suppressed. Defaults to false.

updateDynamic is a boolean. If true, dynamic selectors will have their values refreshed before the description is produced. Defaults to true.

Returns a string that is a description of the selection in the context of the field type.

selectableList - return a list of selectable fields

@slist = $rfields->selectableList( menuOnly [, prefix [, sort ] ] ) ;

menuOnly is a flag that indicates only menu fields should be included in the list. It defaults to false.

prefix is an optional string to attach to the front of the fieldnames.

sort is a flag that indicates the returned list should be sorted by field label. The default is true.

Returns a list of fields that are not hidden and are marked as selectable.

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.

sessVars - accessor for session variable values

$val = $rfields->sessVars(vname) ;

Returns the value of the session variable, or undef if the variale is not defined for the session. Also returns undef if the schema object does not have a sessionVarHandle.

suiteDir - accessor for test suite root

$dir = $rfields->suiteDir();
    $rfields->suiteDir(suite);

Gets/sets the path to the test suite data root.

tables - return a list of fields that are "tables"

@tlist = $rfields->tables() ;

typeOf - return the type of a field

$type = $rfields->typeOf(name);

searches the schema for a field with the given name. Returns the type of that field as a string.

valueAsList - return a value as a list

@list = $rfields->valueAsList(fieldName, value) ;

Returns a list that contains all the discrete values from 'value' when interpreted as a field named fieldName. If fieldName is in a table, then appropriate unescaping is done first.

In a scalar context, returns a reference to the list.

valuesOf - return the legal values for a field

@values = $rfields->valuesOf(name);

searches the schema for a field with the given name. Returns an array of legal values for that field.

visibleList - return a list of visible schema fields

@list = $rfields->visibleList() ;

write - write out the schema file

my $status = $rfields->write() ;

Updates the requirement field file for the current suite / profile with the current state of the requirement fields.

Returns 1 on success, 0 on failure.

serialize - create a serialized version of the object

my $text = $rfields->serialize() ;

Returns a text representation of the object, suitable for saving.

idField - accessor for a ref to the idField

$ref = $rfields->idField ( [ $ref ] ) ;

ref is an optional reference to an ID field object. If supplied, that ref is used to update the idField.

Returns the reference to the idField, or undef if there is no field of type id.

inHistory - return whether a field is a component of a history item

$rfields->inHistory(name);

searches the schema for a field with the given name. Returns true if that field is in a history table.

inTable - return whether a field is a component of a table

$rfields->inTable(name);

searches the schema for a field with the given name. Returns true if that field is in a table.

isBulkEditable - return whether a field can be included in the bulk editor

$rfields->isBulkEditable(name) ;

searches the schema for a field with the given name. Returns true if that field should be not bulk editable.

isHidden - return whether a field is hidden.

$rfields->isHidden(name);

searches the schema for a field with the given name. Returns true if that field should be not displayed.

historyTable - find the history table (if any)

my $field = $schema->historyTable();

Returns the name of the field that contains the history table definition.

If there is no historyTable, returns undef.

tableSize - return the number of rows required for a table

my $size = $schema->tableSize(tableName, reqReference);

tableName - the name of a table field.

reqReference - a reference to a requirement object.

Returns the number of rows the table will require. Returns undef if the field is not a table field, does not exist, or has no fields.

historyTextarea - find the field to add system comments to

my $field = $schema->historyTextarea();

Returns the name of the field to put automated revision history entries in.

Chooses the atm_mcomments field if present, and in a history table, otherwise the first textarea in a history table.

Returns undef if no field matches.

isGraphable - return whether a field is graphable

$rfields->isGraphable(name);

searches the schema for a field with the given name. Returns true if the field is graphable, or false if it is not.

isList - return whether a field type is a "list" or not

$rfields->isList(name);

searches the schema for a field with the given name. Returns true if that field is a list type field.

styleOf - return the style of a field

$rfields->styleOf(name);

searches the schema for a field with the given name. Returns the style of that field as a string.

labelOf - return the label of a field

$rfields->labelOf(name [, includeMarkers] );

searches the schema for a field with the given name. Returns the label of that field as a string. if includeMarkers is true, also annotates the label with mandatory and namepart markers.

isNamepart - return whether a field is part of the name

$rfields->isNamepart(field)

Searches the requirement fields for a field named field. Returns true if the field is a namepart, or false if it is not.

isNumber - return whether a field is to be treated as numeric

$rfields->isNumber(field)

Searches the requirement fields for a field named field. Returns true if the field has a numeric style, or false if it does not.

isOutline - return whether this suites's requirements are in outline mode

$rfields->isOutline()

Returns true if the requirements are using outline numbering mode, and false if not. Returns undef if there is no ID field (which is, of course, impossible).

isSelectable - return whether a field is selectable

$rfields->isSelectable(name);

searches the schema for a field with the given name. Returns true if the field is selectable, or false if it is not.

isVisible - return whether a field is visible for reports

$rfields->isVisible(name);

searches the schema for a field with the given name. Returns true if the field is visible in reports.

getFieldsByType - get a list of fields of a given type and/or style

$rfields->getFieldsByType(type[,style]);

searches the schema for fields of a given type, and optionally a given style. Returns a list of field names.

javaScriptDependencies - determine the dependency rules for JS

Returns JavaScript code that defines the dependencies among schema fields for use in the schema editor and also in selector pages.

SQL_tname - table name accessor

my $tname = $rfields->SQL_tname ;

SQL_value - do a SQL transformation on a value for a field

my $val = $field->SQL_value($val) ;

Returns the value of the field after interpretation by TestDB object.

METHODS

new - create a Field object

$field = new ReqFields::Field(hash);

Creates a new Field object and associates its attributes with the object.

hash

a hash of field attributes

returns a reference to the Field object.

name - return the name of the field

$name = $field->name();

isBulkEditable - is this field simple?

$field->isBulkEditable();

cantSelect - see if a field is not selectable inherently

$field->cantSelect();

canSearch - see if a field is string searchable

$field->canSearch();

default - get/set the default value for a field

$default = $field->default();

descs - retrieve the list of descriptions associated with a schema field

@descs = $field->descs();

descOf - return the description of a value

$desc = $field->descOf($value) ;

Returns the associated description if the variable is a list. If value if a reference to an array, then returns a reference to an array of descriptions.

getFlags - create a FLAGS field from settings

$flags = $field->getFlags();

Returns a value for the FLAGS field of a SCHEMA2 file.

hidden - is this field hidden?

$field->hidden();

highlight - highlight data that matches field rules

If there are hRules defined for the field, highlight the data that matches those rules.

$output = $field->highlight($input) ;

input is a string to highlight.

Output is returned with any matching data highlighted.

prepHighlight - mark areas that match field highlighting rules

If there are hRules defined for the field, mark the data that matches those rules, ready for doHighlight() later.

$output = $field->highlight( input, displayStr );

input is a string to highlight.

if displayStr is specified, then if input matches a rule, display displayStr instead, highlighted. This is used for menu fields.

Returns input (or displayStr, where appropriate) with matching areas bounded by \03 and \04.

doHighlight - add HTML for highlighting fields

$output = $field->doHighlight( value );

value is the string to process.

Returns value, after replacing \03 and \04 (inserted by prepHighlight) with HTML for applying highlighting.

If the field is markup, doHighlight also escapes the markup so the field is displayed "as is".

graphable - get/set the graphable flag for a field

$graphable = $field->graphable();

hRules - set up highlighting rules

$status = $field->hRules(pattern [, isCaseSensitive [, isRE]]) ;

pattern is the pattern to highlight.

isCaseSensitive indicates the pattern is case sensitive (defaults to no).

isRE indicates the pattern is a regular expression (defaults to no).

Returns 1 if successful, 0 if it failed for some reason.

inHistory - what history list is this field within?

$field->inHistory( [ fname ] );

fname - the name of the field.

inTable - what table is this field within?

$field->inTable( [ fname ] );

fname - the name of the field.

isDate - is this field a date type

$field->isDate() ;

Returns 1 if the field is date only, 2 if it is a date/time field, and 0 if it is neither.

isList - is this field a list type

$field->isList();

isNumber - is this field treated as a number for sorting purposes

$field->isNumber();

Note that there are a number of numeric "styles".

isRange - is this field a bounded range

$field->isRange();

isMarkup - does this field contain markup (eg HTML)

$field->isMarkup();

isTable - is this a table type field

$field->isTable();

isText - is this a freeform field

$field->isText();

isImportable - can this field be imported into?

$field->isImportable();

Returns false for table fields, and any built-in fields marked as not importable, and true for anything else.

label - get/set the label for a field

$label = $field->label();

selectable - get/set the selectable flag for a field

$selectable = $field->selectable();

searchable - is it searchable

$searchable = $field->searchable();

fixFlags - ensure that any reserved settings are maintained

$field->fixFlags() ;

Returns nothing.

setFlags - set various flags by parsing a "FLAGS" field

$field->setFlags(flags);

Returns nothing

size - get/set the size for a field

$size = $field->size(size);

Returns the current size of the field.

sizeAsHtml - get the size for a field

$size = $field->sizeAsHtml(limit);

returns a string suitable for use in the appropriate input element.

type - get/set the type for a field

$type = $field->type();

importable - get/set the importable flag for a field

$importable = $field->importable();

prompt - get/set the prompt for a field

$prompt = $field->prompt();

valMap - return a hash map of descriptions to values

$mapRef = $field->valMap() ;

Returns a reference to a hash that maps descriptions to values. Caches the map so that subsequent lookups are faster.

valueOf - return the value for a description

$val = $field->valueOf($desc) ;

desc is the value to describe.

Returns the associated value if the variable is a list. If desc if a reference to an array, then returns a reference to an array of descriptions.

values - retrieve the list of values associated with a schema field

@vlist = $field->values();

valuesList - accessor for list of values

@vlist = $field->valuesList( [ $lRef ] ) ;

lRef is an optional reference to a list of values. If supplied, the stored list of values will be updated.

Returns a list of values.

style - get/set the style associated with a schema field

$style = $field->style();

visible - get/set the visible flag for a field

$visible = $field->visible();

release - release the object

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

AUTOLOAD - catchall for undefined methods

$value = $field->WHATEVER();

    $value = $field->WHATEVER(newvalue);

Updates the setting of the WHATEVER attribute. Returns the current or new setting.

DESTROY() - tidy up

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