Isis 3 Programmer Reference
Isis::PvlConstraints Class Reference

This class can be used to define import/export behavior of Pvl structures when used in the PvlFlatMap class. More...

#include <PvlFlatMap.h>

Collaboration diagram for Isis::PvlConstraints:
Collaboration graph

Public Member Functions

 PvlConstraints ()
 Default constructor for an empty PvlConstraints object. More...
 
 PvlConstraints (const QString &keyListFile)
 Constructs a PvlConstraints object from a file containing PvlKeyword names. More...
 
virtual ~PvlConstraints ()
 Destructor. More...
 
int excludeSize () const
 Returns the number of PvlObjects and PvlGroups to exclude. More...
 
int includeSize () const
 Returns the number of PvlObjects and PvlGroups to include. More...
 
int keyListSize () const
 Returns the number of PvlKeywords to include. More...
 
void addExclude (const QString &name)
 Adds a PvlObject/PvlGroup exclusion constraint. More...
 
void addInclude (const QString &name)
 Adds a PvlObject/PvlGroup inclusion constraint. More...
 
void addKeyToList (const QString &name)
 Adds a PvlKeyword inclusion constraint. More...
 
void addExclude (const QStringList &other)
 Adds multiple PvlObject/PvlGroup exclusion constraints. More...
 
void addInclude (const QStringList &other)
 Adds multiple PvlObject/PvlGroup inclusion constraints. More...
 
void addKeyToList (const QStringList &other)
 Adds multiple PvlKeyword inclusion constraints. More...
 
void addKeyToList (const FileName &fileName)
 Adds PvlKeywords contained in a file to the keyword constraints. More...
 
bool isExcluded (const QString &name) const
 Determines if a PvlObject or PvlGroup is excluded. More...
 
bool isIncluded (const QString &name) const
 Determines if a PvlObject or PvlGroup is included. More...
 
bool isKeyInList (const QString &name) const
 Determines if a PvlKeyword is included. More...
 
const QStringListexcludes () const
 Returns the PvlObject/PvlGroup exclusion constraints. More...
 
const QStringListincludes () const
 Returns the PvlObject/PvlGroup inclusion constraints. More...
 
const QStringListkeyList () const
 Returns the PvlKeyword inclusion constraints. More...
 

Static Public Member Functions

static PvlConstraints withExcludes (const QStringList &excludes)
 Static method to construct a PvlConstraints object from a list of names for the PvlObjects and PvlGroups to exclude. More...
 
static PvlConstraints withIncludes (const QStringList &includes)
 Static method to construct a PvlConstraints object from a list of names for the PvlObjects and PvlGroups to include. More...
 

Private Member Functions

void readKeyListFile (const FileName &fname)
 Reads PvlKeyword inclusion constraints from a file. More...
 

Private Attributes

QStringList m_excludes
 The names of objects and groups excluded (Excludes keyword) More...
 
QStringList m_includes
 The names of objects and groups included (Includes keyword) More...
 
QStringList m_keylist
 The names of keywords to exclusively include (KeyListFile) More...
 

Detailed Description

This class can be used to define import/export behavior of Pvl structures when used in the PvlFlatMap class.

The include/exclude features are applied to PvlObject and PvlGroup structures.

The keylists apply only to keywords.

Behavior beyond what is provided here is the burden of the programmer.

A complete Pvl structure can be provided in the PvlFlatMap class along with a defined PvlConstraints class containing objects/groups that are included or excluded from import operations. Additionally, users can restrict the contents of all keyword containers to a list of keywords as provided in the keylist in this class. It applies to all PVL keyword containers so ensure the list is comprehensive to include all desired keywords from all containers.

Note if any include containers names are specified, all others are excluded by definition. Likewise, if any containers are excluded, all other keywords containers are included by definition. This behavior is defined to be constrained to the PvlObject and/or PvlGroup levels.

A special mode can be defined by using both the include and exclude feature in combination. Include names are preimenent in this mode including only those PVL structures in the include list and excluding PVL structures in the exclude list. If any keywords exist in the keylist, then they are the only keywords mapped from the PVL stuctures in the include list.

