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:

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 QStringList &	excludes () const
	Returns the PvlObject/PvlGroup exclusion constraints. More...

const QStringList &	includes () const
	Returns the PvlObject/PvlGroup inclusion constraints. More...

const QStringList &	keyList () 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

keyListFile The 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

name	The 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

other A 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

name	The 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

other A 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

name	The 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

other A 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

name	The 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

name	The 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

name	The 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

name	The 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

excludes QStringList 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

includes QStringList 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:

src/base/objs/PvlFlatMap/PvlFlatMap.h
src/base/objs/PvlFlatMap/PvlFlatMap.cpp

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ PvlConstraints() [1/2]

◆ PvlConstraints() [2/2]

◆ ~PvlConstraints()

Member Function Documentation

◆ addExclude() [1/2]

◆ addExclude() [2/2]

◆ addInclude() [1/2]

◆ addInclude() [2/2]

◆ addKeyToList() [1/3]

◆ addKeyToList() [2/3]

◆ addKeyToList() [3/3]

◆ excludes()

◆ excludeSize()

◆ includes()

◆ includeSize()

◆ isExcluded()

◆ isIncluded()

◆ isKeyInList()

◆ keyList()

◆ keyListSize()

◆ readKeyListFile()

◆ withExcludes()

◆ withIncludes()

Member Data Documentation

◆ m_excludes

◆ m_includes

◆ m_keylist