foamVtkFormatter.H

Go to the documentation of this file.

/*---------------------------------------------------------------------------*\
  =========                 |
  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
   \\    /   O peration     |
    \\  /    A nd           | www.openfoam.com
     \\/     M anipulation  |
-------------------------------------------------------------------------------
    Copyright (C) 2016-2025 OpenCFD Ltd.
-------------------------------------------------------------------------------
License
    This file is part of OpenFOAM.
 
    OpenFOAM is free software: you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
 
    OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
    for more details.
 
    You should have received a copy of the GNU General Public License
    along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
 
Class
    Foam::vtk::formatter
 
Description
    Abstract class for a VTK output stream formatter.
 
    Includes simple support for writing XML elements.
    By default uses single-quoting for XML attributes.
 
SourceFiles
    foamVtkFormatter.cxx
    foamVtkFormatter.txx
    foamVtkFormatterI.H
 
\*---------------------------------------------------------------------------*/
 
#ifndef Foam_vtk_formatter_H
#define Foam_vtk_formatter_H
 
#include "int.H"
#include "label.H"
#include "uint64.H"
#include "direction.H"
#include "word.H"
#include "List.H"
#include "DynamicList.H"
#include "foamVtkCore.H"
#include "foamVtkPTraits.H"
 
#include <iostream>
 
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
namespace Foam
{
namespace vtk
{
 
// Forward Declarations
class outputOptions;
 
/*---------------------------------------------------------------------------*\
                       Class vtk::formatter Declaration
\*---------------------------------------------------------------------------*/
 
class formatter
{
public:
 
    //- Quoting for XML attributes
    enum quoteChar : char
    {
        DOUBLE_QUOTE = '\"',  
        SINGLE_QUOTE = '\'',  
    };
 
 
protected:
 
    // Private Data
 
        //- The output stream for the formatter
        std::ostream& os_;
 
        //- LIFO stack of current XML tags
        DynamicList<word> xmlTags_;
 
        //- Tag open/closed/ended state
        mutable bool inTag_;
 
        //- Quoting character for XML attributes
        char quote_;
 
 
protected:
 
    // Protected Member Functions
 
        //- Can write XML key/value attribute pair when inside a tag.
        //- Emit warning and return false if this condition is not met.
        bool canWriteAttr(const word& k) const;
 
        //- Can write tag-like top-level content (eg, comment, ...)
        //- when not already inside a tag.
        //- Emit warning and return false if this condition is not met.
        bool canWriteToplevel(const char* what) const;
 
        //- Write XML key/value attribute pair (implementation).
        template<class Type>
        inline void writeAttr(const word& k, const Type& v);
 
        //- No-op write XML attribute (for templating code).
        //  \return formatter for chaining
        inline formatter& xmlAttr();
 
        //- Loop/output XML comments
        template<class... Args>
        inline void xmlCommentLoop(const std::string& text, Args&&... args);
 
        //- Open XML tag (implementation), checking if not already inside
        //- another tag.
        //- Emit warning and return false if this condition is not met.
        bool openTagImpl(const word& tagName);
 
 
    // Constructors
 
        //- Construct and attach to an output stream
        inline explicit formatter(std::ostream& os);
 
 
public:
 
    // Public typedefs
 
        //- The header data is vtk UInt64
        typedef uint64_t headerType;
 
        //- Out of range position or size.
        static constexpr uint64_t npos = uint64_t(-1);
 
 
    //- Destructor
    virtual ~formatter() = default;
 
 
    // Member Functions
 
    // Access
 
        //- Access to the underlying output stream
        inline std::ostream& os() noexcept;
 
        //- The format-type / output options.
        virtual const vtk::outputOptions& opts() const = 0;
 
        //- Name for the XML output type or the legacy output type.
        virtual const char* name() const = 0;
 
        //- Name for the XML append encoding
        virtual const char* encoding() const = 0;
 
        //- Change quoting char for XML attributes (default: SINGLE_QUOTE)
        void quoting(quoteChar quote) noexcept;
 
        //- Increase the append data offset by numbytes and sizeof(uint64_t).
        //  The additional (uint64_t) size information is consistent with
        //  writeSize()
        //
        //  \return The previous data offset or formatter::npos for formats
        //     that do not support appending data.
        virtual uint64_t offset(const uint64_t numbytes);
 
        //- The encoded length for binary output is pass-through.
        virtual std::size_t encodedLength(std::size_t n) const;
 
        //- Write leading size for binary output
        //  \return True if used by the formatter.
        virtual bool writeSize(const uint64_t numbytes) = 0;
 
        virtual void write(const uint8_t val) = 0;
        virtual void write(const label val)   = 0;
        virtual void write(const float val)   = 0;
        virtual void write(const double val)  = 0;
 
        //- Flush encoding, write newline etc.
        virtual void flush() = 0;
 
 
    // General Output
 
        //- Add indenting according to the current XML tag depth
        //  Two spaces per depth.
        inline void indent();
 
        //- Add indenting of n spaces.
        inline void indent(label n);
 
        //- Write XML header
        //  \return formatter for chaining
        inline formatter& xmlHeader();
 
