Re: [boost] API Review request: XML API for C++, second round

From: Stefan Seefeld (seefeld_at_[hidden])
Date: 2003-06-26 07:55:24

Hamish Mackenzie wrote:
> On Wed, 2003-06-25 at 20:45, Stefan Seefeld wrote: 
> 
>>>Why should the node-wrappers keep the document alive?
>>
>>for consistency, and convenience. In the same way you can get down from
>>the document to the individual nodes you can get up: node.parent() and
>>node.document() provide the means to walk up towards the document root.
> 
> 
> And yet it does not keep it's parent() alive.  How is that consistent?  
> 
> In what way would you be unable to walk toward the document if it was
> not add reffed?

dom::node_ptr root;
{
   dom::document_ptr = document("foo.xml");
   root = document.root_node();
}

at this point document would go out of scope and so the tree would
be destructed, making root invalid. With root holding a reference
to the document it is not, and the following will work:

dom::document_ptr document = root.document();
// continue here...

[...]

> With the implicit add ref it is hard to tell what the intent of the code
> is.  Your example illustrates this problem well, but consider this
> simpler version....

yes, letting the user explicitely manage the document would be the alternative.
I'm not sure that nodes referencing their document is less clear, though.

> 
> {
> xml::document_ptr doc( "config.xml" );
> some_function( doc->root_node() );
> }
> 
> I cannot tell what the writer intended the scope of doc to be without
> examining some_function and understanding what it does.  It might add
> ref the document it might not.

What about the relationship between the document and dom::document_ptr ?
So even if 'doc' (a document pointer) is limitted, the callee could
set its own member

some_function(dom::node_ptr node)
{
   my_doc = node->document()
}

and just by looking at the API it is not clear that the 'doc'
variable above is really the master document pointer. Being
able to write things like

dom::document_ptr doc("config.xml");
dom::document_ptr doc2(doc);

somehow suggests that either the document is not managed by
dom::document_ptr at all, or by all of them (and thus by
extension by dom::node_ptr)

[...]

>>>Here is the analogy I think works best...
>>>
>>>container --> document
>>>container::value_type --> node
>>>container::iterator --> node_iterator
>>>container::pointer_type --> node_pointer
>>>container::reference_type --> node_reference
>>
>>hmm, that makes it look simpler than it actually is: is there really
>>a single 'value_type' ?
> 
> 
> True you need attribute_, element_ etc. variations which you already
> have.
> 
> value_types could exist but it would require a deep copy to be
> consistent.  If you do want to define it then I suggest

you mean if I do *not* want to define it ?

> typedef void value_type;

> Your iterator types look good.  Why is there an extra level of
> indirection in basic_element_const_iterator?

the const iterator is non-functional right now. I'v been wondering
how to provide one. It seems I would need to define a 'const_node_ptr'
set of classes.

Regards,
                Stefan