idaeim studio
 PVL: Parameter Value Language

Classes | Public Types | Public Member Functions | Static Public Member Functions
Aggregate Class Reference

An Aggregate implements a Parameter that is a list of Parameters. More...

#include <Parameter.hh>

Inheritance diagram for Aggregate:
Inheritance graph
[legend]
Collaboration diagram for Aggregate:
Collaboration graph
[legend]

List of all members.

Classes

class  Depth_Iterator
 A Depth_Iterator is a bidirectional iterator over an Aggregate's Parameter list and, depth-first, over the Parameter list of each Aggregate encountered. More...

Public Types

enum  {
  CASE_INSENSITIVE,
  CASE_SENSITIVE
}
 Flags for find case sensitivity argument. More...
typedef
Parameter_List::const_iterator 
const_iterator
 Identify the iterator for compilers that need help.
typedef Depth_Iterator depth_iterator
 A specialized iterator that descends into Aggregates in the Parameter list.
typedef Parameter_List::iterator iterator
 Identify the iterator for compilers that need help.
typedef Vectal< ParameterParameter_List
 Aggregate as a Vectal (vector) of Parameters.

Public Member Functions

Aggregateadd (const Parameter &parameter)
 Adds a clone of the Parameter to the end of the Aggregate's Parameter list.
Aggregateadd (Parameter *parameter)
 Adds the Parameter to the end of the Aggregate's Parameter list.
 Aggregate (const Aggregate &aggregate)
 Copy constructor.
 Aggregate (Parser &parser, const std::string name="")
 Constructs an Aggregate using a Parser to provide its contents.
 Aggregate (const std::string name="", const idaeim::PVL::Parameter::Type type_code=Default_Subtype)
 Constructs an empty Aggregate.
 Aggregate (const Parameter &parameter)
 Copy constructor from a Parameter.
Depth_Iterator begin_depth ()
 Gets a Depth_Iterator positioned at the beginning of this Aggregate.
Aggregateclone () const
 Clones the Aggregate by making a copy of itself.
int compare (const Parameter &parameter) const
 Compares this Aggregate with another Parameter.
Aggregatecopy_in (const Aggregate &aggregate)
 Copies the Parameter list in an Aggregate into this Aggregate's list.
Depth_Iterator end_depth ()
 Gets a Depth_Iterator positioned at the end of this Aggregate.
void entering (Parameter *parameter)
 Sets the parent of a Parameter to this Aggregate.
Parameterfind (const std::string &pathname, bool case_sensitive=false, int skip=0, idaeim::PVL::Parameter::Type type=(Type)(ASSIGNMENT|AGGREGATE)) const
 Find a named Parameter.
bool is (const Type type) const
 Test if the Parameter is of some Type.
bool is_Aggregate () const
 Test if this is an Aggregate.
bool is_Group () const
 Test if this is a Group Aggregate.
bool is_Object () const
 Test if this is a Group Aggregate.
Aggregatemove_in (Aggregate &aggregate)
 Moves the Parameter list in an Aggregate into this Aggregate's list.
Aggregateoperator= (const Parameter &parameter)
 Assigns a Parameter to this Aggregate.
Aggregateoperator= (const Aggregate &parameter)
 Assigns an Aggregate to this Aggregate.
Aggregateoperator= (const Assignment &parameter)
 Assigns an Assignment to this Aggregate.
Aggregateoperator= (const Value &value)
 An Aggregate doesn't have a Value, so this always throws an Invalid_Argument exception.
const Parameteroperator[] (unsigned int index) const
 Gets the Parameter at an index of the Aggregate list.
Parameteroperator[] (unsigned int index)
 Gets the Parameter at an index of the Aggregate list.
void read (std::istream &in=std::cin)
 Reads an input stream parsed as PVL syntax into this Aggregate.
void read (Parser &parser)
 Parameters read by a Parser are added to this Aggregate.
Parameterremove (size_type index)
 Removes a Parameter at an element index of the Aggregate's Parameter list.
Parameterremove (Parameter *parameter)
 Removes a Parameter from the Aggregate's Parameter list.
Parameterremove (iterator position)
 Removes a Parameter at an iterator position from the Aggregate's Parameter list.