        //- Write XML comment (at the current indentation level)
        //  \return formatter for chaining
        template<class... Args>
        inline formatter& xmlComment(const std::string& text, Args&&... args);
 
 
        //- Start an XML tag, optionally with attributes
        //  \return formatter for chaining
        template<class... Args>
        inline formatter& openTag(const word& tagName, Args&&... args);
 
        //- Start an XML tag, optionally with attributes
        //  \return formatter for chaining
        template<class... Args>
        inline formatter& openTag(vtk::fileTag t, Args&&... args);
 
        //- Finish an XML tag, optional as an empty container.
        //  Always adds a trailing newline.
        //  \return formatter for chaining
        formatter& closeTag(const bool isEmpty = false);
 
        //- An end XML tag, optional with sanity check
        //  Always adds a trailing newline.
        //  \return formatter for chaining
        formatter& endTag(const word& tagName = word::null);
 
        //- An end XML tag with sanity check
        //  Always adds a trailing newline.
        //  \return formatter for chaining
        inline virtual formatter& endTag(vtk::fileTag t);
 
        //- Write XML tag without any attributes. Combines openTag/closeTag.
        //  \return formatter for chaining
        template<class... Args>
        inline formatter& tag(const word& t, Args&&... args);
 
        //- Write XML tag without any attributes. Combines openTag/closeTag.
        //  \return formatter for chaining
        template<class... Args>
        inline formatter& tag(vtk::fileTag t, Args&&... args);
 
 
        //- Add a "VTKFile" XML tag for contentType, followed by a tag for
        //- the contentType itself.
        //  \param leaveOpen Leave tag open for additional attributes.
        //  \return formatter for chaining
        formatter& beginVTKFile
        (
            const word& contentType,
            const word& contentVersion,
            const bool leaveOpen = false
        );
 
        //- Add a "VTKFile" XML tag for contentType, followed by a tag for
        //- the contentType itself.
        //  \param leaveOpen Leave tag open for additional attributes.
        //  \return formatter for chaining
        inline formatter& beginVTKFile
        (
            vtk::fileTag contentType,
            const word& contentVersion,
            const bool leaveOpen = false
        );
 
        //- Add a "VTKFile" XML tag for contentType, followed by a tag for
        //- the contentType itself.
        //  \param leaveOpen Leave tag open for additional attributes.
        //  \return formatter for chaining
        inline formatter& beginVTKFile
        (
            vtk::fileTag contentType,
            const bool leaveOpen = false
        );
 
        //- Add a "VTKFile" XML tag for contentType, followed by a tag for
        //- the contentType itself.
        //  \param leaveOpen Leave tag open for additional attributes.
        //  \return formatter for chaining
        template<vtk::fileTag ContentType>
        inline formatter& beginVTKFile(bool leaveOpen = false);
 
        //- Add a "AppendedData" XML tag with the current encoding and output
        //- the requisite '_' prefix.
        //  \return formatter for chaining
        formatter& beginAppendedData();
 
        //- Begin "Block" XML section.
        //  \param index The index of the block
        //  \param name The name of the block (ignored if empty)
        //  \return formatter for chaining
        formatter& beginBlock(label index, std::string name = "");
 
        //- End "Block" XML section.
        //  \return formatter for chaining
        inline formatter& endBlock();
 
        //- Begin "Piece" XML section.
        //  \param index The index of the piece
        //  \param name The name of the piece (ignored if empty)
        //  \return formatter for chaining
        formatter& beginPiece(label index, std::string name = "");
 
        //- End "Piece" XML section.
        //  \return formatter for chaining
        inline virtual formatter& endPiece();
 
        //- Insert a single "DataSet" XML entry tag.
        //  \param index The index of the DataSet
        //  \param file The file name for the data (ignored if empty)
        //  \param autoName The name for the data extracted from the file name
        //      (without extension)
        //  \return formatter for chaining
        formatter& DataSet
        (
            label index,
            std::string file = "",
            bool autoName = true
        );
 
        //- Insert a single "DataSet" XML entry tag.
        //  \param index The index of the DataSet
        //  \param file The file name for the data (ignored if empty)
        //  \param name The name for the dataset
        //  \return formatter for chaining
        formatter& DataSet
        (
            label index,
            std::string file,
            std::string name
        );
 
        //- Begin "DataArray" XML section.
        //
        //  \param dataName The name of the DataArray
        //  \param payLoad  Additional payLoad information to increment
        //     the offset for an append formatter and add the "offset"
        //     attribute accordingly.
        //  \param leaveOpen Leave tag open for additional attributes.
        //
        //  \return formatter for chaining
        template<class Type, direction nComp=1, int nTuple=0>
        formatter& beginDataArray
        (
            const word& dataName,
            uint64_t payLoad = npos,
            bool leaveOpen = false
        );
 
        //- Begin "DataArray" XML section.
        //
        //  \param dataName The name of the DataArray as an enumeration
        //  \param payLoad  Additional payLoad information to increment
        //     the offset for an append formatter and add the "offset"
        //     attribute accordingly.
        //  \param leaveOpen Leave tag open for additional attributes.
        //
        //  \return formatter for chaining
        template<class Type, direction nComp=1, int nTuple=0>
        inline formatter& beginDataArray
        (
            const vtk::dataArrayAttr& dataName,
            uint64_t payLoad = npos,
            bool leaveOpen = false
        );
 
