XERCES_CPP_NAMESPACE_BEGIN
class XMLFormatTarget;
class XMLTranscoder;
/**
* This class provides the basic formatting capabilities that are required
* to turn the Unicode based XML data from the parsers into a form that can
* be used on non-Unicode based systems, that is, into local or generic text
* encodings.
*
* A number of flags are provided to control whether various optional
* formatting operations are performed.
*/
class XMLPARSER_EXPORT XMLFormatter
{
public:
// -----------------------------------------------------------------------
// Class types
// -----------------------------------------------------------------------
/** @name Public Contants */
//@{
/**
* EscapeFlags - Different styles of escape flags to control various formatting.
*
* NoEscapes:
* No character needs to be escaped. Just write them out as is.
* StdEscapes:
* The following characters need to be escaped:
*
*
* | character |
* should be escaped and written as |
*
*
* | & |
* & |
*
*
* | > |
* > |
*
*
* | " |
* " |
*
*
* | < |
* < |
*
*
* | ' |
* ' |
*
*
* AttrEscapes:
* The following characters need to be escaped:
*
*
* | character |
* should be escaped and written as |
*
*
* | & |
* & |
*
*
* | > |
* > |
*
*
* | " |
* " |
*
*
* CharEscapes:
* The following characters need to be escaped:
*
*
* | character |
* should be escaped and written as |
*
*
* | & |
* & |
*
*
* | > |
* > |
*
*
* EscapeFlags_Count:
* Special value, do not use directly.
* DefaultEscape:
* Special value, do not use directly.
*
*/
enum EscapeFlags
{
NoEscapes
, StdEscapes
, AttrEscapes
, CharEscapes
// Special values, don't use directly
, EscapeFlags_Count
, DefaultEscape = 999
};
/**
* UnRepFlags
*
* The unrepresentable flags that indicate how to react when a
* character cannot be represented in the target encoding.
*
* UnRep_Fail:
* Fail the operation.
* UnRep_CharRef:
* Display the unrepresented character as reference.
* UnRep_CharRef:
* Replace the unrepresented character with the replacement character.
* DefaultUnRep:
* Special value, do not use directly.
*
*/
enum UnRepFlags
{
UnRep_Fail
, UnRep_CharRef
, UnRep_Replace
, DefaultUnRep = 999
};
//@}
// -----------------------------------------------------------------------
// Constructors and Destructor
// -----------------------------------------------------------------------
/** @name Constructor and Destructor */
//@{
/**
* @param outEncoding the encoding for the formatted content
* @param target the formatTarget where the formatted content is written to
* @param escapeFlags the escape style for certain character
* @param unrepFlags the reaction to unrepresentable character
*/
XMLFormatter
(
const XMLCh* const outEncoding
, XMLFormatTarget* const target
, const EscapeFlags escapeFlags = NoEscapes
, const UnRepFlags unrepFlags = UnRep_Fail
);
XMLFormatter
(
const char* const outEncoding
, XMLFormatTarget* const target
, const EscapeFlags escapeFlags = NoEscapes
, const UnRepFlags unrepFlags = UnRep_Fail
);
~XMLFormatter();
//@}
// -----------------------------------------------------------------------
// Formatting methods
// -----------------------------------------------------------------------
/** @name Formatting methods */
//@{
/**
* @param toFormat the string to be formatted
* @param count length of the string
* @param escapeFlags the escape style for formatting toFormat
* @param unrepFlags the reaction for any unrepresentable character in toFormat
*
*/
void formatBuf
(
const XMLCh* const toFormat
, const unsigned int count
, const EscapeFlags escapeFlags = DefaultEscape
, const UnRepFlags unrepFlags = DefaultUnRep
);
/**
* @see formatBuf
*/
XMLFormatter& operator<<
(
const XMLCh* const toFormat
);
XMLFormatter& operator<<
(
const XMLCh toFormat
);
void writeBOM(const XMLByte* const toFormat
, const unsigned int count);
//@}
// -----------------------------------------------------------------------
// Getter methods
// -----------------------------------------------------------------------
/** @name Getter methods */
//@{
/**
* @return return the encoding set for the formatted content
*/
const XMLCh* getEncodingName() const;
/**
* @return return the transcoder used internally for transcoding the formatter conent
*/
inline const XMLTranscoder* getTranscoder() const;
//@}
// -----------------------------------------------------------------------
// Setter methods
// -----------------------------------------------------------------------
/** @name Setter methods */
//@{
/**
* @param newFlags set the escape style for the follow-on formatted content
*/
void setEscapeFlags
(
const EscapeFlags newFlags
);
/**
* @param newFlags set the reaction for unrepresentable character
*/
void setUnRepFlags
(
const UnRepFlags newFlags
);
/**
* @param newFlags set the escape style for the follow-on formatted content
* @see setEscapeFlags
*/
XMLFormatter& operator<<
(
const EscapeFlags newFlags
);
/**
* @param newFlags set the reaction for unrepresentable character
* @see setUnRepFlags
*/
XMLFormatter& operator<<
(
const UnRepFlags newFlags
);
//@}
private :
// -----------------------------------------------------------------------
// Unimplemented constructors and operators
// -----------------------------------------------------------------------
XMLFormatter();
XMLFormatter(const XMLFormatter&);
void operator=(const XMLFormatter&);
// -----------------------------------------------------------------------
// Private class constants
// -----------------------------------------------------------------------
enum Constants
{
kTmpBufSize = 16 * 1024
};
// -----------------------------------------------------------------------
// Private helper methods
// -----------------------------------------------------------------------
const XMLByte* getAposRef(unsigned int & count);
const XMLByte* getAmpRef(unsigned int & count);
const XMLByte* getGTRef(unsigned int & count);
const XMLByte* getLTRef(unsigned int & count);
const XMLByte* getQuoteRef(unsigned int & count);
void specialFormat
(
const XMLCh* const toFormat
, const unsigned int count
, const EscapeFlags escapeFlags
);
// -----------------------------------------------------------------------
// Private, non-virtual methods
//
// fEscapeFlags
// The escape flags we were told to use in formatting. These are
// defaults set in the ctor, which can be overridden on a particular
// call.
//
// fOutEncoding
// This the name of the output encoding. Saved mainly for meaningful
// error messages.
//
// fTarget
// This is the target object for the formatting operation.
//
// fUnRepFlags
// The unrepresentable flags that indicate how to react when a
// character cannot be represented in the target encoding.
//
// fXCoder
// This the transcoder that we will use. It is created using the
// encoding name we were told to use.
//
// fTmpBuf
// An output buffer that we use to transcode chars into before we
// send them off to be output.
//
// fAposRef
// fAmpRef
// fGTRef
// fLTRef
// fQuoteRef
// These are character refs for the standard char refs, in the
// output encoding. They are faulted in as required, by transcoding
// them from fixed Unicode versions.
// -----------------------------------------------------------------------
EscapeFlags fEscapeFlags;
XMLCh* fOutEncoding;
XMLFormatTarget* fTarget;
UnRepFlags fUnRepFlags;
XMLTranscoder* fXCoder;
XMLByte fTmpBuf[kTmpBufSize + 4];
XMLByte* fAposRef;
unsigned int fAposLen;
XMLByte* fAmpRef;
unsigned int fAmpLen;
XMLByte* fGTRef;
unsigned int fGTLen;
XMLByte* fLTRef;
unsigned int fLTLen;
XMLByte* fQuoteRef;
unsigned int fQuoteLen;
};
class XMLPARSER_EXPORT XMLFormatTarget
{
public:
// -----------------------------------------------------------------------
// Constructors and Destructor
// -----------------------------------------------------------------------
virtual ~XMLFormatTarget() {}
// -----------------------------------------------------------------------
// Virtual interface
// -----------------------------------------------------------------------
virtual void writeChars
(
const XMLByte* const toWrite
, const unsigned int count
, XMLFormatter* const formatter
) = 0;
virtual void flush() {};
protected :
// -----------------------------------------------------------------------
// Hidden constructors and operators
// -----------------------------------------------------------------------
XMLFormatTarget() {}
XMLFormatTarget(const XMLFormatTarget&) {}
void operator=(const XMLFormatTarget&) {}
};
// ---------------------------------------------------------------------------
// XMLFormatter: Getter methods
// ---------------------------------------------------------------------------
inline const XMLCh* XMLFormatter::getEncodingName() const
{
return fOutEncoding;
}
inline const XMLTranscoder* XMLFormatter::getTranscoder() const
{
return fXCoder;
}
// ---------------------------------------------------------------------------
// XMLFormatter: Setter methods
// ---------------------------------------------------------------------------
inline void XMLFormatter::setEscapeFlags(const EscapeFlags newFlags)
{
fEscapeFlags = newFlags;
}
inline void XMLFormatter::setUnRepFlags(const UnRepFlags newFlags)
{
fUnRepFlags = newFlags;
}
inline XMLFormatter& XMLFormatter::operator<<(const EscapeFlags newFlags)
{
fEscapeFlags = newFlags;
return *this;
}
inline XMLFormatter& XMLFormatter::operator<<(const UnRepFlags newFlags)
{
fUnRepFlags = newFlags;
return *this;
}
XERCES_CPP_NAMESPACE_END
#endif