Parameterremove_depth (Parameter *parameter)
 Removes a Parameter from the Aggregate's Parameter list or any of its sub-lists.
void removing (Parameter *parameter)
 Resets the parent of a Parameter to NULL.
size_type total_size ()
 Counts the number of Parameters in the Aggregate's Parameter list and, recursively, the number of Parameters in the Parameter list of each Aggregate in the list.
Aggregatetype (const int type)
 Sets the Type specification.
Type type () const
 Gets the Type specification.
std::string type_name () const
 Gets the name for this Aggregate's Type specification.
Valuevalue () const
 An Aggregate doesn't have a Value, so this always throws an Invalid_Argument exception.
 ~Aggregate ()
 Destroys an Aggregate by clearing the Parameter list.

Static Public Member Functions

static Type default_type ()
 Gets the default Type specification to be used when constructing a new Aggregate without a Type specified.
static Type default_type (const int type)
 Sets the default Type specification to be used when constructing a new Aggregate without a Type specified.

Detailed Description

An Aggregate implements a Parameter that is a list of Parameters.

An Aggregate provides for the hierarchical structuring of Parameters.

The list is provided by subclassing a Vectal of Parameters. A Vectal is a vector of virtual objects that are stored as pointers but for which reference semantics are offered in the access interface. However, the normal value functionality is also provided by copying (actually cloning) objects into the list and deleting them on removal. An Aggregate ensures that, normally, whenever a Parameter is entered into its list the parent of the Parameter is set to the Aggregate. Thus the hierarchical relationships are automatically maintained. Provision is also made for pulling a Parameter from an Aggregate's list without deleting it, but also automatically resetting its parent to NULL to correctly reflect that it is no longer a member of the Aggregate hierarchy.

In addition to the normal vector interators for traversing an Aggregate's Parameter list, specialized Depth_Iterators are provided that descend into Aggregates encountered in a Parameter list. They continue iterating the parent list where they left off after completing the interation of a child Aggregate. They also remember the root Aggregate where they started, which is where they will end. These iterators are bidirectional with some random access capabilities.

See also:
Vectal

Member Typedef Documentation

Aggregate as a Vectal (vector) of Parameters.

Identify the iterator for compilers that need help.

Reimplemented from Vectal< Parameter >.

Identify the iterator for compilers that need help.

Reimplemented from Vectal< Parameter >.

A specialized iterator that descends into Aggregates in the Parameter list.


Member Enumeration Documentation

anonymous enum

Flags for find case sensitivity argument.

Enumerator:
CASE_INSENSITIVE 
CASE_SENSITIVE 

Constructor & Destructor Documentation

Aggregate ( const std::string  name = "",
const idaeim::PVL::Parameter::Type  type_code = Default_Subtype 
) [explicit]

Constructs an empty Aggregate.

Parameters:
nameThe Parameter name.
type_codeThe Type specification code for the Aggregate.
See also:
type(Type)
Aggregate ( const Aggregate aggregate)

Copy constructor.

The entire Parameter list is replicated (cloned).

Parameters:
aggregateThe Aggregate to copy.
See also:
Parameter::Parameter(Parameter)
Aggregate ( const Parameter parameter)

Copy constructor from a Parameter.

If the Parameter being copied is an Aggregate, it is assigned to the new Aggregate. If, however, the Parameter is an Assignment, it is copied as the first element in the new Aggregate's Parameter list.

Parameters:
parameterThe Parameter to copy.
Aggregate ( Parser parser,
const std::string  name = "" 
)

Constructs an Aggregate using a Parser to provide its contents.

This is the same as constructing an empty Aggregate and then using the Parser::add_parameters(Aggregate&) method on it. Note that the Parameters obtained from the Parser are all added as elements of the new Aggregate. Thus even if the Parser only finds one Parameter - e.g. from a string defining a single Group - the result will be an Aggregate containing a single Parameter element.

Note: If the new Aggregate is given the name Parser::CONTAINER_NAME then when the Aggregate is written to an ostream, only the content Parameters will be written.

Parameters:
parserThe Parser from which to get content Parameters.
nameThe name for the Aggregate.
See also:
Parser::add_parameters(Aggregate&)
~Aggregate ( )

