Schema - class to represent and manipulate test suite schemas
Shane P. McCarron <shane@aptest.com>
Copyright 1999-2011 Applied Testing and Technology, Inc. All Rights Reserved.
use Schema; # create a schema object my $schema = new Schema(suiteName); # get a handle to the hash of a schema field $field = $schema->field(name); # get a handle to a hash of all fields $fieldHash = $schema->field(); # structure a value in a schema instance $output = $schema->print(fieldName, value, edit);
The Schema object is a tool to instantiate the schema for a test suite.
$schema = new Schema(suite, edit);
Creates a new schema object.
the name of a test suite to access.
returns a reference to the schema object.
@descs = $schema->descsOf(name);
searches the schema for a field with the given name. Returns an array of legal descriptions for that field.
$schema->delRow(testCase, fieldName, row);
testCase is a handle to a test case.
fieldName is the name of the field.
row is the row number to delete. If row is greater than the number of rows defined in a table, the command is silently ignored.
$state = $schema->edit(); $state = $schema->edit(boolean);
$mode = $schema->mode(); $mode = $schema->mode( string );
The mode is one of 'view', 'edit', 'run', 'report'.
@mlists = $schema->multiLists() ;
$ref = $schema->field(); $ref = $schema->field(name);
@list = $schema->fieldList() ;
Returns the list of fields defined in the schema.
$output = $schema->fieldEntryWrap(testcase, test, field, value, fn);
testcase - reference to a TestCase object
test - a handle to the test case instance
field - the field we are using
value - the value the field has in the test case
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).
$output = $schema->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
$output = $schema->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.
$table = $schema->buildSelectorTable( currentSelection, allowNonSelectable, showSpecials, multiple, showDynamic );
The arguments are passed through to fieldSelection().
($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).
$output = $schema->fieldSelection( field, currentSelection, allowNonSelectable, showSpecials, $multiple, $showDynamic );
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.
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.
$output = $schema->fieldPrint(fname, ref, useLabels) ;
fname is the name of the field
ref is a reference to a selector-style hash (pat, isCS, isRE).
useLabels is true if the label should be emitted as well.
Returns the output formatted appropriately for the field. Note that this does not work with field type "table", since that is necessarily only emitted in the context of a test case.
$status = $schema->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.
@list = $schema->flist();
@sFlist = $schema->sortedFlist() ;
Returns a list of field names that are sorted by field label case insensitively.
$schema->insRow(testHandle, fieldName, rowNumber);
testHandle - a Framework handle to an active test case
fieldName - the name of the field in the schema
rowNumber - the row to insert before. If not defined, then just add a row to the end.
looks up fieldName in the current schema, finds the associated fields, and performs the operation on those fields
$newval = $schema->makeValid($field, $value);
returns a valid value, which may have been reordered if it is a list field.
@fList = $schema->nameParts() ;
Returns an ordered list of the fields that should be used in the displayID of the requirement.
$num = $schema->numFields();
returns the number of fields defined in a schema
$schema->print(); $schema->print(field);
returns the string-ified version of the entire database, or just the contents of field
Really a no-op, since this object does not have a database.
$desc = $schema->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.
@slist = $schema->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.
Gets/sets a handle to a test session from which variables can be extracted and interpolated into field values during formatting.
$val = $schema->sessVars(vname) ;
Returns the value of the session variable, or undef if the variable is not defined for the session. Also returns undef if the schema object does not have a sessionVarHandle.
$newstr = stripBR($oldStr) ;
Removes any trailing BR elements. Note that this is just a function, not an object method.
$dir = $schema->suiteDir(); $schema->suiteDir(suite);
Gets/sets the path to the test suite data root.
@tlist = $schema->tables() ;
$type = $schema->typeOf(name);
searches the schema for a field with the given name. Returns the type of that field as a string.
$bool = $schema->usesStaffTime() ;
Returns true if staff time tracking is active for the suite.
$bool = $schema->usesClockTime() ;
Returns true if clock time tracking is active for the suite.
@list = $schema->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.
@values = $schema->valuesOf(name);
searches the schema for a field with the given name. Returns an array of legal values for that field.
@list = $schema->visibleList( [ $sort ] ) ;
my $status = $schema->write() ;
Updates the schema file for the current suite / profile with the current state of the schema.
Returns 1 on success, 0 on failure.
my $text = $schema->serialize() ;
Returns a text representation of the object, suitable for saving.
$ref = $schema->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.
$schema->inHistory(name);
searches the schema for a field with the given name. Returns the name of the history field a field is contained within, or false if the field is NOT in a history table.
$schema->inTable(name);
searches the schema for a field with the given name. Returns true if that field is in a table.
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.
$schema->isBulkEditable(name) ;
searches the schema for a field with the given name. Returns true if that field should be not bulk editable.
$schema->isHidden(name);
searches the schema for a field with the given name. Returns true if that field should be not displayed.
$schema->isList(name);
searches the schema for a field with the given name. Returns true if that field is a list type field.
$schema->styleOf(name);
searches the schema for a field with the given name. Returns the style of that field as a string.
$schema->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.
$schema->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.
$schema->isNamepart(field)
Searches the test case fields for a field named field. Returns true if the field is a namepart, or false if it is not.
$schema->isNumber(field)
Searches the test case fields for a field named field. Returns true if the field has a numeric style, or false if it does not.
$schema->isOutline()
Returns true if the test cases are using outline numbering mode, and false if not. Returns undef if there is no ID field (which is, of course, impossible).
$schema->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.
$schema->isVisible(name);
searches the schema for a field with the given name. Returns true if the field is visible in reports.
$schema->getFieldsByType(type[,style]);
searches the schema for fields of a given type, and optionally a given style. Returns a list of field names.
Returns JavaScript code that defines the dependencies among schema fields for use in the schema editor and also in selector pages.
my $tname = $schema->SQL_tname ;
Copyright © 2000-2013 Applied Testing and Technology, Inc. All rights reserved.