        //- End "DataArray" XML section
        //  \return formatter for chaining
        inline virtual formatter& endDataArray();
 
        //- Insert a single "PDataArray" XML entry tag.
        //  For some entries, the name is optional.
        //  \return formatter for chaining
        template<class Type, direction nComp=1, int nTuple=0>
        formatter& PDataArray(const word& dataName);
 
 
        //- Begin "FieldData" XML section.
        inline formatter& beginFieldData();
 
        //- Begin "CellData" XML section.
        inline formatter& beginCellData();
 
        //- Begin "PointData" XML section.
        inline formatter& beginPointData();
 
        //- End "FieldData" XML section.
        inline virtual formatter& endFieldData();
 
        //- End "CellData" XML section.
        inline virtual formatter& endCellData();
 
        //- End "PointData" XML section.
        inline virtual formatter& endPointData();
 
 
        //- End "AppendedData" XML section
        //  \return formatter for chaining
        formatter& endAppendedData();
 
        //- End "VTKFile" XML section.
        //  \return formatter for chaining
        inline virtual formatter& endVTKFile();
 
 
        //- Emit "TimeValue" for FieldData (name as per Catalyst output)
        formatter& writeTimeValue(scalar timeValue);
 
 
    // XML Attributes
 
        //- Pair-wise write of XML key/value attributes
        //  \return formatter for chaining
        template<class... Args>
        inline formatter& xmlAttr
        (
            const word& k,
            const std::string& v,
            Args&&... args
        );
 
        //- Pair-wise write of XML key/value attributes
        //  \return formatter for chaining
        template<class... Args>
        inline formatter& xmlAttr
        (
            const word& k,
            const int32_t v,
            Args&&... args
        );
 
        //- Pair-wise write of XML key/value attributes
        //  \return formatter for chaining
        template<class... Args>
        inline formatter& xmlAttr
        (
            const word& k,
            const int64_t v,
            Args&&... args
        );
 
        //- Pair-wise write of XML key/value attributes
        //  \return formatter for chaining
        template<class... Args>
        inline formatter& xmlAttr
        (
            const word& k,
            const uint64_t v,
            Args&&... args
        );
 
        //- Pair-wise write of XML key/value attributes
        //  \return formatter for chaining
        template<class... Args>
        inline formatter& xmlAttr
        (
            const word& k,
            const scalar v,
            Args&&... args
        );
 
        //- Pair-wise write of XML key/value attributes
        //  \return formatter for chaining
        template<class... Args>
        inline formatter& xmlAttr
        (
            const vtk::fileAttr& k,
            const std::string& v,
            Args&&... args
        );
 
        //- Pair-wise write of XML key/value attributes
        //  \return formatter for chaining
        template<class... Args>
        inline formatter& xmlAttr
        (
            const vtk::fileAttr& k,
            const int32_t v,
            Args&&... args
        );
 
        //- Pair-wise write of XML key/value attributes
        //  \return formatter for chaining
        template<class... Args>
        inline formatter& xmlAttr
        (
            const vtk::fileAttr& k,
            const int64_t v,
            Args&&... args
        );
 
        //- Pair-wise write of XML key/value attributes
        //  \return formatter for chaining
        template<class... Args>
        inline formatter& xmlAttr
        (
            const vtk::fileAttr& k,
            const uint64_t v,
            Args&&... args
        );
 
        //- Pair-wise write of XML key/value attributes
        //  \return formatter for chaining
        template<class... Args>
        inline formatter& xmlAttr
        (
            const vtk::fileAttr& k,
            const scalar v,
            Args&&... args
        );
 
 
    // Housekeeping
 
        //- Open "DataArray" XML tag and leave open (requires a closeTag).
        //  \deprecated Use beginDataArray instead (SEPT-2018)
        template<class Type, direction nComp=1, int nTuple=0>
        formatter& openDataArray(const word& dataName)
        {
            return beginDataArray<Type, nComp, nTuple>
            (
                dataName, formatter::npos, true
            );
        }
 
        //- Open "DataArray" XML tag and leave open (requires a closeTag).
        //  \deprecated Use beginDataArray instead (SEPT-2018)
        template<class Type, direction nComp=1, int nTuple=0>
        formatter& openDataArray(const vtk::dataArrayAttr& dataName)
        {
            return beginDataArray<Type, nComp, nTuple>
            (
                dataName, formatter::npos, true
            );
        }
};
 
 
// Global Functions
 
//- Commonly used calculation for header and payload sizes
template<class Type, direction nComp=1>
inline uint64_t sizeofData(label count)
{
    return (count * nComp * sizeof(Type));
}
 
 
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
} // End namespace vtk
} // End namespace Foam
 
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
#include "foamVtkFormatterI.H"
 
#ifdef NoRepository
    #include "foamVtkFormatter.txx"
#endif
 
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
#endif
 
// ************************************************************************* //