Destroys an Aggregate by clearing the Parameter list.

Each Parameter in the list will be deleted.


Member Function Documentation

Aggregate* clone ( ) const [inline, virtual]

Clones the Aggregate by making a copy of itself.

Returns:
A pointer to a copy of this Aggregate.
See also:
Aggregate(Aggregate&)

Implements Parameter.

References Parameter::Aggregate.

bool is_Aggregate ( ) const [inline, virtual]

Test if this is an Aggregate.

Returns:
Always returns true.

Reimplemented from Parameter.

bool is_Group ( ) const [inline, virtual]

Test if this is a Group Aggregate.

Returns:
true if the Type specification is GROUP.

Reimplemented from Parameter.

References Parameter::GROUP.

bool is_Object ( ) const [inline, virtual]

Test if this is a Group Aggregate.

Returns:
true if the Type specification is OBJECT.

Reimplemented from Parameter.

References Parameter::OBJECT.

bool is ( const Type  type) const [inline, virtual]

Test if the Parameter is of some Type.

The test is the logical AND of the Parameter Subtype and the specified Type value. Thus, conceptually, the test is if the Parameter is any one of a possible combination of Types. For example, parameter.is (GROUP| OBJECT) will be true for any AGGREGATE parameter, which could just as easily be tested by parameter.is (AGGREGATE); and parameter.is (ASSIGNMENT | AGGREGATE) can be expected to always be true.

Parameters:
typeThe Type specification code against which to test the Parameter.
Returns:
true if the implementing class is of the specified Type. an OBJECT Type specification; false otherwise.

Implements Parameter.

References Parameter::type().

Type type ( ) const [inline, virtual]

Gets the Type specification.

Returns:
This should be either the GROUP or OBJECT code.

Implements Parameter.

Aggregate& type ( const int  type) [virtual]

Sets the Type specification.

Parameters:
typeThe Type specification for the Aggregate.
Returns:
This Aggregate.
Exceptions:
Invalid_ArgumentIf the type value is not GROUP or OBJECT.

Implements Parameter.

std::string type_name ( ) const [inline, virtual]

Gets the name for this Aggregate's Type specification.

Returns:
The name string associated with the Aggregate's Type specification.
See also:
Parameter::type_name(Type)

Implements Parameter.

References Parameter::type_name().

static Type default_type ( ) [inline, static]

Gets the default Type specification to be used when constructing a new Aggregate without a Type specified.

Returns:
The current default Type specification.
static Type default_type ( const int  type) [static]

Sets the default Type specification to be used when constructing a new Aggregate without a Type specified.

Returns:
The previous default Type specification.
Exceptions:
Invalid_ArgumentIf the type value is not GROUP or OBJECT.
Value& value ( ) const [virtual]

An Aggregate doesn't have a Value, so this always throws an Invalid_Argument exception.

Returns:
Never returns ...
Exceptions:
Invalid_Argumentalways.

Implements Parameter.

Parameter& operator[] ( unsigned int  index) [inline, virtual]

Gets the Parameter at an index of the Aggregate list.

This form of the operator is used with an assignable Parameter (lvalue) in an expression.

Parameters:
indexThe index of a Parameter in the Aggregate list.
Returns:
The Parameter reference at the index position.

Reimplemented from Parameter.

References Parameter::operator[]().

const Parameter& operator[] ( unsigned int  index) const [inline, virtual]

Gets the Parameter at an index of the Aggregate list.

This form of the operator produces an unassignable (read only) Parameter.

Parameters:
indexThe index of a Parameter in the Aggregate list.
Returns:
The Parameter reference at the index position.

Reimplemented from Parameter.

References Parameter::operator[]().

Aggregate& operator= ( const Parameter parameter) [virtual]

Assigns a Parameter to this Aggregate.

If the Parameter is an Aggregate its name, comment and Type specification are copied, but not its parent. The Parameter list from the other Aggregate is replicated (cloned) and replaces the current list. The replacement is overlap safe: an Aggregate from within this Aggregate can be assigned. The current Parameter list is set aside but not deleted until the list replacement has completed.

If the Parameter is an Assignment its clone is appended to the Parameter list.

Nothing is done when assigning a Parameter to itself.

