An os_element_group is a collection of elements. As an os_element -derived class, an os_element_group has an HTML tag, zero or more attributes, and an end tag. The tag is specified in the constructor. It is unnecessary in most cases to create an os_element_group explicitly, because specific os_element_group -derived classes are typically created instead.

Elements are added to an os_element_group through both the add() member functions and operator<< . Elements are stored on the heap internally as an STL vector of os_element* . This underlying container is exposed through the elements() member function to allow application-specific manipulation of the collection contents.

An element within an os_element_group is identified by its key. The find, remove, and replace member functions search for elements by key. The search range for these member functions is specified by a search depth. Two depths are defined: shallow and deep. A shallow search considers only the top-level elements within a page or element group. This is the default. A deep search recursively considers elements in both the top-level page or element group and all sublevel element groups. These operations are depth first.

The find_first() and find_all() member functions locate elements within the os_element_group and return pointers to these elements. The remove_first() and remove_all() member functions delete elements from the os_element_group . The replace_first() and replace_all() member functions replace elements within an os_element_group with a replacement element and delete the old element.

The contents of an os_element_group are constrained by a rule set that can be enabled, disabled, or modified at runtime. Constraint checking is disabled by default.

Constraints are enabled, disabled, and queried through the enable_constraints() , disable_constraints() , and constraints_enabled() static member functions.

A constraint rule can be added through the add_constraint() static member function, or deleted through the delete_constraint() static member function.

Interface

Constructor

os_element_group( const string& tag )

Constructs an empty element group with HTML tag tag .

Constructor

os_element_group( const string& tag, const os_element& element )

Constructs an element group, with HTML tag tag , containing a copy of element .

Constructor

os_element_group( const string& tag , const string& text )

Constructs an element group, with HTML tag tag , containing an os_text element created from text .

Constructor

os_element_group( const os_element_group& rhs )

Constructs an element group that is a copy of rhs .

Destructor

/* virtual */ ~os_element_group()

Destroys the element group.

os_element_group& operator<<( const os_element& element )

Inserts a copy of element and returns a reference to the element group.

os_element_group& operator<<( const string& text )

Inserts an os_text element created from text and returns a reference to the element group.

os_element_group& operator=( const os_element_group& rhs )

Replaces the element group contents with a copy of rhs and returns a reference to the element group.

add

/* virtual */ os_element* add( const os_element& element )

Adds a copy of element to the element group and returns a pointer to the new element.

add

/* virtual */ os_element* add( const string& text )

Adds an os_text element created from text to the element group, and returns a pointer to the new element.

add_constraint

bool add_constraint( const string& container_class , const string& element_class )

Adds an element group constraint rule to allow an element of type container_class to contain elements of type element_class , and returns true upon success.

add_element_class

bool add_element_class( const string& tag, const string& class_name )

Adds an element group tag-to-class mapping, to map HTML tag tag to class class_name , and returns true upon success.

can_contain

bool can_contain( const os_element& element ) const

Returns true if the element group can contain element .

class_by_tag

/* static */ multimap<string, string, less<string> >* class_by_tag()

Returns a pointer to the tag-to-class multimap.

class_name

string class_name( const os_element& element ) const

Returns the class name of element , or the empty string if the name is not defined in the element group tag-to-class multimap.

clone

/* virtual */ os_element* clone() const

Returns a base class pointer to a heap-based deep copy of the element group.

constraints

/* static */ multimap<string, string, less<string> >* constraints()

Returns a pointer to the element group content constraint multimap.

constraints_enabled

bool constraints_enabled()

Returns true if element group content constraint checking is enabled.

delete_constraint

bool delete_constraint( const string& container_class , const string& element_class )

Deletes an element group constraint rule that would allow an element of type container_class to contain elements of type element_class , and returns true upon success.

disable_constraints

void disable_constraints()

Disables element group content constraint checking.

elements

vector<os_element*>& elements()

Returns a reference to a vector of pointers that point to the elements contained in the element group.

enable_constraints

void enable_constraints()

Enables element group content constraint checking during printing.

find_all

/* virtual */ vector<os_element*> find_all( const string& key , os_element::search_depth depth )

Returns a list of pointers to the elements with key key found on a depth (default os_element::shallow ) search. Returns an empty list if no matching elements are found.

find_first

/* virtual */ os_element* find_first( const string& key , os_element::search_depth depth )

Returns a pointer to the first element with key key found on a depth (default os_element::shallow ) search. Returns 0 if no matching element is found.

print

/* virtual */ void print( ostream& os ) const

Prints the element group to os .

print_body

void print_body( ostream& os ) const

Prints the contents of the element group to os .

remove_all

/* virtual */ int remove_all( const string& key , os_element::search_depth depth )

Removes all elements with key key found on depth (default os_element::shallow ) search, and returns the total number of elements removed. Returns 0 if no matching elements are found.

remove_first

/* virtual */ bool remove_first( const string& key , os_element::search_depth depth )

Removes the first element with key key found on depth (default os_element::shallow ) search, and returns true . Returns false if no matching element is found.

replace_all

/* virtual */ int replace_all( const string& key , const os_element& replacement , os_element::search_depth depth )

Replaces, with replacement , all elements with key key found on depth (default os_element::shallow ) search, and returns the total number of elements replaced. Returns 0 if no matching elements are found.

replace_first

/* virtual */ bool replace_first( const string& key , const os_element& replacement , os_element::search_depth depth )

Replaces, with replacement , the first element with key key found on depth (default os_element::shallow ) search, and returns true . Returns false if no matching element is found.

report_constraint_violation

/* virtual */ void report_constraint_violation( const os_element& element , ostream& os ) const

Prints to os a constraint violation notice for an element within the element group.

os_element_group

Declaration

Typedefs

Interface