Main Page | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | File Members

vtkNestingExpatBase Class Reference

#include <vtkNestingExpatBase.h>

Inheritance diagram for vtkNestingExpatBase:

Inheritance graph
[legend]
Collaboration diagram for vtkNestingExpatBase:

Collaboration graph
[legend]
List of all members.

Detailed Description

Subclass supporting a hierarchy of XML parsers.

vtkNestingExpatBase is a subclass to support a hierarchy of nesting parser objects, where a top-level (or root) parser object may create sub-parsers for different pieces of markup in a file.

The currently active child parser object is owned (i.e. the parent instance calls Register on it) and is UnRegistered by in the destructor, so error handling can propagate up the tree, closing parsers, without leaks.

Switching to sub-parsers
You can transfer to a sub-parser with: 
   // carries on using our parser, is self-deleting
   new UserChildParser(this)
Warning:
You can accidentally invoke a new parser without it doing anything. e.g.: 
            // will be new top-level parser, nothing to do with our XML
            new UserChildParser()
Self-deletion
If you transfer control to a sub-parser with just 
 new UserChildParser(this)
then it will be automatically self-deleting in its ReturnToParent method and will invoke DisownChild to clear our Child.
The reason for self-deletion being governed by a somewhat complex chain of calls rather than simply a boolean flag is because expatpp has been in use worldwide for many years and it was deemed too unfriendly to break code in a manner which could cause unwanted side effects - the current approach safely preserves self-deletion but also allows for expatpp to have parent parsers own and delete children, without compiling with different options.