Parameters:
parameterThe Parameter to be assigned.
Returns:
This Aggregate.

Implements Parameter.

Aggregate& operator= ( const Aggregate parameter) [inline]

Assigns an Aggregate to this Aggregate.

Parameters:
parameterThe Aggregate to be assigned.
Returns:
This Aggregate.
See also:
operator=(const Parameter&)

References Parameter::operator=().

Aggregate& operator= ( const Assignment parameter) [inline]

Assigns an Assignment to this Aggregate.

Parameters:
parameterThe Assignment to be assigned.
Returns:
This Aggregate.
See also:
operator=(const Parameter&)

References Parameter::operator=().

Aggregate& operator= ( const Value value) [virtual]

An Aggregate doesn't have a Value, so this always throws an Invalid_Argument exception.

Returns:
Never returns ...
Exceptions:
Invalid_Argumentalways.

Implements Parameter.

int compare ( const Parameter parameter) const [virtual]

Compares this Aggregate with another Parameter.

A Parameter compared with itself is, of course, identical.

The Parameter names are compared and, if they are different, the result of this comparison is returned.

When the Parameter names are the same, an Aggregate is greater than an Assignment.

When comparing Aggregates with the same name, the greater is the one with the larger Parameter list (not including the size of Parameter lists in any Aggregates in the list). When the size of both lists is the same, then each Parameter in the list is compared in the order they occur in the list and the result of the first non-equal comparison is returned; thus for the best results sort both Aggregates first.

Parameters:
parameterThe Parameter to compare against.
Returns:
An int that is less than, equal to, or greater than 0 if this Aggregate is logically less than, equal to, or greater than, respectively, the Parameter.
See also:
sort(depth_iterator, depth_iterator)

Implements Parameter.

Parameter* find ( const std::string &  pathname,
bool  case_sensitive = false,
int  skip = 0,
idaeim::PVL::Parameter::Type  type = (Type)(ASSIGNMENT|AGGREGATE) 
) const

Find a named Parameter.

The Parameter to be found may be specified by a simple name, a relative pathname or an absolute pathname. A simple name is the name of a Parameter itself. A relative pathname is a simple name preceeded by the pathname of an Aggregate Parameter that must contain the Parameter with the simple name. An absolute pathname is a pathname that begins with a pathname delimiter ('/'); i.e. it is a fully qualified pathname beginning at the root of the Aggregate hierarchy, compared to a relative pathname that may begin at any Aggregate in the hierarchy.

Since it is not necessary that the pathname to each Parameter be unique, the number of matching pathnames to skip before selecting a Parameter may need to be specified to get the desired Parameter. Also, a specific type of Parameter - an Aggregate of Parameters or an Assignment of Values - may be specified. When skipping parameters, only the specified type, if any, are counted.

Parameters:
pathnameThe pathname of the parameter to find.
case_sensitiveIf true, the name search is case sensitive; case insensitive otherwise.
skipThe number of parameters that match the criteria to skip before selecting a matching parameter. A value less than or equal to zero selects the first match.
typeA Type code that specifies the type of Parameter that is to be selected. By default any Type (ASSIGNMENT or AGGREGATE) will be acceptable.
Returns:
A pointer to the matching parameter, or NULL if a match could not be found.
void read ( std::istream &  in = std::cin) [virtual]

Reads an input stream parsed as PVL syntax into this Aggregate.

A Parser is constructed from the input stream and passed to the read(Parser&) method.

Parameters:
inThe istream to be parsed for PVL syntax.

Implements Parameter.

void read ( Parser parser) [virtual]

Parameters read by a Parser are added to this Aggregate.

All available Parameters are obtained from the Parser will be added to the end of this Aggregate's Parameter list. If the Parser produces an Aggregate then each Parameter in its list is moved into this Aggregate list if the list is currently empty; if the list is not empty the entire Aggregate that was obtained, not just its list of Parameters, is appended to the list. If the Parameter the Parser produces in not an Aggregate Parameter then it is appended to this Aggregate's list. If the Parser does not produce a Parameter, nothing is done.

Parameters:
parserThe Parser from which to obtain Parameters.
See also:
Parser::get_parameters()

Implements Parameter.

