Line data Source code
1 : /****************************************************************************/
2 : // Eclipse SUMO, Simulation of Urban MObility; see https://eclipse.dev/sumo
3 : // Copyright (C) 2012-2025 German Aerospace Center (DLR) and others.
4 : // This program and the accompanying materials are made available under the
5 : // terms of the Eclipse Public License 2.0 which is available at
6 : // https://www.eclipse.org/legal/epl-2.0/
7 : // This Source Code may also be made available under the following Secondary
8 : // Licenses when the conditions for such availability set forth in the Eclipse
9 : // Public License 2.0 are satisfied: GNU General Public License, version 2
10 : // or later which is available at
11 : // https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html
12 : // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-or-later
13 : /****************************************************************************/
14 : /// @file OutputFormatter.h
15 : /// @author Daniel Krajzewicz
16 : /// @author Michael Behrisch
17 : /// @date 2012
18 : ///
19 : // Abstract base class for output formatters
20 : /****************************************************************************/
21 : #pragma once
22 : #include <config.h>
23 :
24 : #include <string>
25 : #include <vector>
26 : #include <utils/xml/SUMOXMLDefinitions.h>
27 :
28 :
29 : // ===========================================================================
30 : // class declarations
31 : // ===========================================================================
32 : class Boundary;
33 : class Position;
34 : class PositionVector;
35 : class RGBColor;
36 :
37 :
38 : // ===========================================================================
39 : // class definitions
40 : // ===========================================================================
41 : enum class OutputFormatterType {
42 : XML,
43 : #ifdef HAVE_PARQUET
44 : PARQUET,
45 : #endif
46 : CSV
47 : };
48 :
49 : /**
50 : * @class OutputFormatter
51 : * @brief Abstract base class for output formatters
52 : *
53 : * OutputFormatter format XML like output into the output stream.
54 : * There are only two implementation at the moment, "normal" XML
55 : * and binary XML.
56 : */
57 : class OutputFormatter {
58 : public:
59 : /// @brief Constructor
60 1571703 : OutputFormatter(OutputFormatterType t) : myType(t) { }
61 :
62 : /// @brief Destructor
63 : virtual ~OutputFormatter() { }
64 :
65 : /** @brief Writes an XML header with optional configuration
66 : *
67 : * If something has been written (myXMLStack is not empty), nothing
68 : * is written and false returned.
69 : * The default implementation does nothing and returns false.
70 : *
71 : * @param[in] into The output stream to use
72 : * @param[in] rootElement The root element to use
73 : * @param[in] attrs Additional attributes to save within the rootElement
74 : * @param[in] includeConfig whether the current config should be included as XML comment
75 : * @return whether something has been written
76 : */
77 30 : virtual bool writeXMLHeader(std::ostream& into, const std::string& rootElement,
78 : const std::map<SumoXMLAttr, std::string>& attrs, bool writeMetadata,
79 : bool includeConfig) {
80 : UNUSED_PARAMETER(into);
81 : UNUSED_PARAMETER(rootElement);
82 : UNUSED_PARAMETER(attrs);
83 : UNUSED_PARAMETER(writeMetadata);
84 : UNUSED_PARAMETER(includeConfig);
85 30 : return false;
86 : }
87 :
88 : /** @brief Opens an XML tag
89 : *
90 : * An indentation, depending on the current xml-element-stack size, is written followed
91 : * by the given xml element ("<" + xmlElement)
92 : * The xml element is added to the stack, then.
93 : *
94 : * @param[in] into The output stream to use
95 : * @param[in] xmlElement Name of element to open
96 : * @return The OutputDevice for further processing
97 : */
98 : virtual void openTag(std::ostream& into, const std::string& xmlElement) = 0;
99 :
100 : /** @brief Opens an XML tag
101 : *
102 : * Helper method which finds the correct string before calling openTag.
103 : *
104 : * @param[in] into The output stream to use
105 : * @param[in] xmlElement Id of the element to open
106 : */
107 : virtual void openTag(std::ostream& into, const SumoXMLTag& xmlElement) = 0;
108 :
109 : virtual void writeTime(std::ostream& into, const SumoXMLAttr attr, const SUMOTime val) = 0;
110 :
111 : /** @brief Closes the most recently opened tag and optinally add a comment
112 : *
113 : * @param[in] into The output stream to use
114 : * @return Whether a further element existed in the stack and could be closed
115 : * @todo it is not verified that the topmost element was closed
116 : */
117 : virtual bool closeTag(std::ostream& into, const std::string& comment = "") = 0;
118 :
119 : /** @brief Writes a preformatted tag to the device but ensures that any
120 : * pending tags are closed.
121 : * This method is only implemented for XML output.
122 : * @param[in] into The output stream to use
123 : * @param[in] val The preformatted data
124 : */
125 0 : virtual void writePreformattedTag(std::ostream& into, const std::string& val) {
126 : UNUSED_PARAMETER(into);
127 : UNUSED_PARAMETER(val);
128 0 : throw ProcessError("The selected file format does not support preformatted tags.");
129 : }
130 :
131 : /** @brief Writes some whitespace to format the output.
132 : * This method is only implemented for XML output.
133 : * @param[in] into The output stream to use
134 : * @param[in] val The whitespace
135 : */
136 0 : virtual void writePadding(std::ostream& into, const std::string& val) {
137 : UNUSED_PARAMETER(into);
138 : UNUSED_PARAMETER(val);
139 0 : }
140 :
141 : /** @brief Returns whether a header has been written.
142 : * Useful to detect whether a file is being used by multiple sources.
143 : * @return Whether a header has been written
144 : */
145 : virtual bool wroteHeader() const = 0;
146 :
147 : /** @brief Returns the type of formatter being used.
148 : * @return the formatter type
149 : */
150 : OutputFormatterType getType() {
151 90809910 : return myType;
152 : }
153 :
154 : /** @brief Set the expected attributes to write.
155 : * This is used for tracking which attributes are expected in table like outputs.
156 : * This should be not necessary but at least in the initial phase of implementing CSV and Parquet
157 : * it helps a lot to track errors.
158 : * @param[in] expected which attributes are to be written (at the deepest XML level)
159 : * @param[in] depth the maximum XML hierarchy depth (excluding the root)
160 : */
161 3034 : virtual void setExpectedAttributes(const SumoXMLAttrMask& expected, const int depth = 2) {
162 : UNUSED_PARAMETER(expected);
163 : UNUSED_PARAMETER(depth);
164 3034 : }
165 :
166 : private:
167 : /// @brief the type of formatter being used (XML, CSV, Parquet, etc.)
168 : const OutputFormatterType myType;
169 : };
|
