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