Aggregate& add ( const Parameter parameter) [inline]

Adds a clone of the Parameter to the end of the Aggregate's Parameter list.

Parameters:
parameterThe Parameter to add.
Returns:
This Aggregate.
See also:
Vectal::push_back(reference)
add(Parameter*)
Aggregate& add ( Parameter parameter) [inline]

Adds the Parameter to the end of the Aggregate's Parameter list.

Note: The Parameter is not cloned; The Parameter pointer is placed directly in the Parameter list backing store. The parent of the Parameter is changed to this Aggregate.

Parameters:
parameterThe Parameter to add.
Returns:
This Aggregate.
See also:
Vectal::poke_back(pointer)
add(const Parameter&)
Aggregate& copy_in ( const Aggregate aggregate)

Copies the Parameter list in an Aggregate into this Aggregate's list.

Each Parameter in the source Aggregate Parameter list is added to the end of this Aggregate's Parameter list.

Parameters:
aggregateThe source Aggregate.
Returns:
This Aggregate.
See also:
add(const Parameter&)
Aggregate& move_in ( Aggregate aggregate)

Moves the Parameter list in an Aggregate into this Aggregate's list.

Each Parameter in the source Aggregate Parameter list is moved to the end of this Aggregate's Parameter list. As a result the source Aggregate will be emptied.

Parameters:
aggregateThe source Aggregate.
Returns:
This Aggregate.
See also:
add(const Parameter*)
Parameter* remove ( iterator  position)

Removes a Parameter at an iterator position from the Aggregate's Parameter list.

Parameters:
positionA valid iterator for the Aggregate's Parameter list.
Returns:
A pointer to the Parameter that was removed.
See also:
pull_out(iterator)
Parameter* remove ( size_type  index)

Removes a Parameter at an element index of the Aggregate's Parameter list.

Parameters:
indexAn index of the Aggregate's Parameter list.
Returns:
A pointer to the Parameter that was removed. This will be NULL if the index is not within the range of existing elements of the Aggregate's Parameter list.
See also:
pull_out(size_type)
Parameter* remove ( Parameter parameter)

Removes a Parameter from the Aggregate's Parameter list.

Parameters:
parameterA pointer to the Parameter to be removed. If NULL nothing is done and NULL is returned.
Returns:
A pointer to the Parameter that was removed, or NULL if the Parameter was not found in the Aggregate's Parameter list.
Parameter* remove_depth ( Parameter parameter)

Removes a Parameter from the Aggregate's Parameter list or any of its sub-lists.

Parameters:
parameterA pointer to the Parameter to be removed. If NULL nothing is done and NULL is returned.
Returns:
A pointer to the Parameter that was removed, or NULL if the Parameter was not found.
void entering ( Parameter parameter)

Sets the parent of a Parameter to this Aggregate.

This method overrides the Vectal's method that is invoked whenever a Parameter is entered into the Parameter list. It is not intended for normal use since it affects the logical relationship of Parameters in an Aggregate hierarchy.

The uniquness of the Parameter in the path hierachy is ensured; loops are prevented.

Parameters:
parameterThe Parameter whose parent is to be changed.
Exceptions:
Invalid_ArgumentIf the parameter is in the Aggregate's path; i.e. the Parameter is already in the parent hierachy of the Aggregate, or is the Aggregate itself.
void removing ( Parameter parameter)

Resets the parent of a Parameter to NULL.

This method overrides the Vectal's method that is invoked whenever a Parameter is removed from the Parameter list. It is not intended for normal use since it affects the logical relationship of Parameters in an Aggregate hierarchy.

Parameters:
parameterThe Parameter whose parent is to be changed.
size_type total_size ( )

Counts the number of Parameters in the Aggregate's Parameter list and, recursively, the number of Parameters in the Parameter list of each Aggregate in the list.

Returns:
The accumulated total number of Parameters enclosed by this Aggregate.
Depth_Iterator begin_depth ( )

Gets a Depth_Iterator positioned at the beginning of this Aggregate.

Returns:
A Depth_Iterator.
Depth_Iterator end_depth ( )

Gets a Depth_Iterator positioned at the end of this Aggregate.

Returns:
A Depth_Iterator.

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