ZStrimW_ML Class Reference

A write filter strim to help generate well-formed ML-type data (XML, HTML etc). More...

#include <ZStrimW_ML.h>

Inheritance diagram for ZStrimW_ML:


Public Member Functions
virtual void	Imp_Flush ()
	If this strim buffers data then pass it on to its ultimate destination.
const ZStrimW &	Raw () const
	Close off any pending tag and return the sink stream.
void	WriteNBSP () const
	Write an nbsp entity.
void	WriteEntity (const string8 &iEntity) const
	Write an arbitrary entity.
void	Begin (const string8 &iTag) const
	Add a normal begin tag to the top of the stack.
void	End (const string8 &iTag) const
	Check that the tag on the top of the stack matches iTag, and emit the end tag in form </XXX>.
void	End () const
	If the stack is empty trip an error. Otherwise emit the tag on the top of the stack in the form </XXX>.
void	Empty (const string8 &iTag) const
	Write a tag of the form <XXX a1="xxx" a2="xxx">.
void	PI (const string8 &iTag) const
	Write a tag of the form <?XXX a1="xxx" a2="xxx"?>.
void	Tag (const string8 &iTag) const
	Write a tag of the form <XXX a1="xxx" a2="xxx">, without requiring that an end tag be subsequently written.
void	Attr (const string8 &iValue) const
	Add a boolean attribute (one with no value) to the currently pending tag.
void	Attr (const string8 &iName, const string8 &iValue) const
	Add an attribute with the name iName and the value iValue to the pending tag.
void	Attr (const string8 &iName, const UTF8 *iValue) const
	Add an attribute with the name iName and the value iValue to the pending tag.
void	Attr (const string8 &iName, int iValue) const
void	Attrf (const string8 &iName, const UTF8 *iValue,...) const
void	Attr (const string8 &iName, const ZTupleValue &iValue) const
void	Attrs (const ZTuple &iTuple) const
bool	Indent (bool iIndent) const
	Set indent enable, and return previous value.
void	Abandon ()
	Toss any pending tag and its attributes, and clear the stack.
void	EndAll ()
	Close off any pending tag, emit end tags for everything on the stack and empty the stack.
void	EndAll (const string8 &iTag)
	Close off all tags until iTag is reached in the stack.
void	WritePending ()

Detailed Description

A write filter strim to help generate well-formed ML-type data (XML, HTML etc).

ZStrimW_ML extends the ZStrimW protocol with methods to open and close tags, attach attributes to those tags incrementally and pretty-print the output. For example, assuming we're passed iStrimW:

ZStrimW_ML s(iStrimW);
s.Begin("html");

        s.Begin("head");

                s.Begin("title");
                        s.Write("This is my title");
                s.End("title");

        s.End("head");

        s.Begin("body");

                s.Begin("h1");
                        s.Write("This is a header, followed by a horizontal rule");
                s.End("h1");

                s.Tag("hr");
                s.Attr("width", "75%");

                s.Begin("a");
                s.Attr("href", "http://somedomain.com/");
                        s.Write("This text links to somedomain");
                s.End("a");

        s.End("body");

s.End("html");

will generate the html:

<html>
  <head>
    <title>
      This is my title
    </title>
  </head>
  <body>
    <h1>
      This is a header, followed by a horizontal rule
    </h1>
    <hr width="75%">
    <a href="http://somedomain.com/">
      This text links to somedomain
    </a>
  </body>
</html>

It is not necessary to pass the tag name to End, but if you do then ZStrimW_ML can ensure that the tag you think you're closing is indeed the last tag opened. Note that tag names, attribute names and attribute values are stored, compared and emitted as-is -- no case conversion is performed, so closing an 'HTML' begin tag with an 'html' end tag will trip an assertion.

ZStrimW_ML::Tag exists to allow for the generation of tags that do not have their balance checked, in particular common HTML tags such as BR, P, HR, LI, IMG etc.

To generate XML empty tags e.g. <sometag param="something"> use ZStrimW_ML::Empty.

After a call to ZStrimW_ML::Begin, ZStrimW_ML::Empty or ZStrimW_ML::Tag the strim is in a mode whereby attributes may be added to the tag. A call to ZStrimW_ML::End or any call to the normal write methods will cause the pending tag plus its attributes to be emitted to the sink strim followed by the actual write. ZStrimW_ML::Attr trips an assertion if the strim is not in the correct mode.

Note that ZStrimW_ML descends from ZooLib::NonCopyable, in order to enforce that it can't be assigned or copy constructed from another ZStrimW_ML. Nevertheless we declare a copy constructor and then don't define it. Why? In the words of Pete C on comp.lang.c++:

"When initialising a const reference to an rvalue (which we are in this case), the compiler may either: a) Bind the reference directly to the object that the rvalue represents, or b) Construct a temporary const object from the rvalue, and bind the reference to the temporary. The choice is implementation-defined, but the standard says that the constructor that would be used in (b) must be available anyway. ... See section 8.5.3.5 of the Standard for gory details."

We often want to be able to pass a temporary ZStrimW_ML initialized with a regular strim to a function taking a const ZStrimW_ML&. In gcc pre-4.0 this worked just as we want, and gcc post-4.0 still does the same thing (a), but now enforces the requirement that a copy constructor be visible.

The upshot is that if you get an error at link time, stating that no implementation of ZStrimW_ML(const ZStrimW_ML&) can be found, you've got yourself a compiler that's doing (b) and we'll need to rethink things.

Member Function Documentation

void ZStrimW_ML::Imp_Flush ( ) [virtual]

If this strim buffers data then pass it on to its ultimate destination.

Some write strims buffer the data written to them, or are built atop a foundation that may buffer data. Such strims should override Flush and push that buffered data on to its ultimate destination. When the method returns the data may still not have reached its ultimate destination, but is guaranteed to do at some point in the future with no further action necessary on the caller's part.

Reimplemented from ZStrimW.

void ZStrimW_ML::Attr	(	const string8 &	iName,
		int	iValue
	)			const

Add an attribute named iName to the currently pending tag. The value will be a string containing the base 10 digits of the integer iValue.

void ZStrimW_ML::Attrf	(	const string8 &	iName,
		const UTF8 *	iValue,
			...
	)			const

Add an attribute with the name iName and the printf-formatted string iValue etc to the currently pending tag.

void ZStrimW_ML::Attr	(	const string8 &	iName,
		const ZTupleValue &	iValue
	)			const

Add an attribute named iName to the currently pending tag. The value will be a string containing a sensible textual version of iValue.

void ZStrimW_ML::Attrs ( const ZTuple & iTuple ) const

Add attributes to the currently pending tag, taking the names and values from properties of iTuple. String values are added as you would expect, null values are added as boolean attributes. This convention is compatible with that used by ZML::Reader.

void ZStrimW_ML::WritePending ( )

If Begin, Empty, PI or Tag has been called, and no call to Write or End has been made, then the tag has not actually been written out as we're still allowing attributes to be added. Write any such pending tag, and switch to the same state we'd be if we'd called Write.

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

src/stream/ZStrimW_ML.h
src/stream/ZStrimW_ML.cpp

Generated on Thu Jul 26 11:22:07 2007 for ZooLib by

1.4.7

ZStrimW_ML Class Reference

Public Member Functions

Detailed Description

Member Function Documentation