Note that if a PvlGroup/PvlObject is excluded, then every PvlGroup/PvlObject contained within it are also excluded. Similarly, in order for a PvlGroup/PvlObject to be included, then any PvlObject that it is contained in must also be included.

Example PVL:

Object = IsisCube
Object = Core
StartByte = 65537
Format = Tile
TileSamples = 128
TileLines = 128
Group = Dimensions
Samples = 704
Lines = 3640
Bands = 5
End_Group
Group = Pixels
Type = Real
ByteOrder = Lsb
Base = 0.0
Multiplier = 1.0
End_Group
End_Object
Group = Instrument
SpacecraftName = "LUNAR RECONNAISSANCE ORBITER"
InstrumentId = WAC-VIS
TargetName = Moon
StartTime = 2009-09-15T07:27:49.230
End_Group
Group = Archive
DataSetId = LRO-L-LROC-2-EDR-V1.0
ProducerId = LRO_LROC_TEAM
ProductId = M107638937CE
End_Group
Group = BandBin
FilterNumber = (3, 4, 5, 6, 7)
Center = (415, 566, 604, 643, 689)
End_Group
End_Object

For the example PVL above, we can do the following:

1) Exclude the Pixels group

PvlConstraints constraints;
constraints.addExclude("Pixels");

2) Include the Pixels group.

PvlConstraints constraints;
constraints.addInclude("IsisCube");
constraints.addInclude("Core");
constraints.addInclude("Pixels");

3) The following will include everything in the Core object (Pixels, Dimensions, and Core keywords).

PvlConstraints constraints;
constraints.addInclude("IsisCube");
constraints.addInclude("Core");

4) In some cases we will have a mix of includes/excludes.

PvlConstraints constraints;
constraints.addInclude("IsisCube");
constraints.addInclude("Core");
constraints.addExclude("Pixels");
Author
2012-07-15 Kris Becker
History:

2012-07-15 Kris Becker - Original version.

2015-03-20 Ian Humphrey - Updated documentation. Added loadContainer method as helper method to loadContainers to make exluding groups function correctly.

2016-02-24 Jeannie Backer - Added unit test. Updated documentation. Fixes #2399

Definition at line 168 of file PvlFlatMap.h.

Constructor & Destructor Documentation

◆ PvlConstraints() [1/2]

Isis::PvlConstraints::PvlConstraints ( )

Default constructor for an empty PvlConstraints object.

Definition at line 46 of file PvlFlatMap.cpp.

◆ PvlConstraints() [2/2]

Isis::PvlConstraints::PvlConstraints ( const QString &  keyListFile)

Constructs a PvlConstraints object from a file containing PvlKeyword names.

Parameters
keyListFileThe name of the file containing PvlKeyword names.

Definition at line 55 of file PvlFlatMap.cpp.

◆ ~PvlConstraints()

Isis::PvlConstraints::~PvlConstraints ( )
virtual

Destructor.

Definition at line 97 of file PvlFlatMap.cpp.

Member Function Documentation

◆ addExclude() [1/2]

void Isis::PvlConstraints::addExclude ( const QString &  name)

Adds a PvlObject/PvlGroup exclusion constraint.

By providing the name of a PvlObject or PvlGroup object, the object will be excluded when creating a PvlFlatMap from a Pvl structure.

Note that if this structure is contained within a PvlObject, then excluding the top level object also excludes all subgroups/subobjects contained within.

Parameters
nameThe name of the PvlObject or PvlGroup to exclude

Definition at line 151 of file PvlFlatMap.cpp.

Referenced by withExcludes().

◆ addExclude() [2/2]

void Isis::PvlConstraints::addExclude ( const QStringList other)

Adds multiple PvlObject/PvlGroup exclusion constraints.

Parameters
otherA list of exclusion contraints

Definition at line 190 of file PvlFlatMap.cpp.

◆ addInclude() [1/2]

void Isis::PvlConstraints::addInclude ( const QString &  name)