Note:
If you invoke a sub-parser with RedirectInternalParser(new UserChildParser()); then the user child parser will start with a new XML parser instance created by the vtkExpatBase constructor. This is safe but slightly wasteful of processing as SetParent will discard and replace the child's newly created expat XML parser.
Switching to child and explicitly deleting
RedirectInternalParser(somevar = new UserChildParser(this)) allows you to get values back out of a child parser, in the context of the parent, e.g.: 
   void MultiFilterParser::startElement (const XML_Char*  name,
                                         const XML_Char** attrs)
   {
     if (strcmp(name, "FilterRequest")==0)
       {
       // We now own and will have to explicitly delete the child.
       this->RedirectInternalParser( this->CurrentFilterParser =
                                   new FilterRequestParser(this, attrs) );
       ...
       }
     ...

   void MultiFilterParser::endElement (const XML_Char* name)
   {
     if (strcmp(name, "FilterRequest")==0)
       {
       assert(this->CurrentFilterParser != 0);

       // retrieve data built by sub-parser
       FilterData* newData = this->CurrentFilterParser->orphanBuiltData();
       ...
       this->CurrentFilterParser = 0;
       this->SetChild(NULL);
       }
   }
Note:
This class is mutated from Andy Dent's expatppNesting class.
Author:
Sean McInerney
Version:
Revision
1.3
Date:
Date
2004/05/29 23:19:34
See also:
vtkExpatBase

Definition at line 114 of file vtkNestingExpatBase.h.

Public Member Functions

 vtkTypeRevisionMacro (vtkNestingExpatBase, vtkExpatBase)
void PrintSelf (ostream &, vtkIndent)
void RedirectInternalParser (vtkNestingExpatBase *aChild)
 Hand off current document to a child parser that understands the next segment of XML.

virtual vtkNestingExpatBase * ReturnToParent (void)
 Called by NestedEndElementCb if this is NOT the root parser.

virtual vtkNestingExpatBase * GetChild (void) const
 Get the child parser.


Static Public Member Functions

Interface functions for callbacks.
void NestedStartElementCb (void *aPtr, const XML_Char *aName, const XML_Char **aAttrs)
 Start element callback for nesting parsers.

void NestedEndElementCb (void *aPtr, const XML_Char *aName)
 End element callback for nesting parsers.


Protected Member Functions

 vtkNestingExpatBase (vtkNestingExpatBase *parent=NULL)
 Default constructor.

 ~vtkNestingExpatBase ()
virtual void SetupHandlers (void)
 Set the handlers used by expat callbacks.

virtual void SetChild (vtkNestingExpatBase *child)
 Called from child constructors when passed a parent pointer as well as from RedirectInternalParser, in which case it may be the 2nd time we're called for a given child (see scenarios in vtkNestingExpatBase class comment).

virtual void DeleteChild (void)
 Must use before early disposal of holding adopted child parser.

void GrabInternalParserFromParent (void)
 Use parent's underlying expat parser.

void SetParent (vtkNestingExpatBase *aParent)
 Called by RedirectInternalParser to indicate a newly created child parser object is now the currently active child for aParent and the child isn't expected to self-delete.

void OrphanChild (vtkNestingExpatBase *aCallingChild)
 Honor request from aCallingChild to relinquish responsibility for it.


Protected Attributes

Nesting parser object data
vtkNestingExpatBase * Parent
 Parent owns this object (NULL for root parser objects).

int Depth
 Number of levels nested below the root parser.

bool SelfDeleting
 Only valid if Parent is not NULL.

vtkNestingExpatBase * Child
 Owned, optional currently active child.

Constructor & Destructor Documentation

vtkNestingExpatBase::vtkNestingExpatBase (  vtkNestingExpatBase *  parent = NULL  )  [protected]
 

Default constructor.

Warning:
NOT a copy constructor! This is a recursive situation.

vtkNestingExpatBase::~vtkNestingExpatBase (   )  [protected]
 

Member Function Documentation

virtual void vtkNestingExpatBase::DeleteChild (  void   )  [protected, virtual]
 

Must use before early disposal of holding adopted child parser.

virtual vtkNestingExpatBase* vtkNestingExpatBase::GetChild (  void   )  const [virtual]
 

Get the child parser.

Reimplemented in vtkPaletteElementParser.

void vtkNestingExpatBase::GrabInternalParserFromParent (  void   )  [inline, protected]
 

Use parent's underlying expat parser.

Definition at line 255 of file vtkNestingExpatBase.h.

References vtkExpatBase::GrabInternalParser(), vtkObject::Modified(), Parent, and vtkExpatBase::Parser.

Referenced by SetParent().

void vtkNestingExpatBase::NestedEndElementCb (  void *  aPtr,
const XML_Char *  aName
)  [inline, static]
 

End element callback for nesting parsers.

Definition at line 355 of file vtkNestingExpatBase.h.

References Depth, vtkExpatBase::EndElement(), NestedEndElementCb(), and ReturnToParent().

Referenced by NestedEndElementCb().

void vtkNestingExpatBase::NestedStartElementCb (  void *  aPtr,
const XML_Char *  aName,
const XML_Char **  aAttrs
)  [inline, static]
 

Start element callback for nesting parsers.

Definition at line 341 of file vtkNestingExpatBase.h.

References Depth, NestedStartElementCb(), and vtkExpatBase::StartElement().

Referenced by NestedStartElementCb().

void vtkNestingExpatBase::OrphanChild (  vtkNestingExpatBase *  aCallingChild  )  [inline, protected]
 

Honor request from aCallingChild to relinquish responsibility for it.

i.e. Simply set Child member to NULL without calling UnRegister.

Definition at line 303 of file vtkNestingExpatBase.h.

References Child, vtkObject::Modified(), and OrphanChild().

Referenced by OrphanChild(), and ReturnToParent().

void vtkNestingExpatBase::PrintSelf (  ostream &  ,
vtkIndent 
)  [virtual]
 

Reimplemented from vtkExpatBase.

Reimplemented in vtkPaletteColorBaseParser, and vtkPaletteElementParser.

void vtkNestingExpatBase::RedirectInternalParser (  vtkNestingExpatBase *  aChild  )  [inline]
 

Hand off current document to a child parser that understands the next segment of XML.

User code (typically the StartElement handler of parsers derived from vtkNestingExpatBase) may call: 

   RedirectInternalParser(new UserChildParser());

Control will be returned to the original (parent) parser when the end of the child element is reached. In its lifetime a 'parent' parser may switch control to several child parsers (one at a time of course) as it moves through the document encountering various types of child element.

Note:
A child to which control has been switched by 
         new childParser(this);
will self-delete and will clear our Child member in its destructor.

Definition at line 291 of file vtkNestingExpatBase.h.

References RedirectInternalParser(), SetChild(), and SetParent().

Referenced by RedirectInternalParser().

vtkNestingExpatBase * vtkNestingExpatBase::ReturnToParent (  void   )  [inline, virtual]
 

Called by NestedEndElementCb if this is NOT the root parser.

Note:
This makes it is safe to put parsers on the stack.

Reimplemented in vtkPaletteColorBaseParser.

Definition at line 316 of file vtkNestingExpatBase.h.

References vtkObjectBase::Delete(), vtkExpatBase::GrabInternalParser(), OrphanChild(), Parent, and SelfDeleting.

Referenced by NestedEndElementCb().

virtual void vtkNestingExpatBase::SetChild (  vtkNestingExpatBase *  child  )  [protected, virtual]
 

Called from child constructors when passed a parent pointer as well as from RedirectInternalParser, in which case it may be the 2nd time we're called for a given child (see scenarios in vtkNestingExpatBase class comment).

The parameter data is checked against the instance data, so that Register is only called once if the data is unchanged.

Referenced by RedirectInternalParser().

void vtkNestingExpatBase::SetParent (  vtkNestingExpatBase *  aParent  )  [inline, protected]
 

Called by RedirectInternalParser to indicate a newly created child parser object is now the currently active child for aParent and the child isn't expected to self-delete.

Normal code to create an owned child would be either: 

   RedirectInternalParser(new UserChildParser(this));
where this is the currently active parent parser and wants to be responsible for deleting the new child, or 
   new UserChildParser(this);
to have a child parser self-delete.

Warning:
Copes with the situation of people forgetting to pass in the parent parser (and hence creating a new one by default) if invoked by RedirectInternalParser(new UserChildParser()) by somewhat wastefully deleting the parser created in vtkExpatBase::vtkExpatBase by us being a root parser.

Definition at line 269 of file vtkNestingExpatBase.h.

References GrabInternalParserFromParent(), vtkObject::Modified(), Parent, vtkExpatBase::ReleaseParser(), SelfDeleting, and SetParent().

Referenced by RedirectInternalParser(), and SetParent().

virtual void vtkNestingExpatBase::SetupHandlers (  void   )  [protected, virtual]
 

Set the handlers used by expat callbacks.

Warning:
Must call base class method.

Reimplemented from vtkExpatBase.

Reimplemented in vtkPaletteColorBaseParser, and vtkPaletteElementParser.

vtkNestingExpatBase::vtkTypeRevisionMacro (  vtkNestingExpatBase  ,
vtkExpatBase 
) 
 

Member Data Documentation

vtkNestingExpatBase* vtkNestingExpatBase::Child [protected]
 

Owned, optional currently active child.

Definition at line 238 of file vtkNestingExpatBase.h.

Referenced by OrphanChild().

int vtkNestingExpatBase::Depth [protected]
 

Number of levels nested below the root parser.

Definition at line 232 of file vtkNestingExpatBase.h.

Referenced by NestedEndElementCb(), and NestedStartElementCb().

vtkNestingExpatBase* vtkNestingExpatBase::Parent [protected]
 

Parent owns this object (NULL for root parser objects).

Definition at line 229 of file vtkNestingExpatBase.h.

Referenced by GrabInternalParserFromParent(), ReturnToParent(), and SetParent().

bool vtkNestingExpatBase::SelfDeleting [protected]
 

Only valid if Parent is not NULL.

Definition at line 235 of file vtkNestingExpatBase.h.

Referenced by ReturnToParent(), and SetParent().

The documentation for this class was generated from the following file:
Generated on Tue Aug 10 03:42:25 2004 for vtkExtensions by doxygen 1.3.7