Adds a PvlObject/PvlGroup inclusion constraint.

By providing the name of a PvlObject or PvlGroup object, the object will be included when creating a PvlFlapMap from a Pvl structure.

Note that if this structure is contained within a PvlObject, then both must be added to the includes.

Parameters
nameThe name of the PvlObject or PvlGroup to include

Definition at line 167 of file PvlFlatMap.cpp.

Referenced by withIncludes().

◆ addInclude() [2/2]

void Isis::PvlConstraints::addInclude ( const QStringList other)

Adds multiple PvlObject/PvlGroup inclusion constraints.

Parameters
otherA list of inclusion constraints

Definition at line 200 of file PvlFlatMap.cpp.

◆ addKeyToList() [1/3]

void Isis::PvlConstraints::addKeyToList ( const QString &  name)

Adds a PvlKeyword inclusion constraint.

By providing the name of a PvlKeyword, the PvlKeyword will be exclusively included along with any other keyword constraints when creating a PvlFlatMap from a Pvl structure.

Parameters
nameThe QString name of the PvlKeyword to add

Definition at line 180 of file PvlFlatMap.cpp.

◆ addKeyToList() [2/3]

void Isis::PvlConstraints::addKeyToList ( const QStringList other)

Adds multiple PvlKeyword inclusion constraints.

Parameters
otherA list of PvlKeyword names

Definition at line 210 of file PvlFlatMap.cpp.

◆ addKeyToList() [3/3]

void Isis::PvlConstraints::addKeyToList ( const FileName fileName)

Adds PvlKeywords contained in a file to the keyword constraints.

Parameters
nameThe name of the file that contains the PvlKeywords

Definition at line 220 of file PvlFlatMap.cpp.

◆ excludes()

const QStringList & Isis::PvlConstraints::excludes ( ) const

Returns the PvlObject/PvlGroup exclusion constraints.

Returns the values of the Excludes keyword. Excluded PvlObjects and PvlGroups will not be used during the creation of a PvlFlatMap from a Pvl structure. Refer to the PvlFlatMap class documentation for more information.

Returns
QStringList A list of excluded PvlObjects or PvlGroups

Definition at line 279 of file PvlFlatMap.cpp.

◆ excludeSize()

int Isis::PvlConstraints::excludeSize ( ) const

Returns the number of PvlObjects and PvlGroups to exclude.

This method returns the number of values associated with the Excludes keyword.

Returns
int The number of PvlObjects and PvlGroups to exclude

Definition at line 108 of file PvlFlatMap.cpp.

Referenced by Isis::PvlFlatMap::loadGroup(), and Isis::PvlFlatMap::loadObject().

◆ includes()

const QStringList & Isis::PvlConstraints::includes ( ) const

Returns the PvlObject/PvlGroup inclusion constraints.

Returns the values of the Includes keyword. Included PvlObjects and PvlGroups will exclusively be used during the creation of a PvlFlatMap from a Pvl structure. This means anything not included is automatically excluded. Refer to the PvlFlatMap class documentation for more information.

Returns
QStringList A list of included PvlObjects or PvlGroups

Definition at line 294 of file PvlFlatMap.cpp.

◆ includeSize()

int Isis::PvlConstraints::includeSize ( ) const

Returns the number of PvlObjects and PvlGroups to include.

This method returns the number of values associated with the Includes keyword.

Returns
int The number of PvlObjects and PvlGroups to include

Definition at line 120 of file PvlFlatMap.cpp.

Referenced by Isis::PvlFlatMap::loadGroup(), and Isis::PvlFlatMap::loadObject().

◆ isExcluded()

bool Isis::PvlConstraints::isExcluded ( const QString &  name) const

Determines if a PvlObject or PvlGroup is excluded.

Checks if a PvlObject or PvlGroup's name is associated with the Excludes keyword.

Parameters
nameThe name of the PvlObject or PvlGroup
Returns
bool True if the PvlObject or PvlGroup is to be excluded

Definition at line 236 of file PvlFlatMap.cpp.

Referenced by Isis::PvlFlatMap::loadGroup(), and Isis::PvlFlatMap::loadObject().

◆ isIncluded()

bool Isis::PvlConstraints::isIncluded ( const QString &  name) const

Determines if a PvlObject or PvlGroup is included.

Checks if a PvlObject or PvlGroup's name is associated with the Includes keyword.

Parameters
nameThe name of the PvlObject or PvlGroup
Returns
bool True if the PvlObject or PvlGroup is to be included

Definition at line 251 of file PvlFlatMap.cpp.

Referenced by Isis::PvlFlatMap::loadGroup(), and Isis::PvlFlatMap::loadObject().

◆ isKeyInList()

bool Isis::PvlConstraints::isKeyInList ( const QString &  name) const

Determines if a PvlKeyword is included.

Checks if a PvlKeyword's name is associated with the KeyListFile keyword.

Parameters
nameThe name of The PvlKeyword
Returns
bool True if the PvlKeyword is in the KeyListFile

Definition at line 265 of file PvlFlatMap.cpp.

Referenced by Isis::PvlFlatMap::loadKeywords().

◆ keyList()

const QStringList & Isis::PvlConstraints::keyList ( ) const

Returns the PvlKeyword inclusion constraints.

Returns the values of the KeyListFile keyword. Only PvlKeywords that are specified in the KeyListFile will be included during the creation of a PvlFlatMap. Refer to the PvlFlatMap class documentation for more information.

Returns
QStringList A list of PvlKeywords

Definition at line 308 of file PvlFlatMap.cpp.

◆ keyListSize()

int Isis::PvlConstraints::keyListSize ( ) const

Returns the number of PvlKeywords to include.

This method returns the number of values associated with the KeyList keyword. If none of these keyword constraints exist, then all PvlKeywords in a Pvl structure will be included when creating a PvlFlatMap from a Pvl structure.

Returns
int The number of PvlKeywords in the KeyListFile

Definition at line 134 of file PvlFlatMap.cpp.

Referenced by Isis::PvlFlatMap::loadKeywords().

◆ readKeyListFile()

void Isis::PvlConstraints::readKeyListFile ( const FileName keyListFile)
private

Reads PvlKeyword inclusion constraints from a file.

Reads through a file containting PvlKeywords and adds each of the PvlKeyword names as keyword constraints.

Parameters
keyListFile

Definition at line 321 of file PvlFlatMap.cpp.

References Isis::FileName::expanded().

◆ withExcludes()

PvlConstraints Isis::PvlConstraints::withExcludes ( const QStringList excludes)
static

Static method to construct a PvlConstraints object from a list of names for the PvlObjects and PvlGroups to exclude.

Parameters
excludesQStringList of names of PvlObjects or PvlGroups to be excluded.
Returns
PvlConstraints with excludes set from given list.

Definition at line 71 of file PvlFlatMap.cpp.

References addExclude().

Referenced by Isis::Strategy::getDefinitionMap().

◆ withIncludes()

PvlConstraints Isis::PvlConstraints::withIncludes ( const QStringList includes)
static

Static method to construct a PvlConstraints object from a list of names for the PvlObjects and PvlGroups to include.

Parameters
includesQStringList of names of PvlObjects or PvlGroups to be included.
Returns
PvlConstraints with includes set from given list.

Definition at line 87 of file PvlFlatMap.cpp.

References addInclude().

Member Data Documentation

◆ m_excludes

QStringList Isis::PvlConstraints::m_excludes
private

The names of objects and groups excluded (Excludes keyword)

Definition at line 202 of file PvlFlatMap.h.

◆ m_includes

QStringList Isis::PvlConstraints::m_includes
private

The names of objects and groups included (Includes keyword)

Definition at line 203 of file PvlFlatMap.h.

◆ m_keylist

QStringList Isis::PvlConstraints::m_keylist
private

The names of keywords to exclusively include (KeyListFile)

Definition at line 204 of file PvlFlatMap.h.


The documentation for this class was generated from the following files: