HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
XmlIo.h
Go to the documentation of this file.
1 //
2 // Copyright Contributors to the MaterialX Project
3 // SPDX-License-Identifier: Apache-2.0
4 //
5 
6 #ifndef MATERIALX_XMLIO_H
7 #define MATERIALX_XMLIO_H
8 
9 /// @file
10 /// Support for the MTLX file format
11 
12 #include <MaterialXCore/Library.h>
13 
14 #include <MaterialXCore/Document.h>
15 
16 #include <MaterialXFormat/Export.h>
17 #include <MaterialXFormat/File.h>
18 
20 
21 class XmlReadOptions;
22 
23 extern MX_FORMAT_API const string MTLX_EXTENSION;
24 
25 /// A standard function that reads from an XML file into a Document, with
26 /// optional search path and read options.
27 using XmlReadFunction = std::function<void(DocumentPtr, const FilePath&, const FileSearchPath&, const XmlReadOptions*)>;
28 
29 /// @class XmlReadOptions
30 /// A set of options for controlling the behavior of XML read functions.
32 {
33  public:
36 
37  /// If true, then XML comments will be read into documents as comment elements.
38  /// Defaults to false.
40 
41  /// If true, then XML newlines will be read into documents as newline elements.
42  /// Defaults to false.
44 
45  /// If true, then documents from earlier versions of MaterialX will be upgraded
46  /// to the current version. Defaults to true.
48 
49  /// If provided, this function will be invoked when an XInclude reference
50  /// needs to be read into a document. Defaults to readFromXmlFile.
52 
53  /// The vector of parent XIncludes at the scope of the current document.
54  /// Defaults to an empty vector.
56 };
57 
58 /// @class XmlWriteOptions
59 /// A set of options for controlling the behavior of XML write functions.
61 {
62  public:
65 
66  /// If true, elements with source file markings will be written as
67  /// XIncludes rather than explicit data. Defaults to true.
69 
70  /// If provided, this function will be used to exclude specific elements
71  /// (those returning false) from the write operation. Defaults to nullptr.
73 };
74 
75 /// @class ExceptionParseError
76 /// An exception that is thrown when a requested document cannot be parsed.
78 {
79  public:
81 };
82 
83 /// @class ExceptionFileMissing
84 /// An exception that is thrown when a requested file cannot be opened.
86 {
87  public:
89 };
90 
91 /// @name Read Functions
92 /// @{
93 
94 /// Read a Document as XML from the given character buffer.
95 /// @param doc The Document into which data is read.
96 /// @param buffer The character buffer from which data is read.
97 /// @param searchPath An optional sequence of file paths that will be applied
98 /// in order when searching for the given file and its includes. This
99 /// argument can be supplied either as a FileSearchPath, or as a standard
100 /// string with paths separated by the PATH_SEPARATOR character.
101 /// @param readOptions An optional pointer to an XmlReadOptions object.
102 /// If provided, then the given options will affect the behavior of the
103 /// read function. Defaults to a null pointer.
104 /// @throws ExceptionParseError if the document cannot be parsed.
105 MX_FORMAT_API void readFromXmlBuffer(DocumentPtr doc, const char* buffer, FileSearchPath searchPath = FileSearchPath(), const XmlReadOptions* readOptions = nullptr);
106 
107 /// Read a Document as XML from the given input stream.
108 /// @param doc The Document into which data is read.
109 /// @param stream The input stream from which data is read.
110 /// @param searchPath An optional sequence of file paths that will be applied
111 /// in order when searching for the given file and its includes. This
112 /// argument can be supplied either as a FileSearchPath, or as a standard
113 /// string with paths separated by the PATH_SEPARATOR character.
114 /// @param readOptions An optional pointer to an XmlReadOptions object.
115 /// If provided, then the given options will affect the behavior of the
116 /// read function. Defaults to a null pointer.
117 /// @throws ExceptionParseError if the document cannot be parsed.
118 MX_FORMAT_API void readFromXmlStream(DocumentPtr doc, std::istream& stream, FileSearchPath searchPath = FileSearchPath(), const XmlReadOptions* readOptions = nullptr);
119 
120 /// Read a Document as XML from the given filename.
121 /// @param doc The Document into which data is read.
122 /// @param filename The filename from which data is read. This argument can
123 /// be supplied either as a FilePath or a standard string.
124 /// @param searchPath An optional sequence of file paths that will be applied
125 /// in order when searching for the given file and its includes. This
126 /// argument can be supplied either as a FileSearchPath, or as a standard
127 /// string with paths separated by the PATH_SEPARATOR character.
128 /// @param readOptions An optional pointer to an XmlReadOptions object.
129 /// If provided, then the given options will affect the behavior of the read
130 /// function. Defaults to a null pointer.
131 /// @throws ExceptionParseError if the document cannot be parsed.
132 /// @throws ExceptionFileMissing if the file cannot be opened.
135  FileSearchPath searchPath = FileSearchPath(),
136  const XmlReadOptions* readOptions = nullptr);
137 
138 /// Read a Document as XML from the given string.
139 /// @param doc The Document into which data is read.
140 /// @param str The string from which data is read.
141 /// @param searchPath An optional sequence of file paths that will be applied
142 /// in order when searching for the given file and its includes. This
143 /// argument can be supplied either as a FileSearchPath, or as a standard
144 /// string with paths separated by the PATH_SEPARATOR character.
145 /// @param readOptions An optional pointer to an XmlReadOptions object.
146 /// If provided, then the given options will affect the behavior of the
147 /// read function. Defaults to a null pointer.
148 /// @throws ExceptionParseError if the document cannot be parsed.
149 MX_FORMAT_API void readFromXmlString(DocumentPtr doc, const string& str, const FileSearchPath& searchPath = FileSearchPath(), const XmlReadOptions* readOptions = nullptr);
150 
151 /// @}
152 /// @name Write Functions
153 /// @{
154 
155 /// Write a Document as XML to the given output stream.
156 /// @param doc The Document to be written.
157 /// @param stream The output stream to which data is written
158 /// @param writeOptions An optional pointer to an XmlWriteOptions object.
159 /// If provided, then the given options will affect the behavior of the
160 /// write function. Defaults to a null pointer.
161 MX_FORMAT_API void writeToXmlStream(DocumentPtr doc, std::ostream& stream, const XmlWriteOptions* writeOptions = nullptr);
162 
163 /// Write a Document as XML to the given filename.
164 /// @param doc The Document to be written.
165 /// @param filename The filename to which data is written. This argument can
166 /// be supplied either as a FilePath or a standard string.
167 /// @param writeOptions An optional pointer to an XmlWriteOptions object.
168 /// If provided, then the given options will affect the behavior of the
169 /// write function. Defaults to a null pointer.
170 MX_FORMAT_API void writeToXmlFile(DocumentPtr doc, const FilePath& filename, const XmlWriteOptions* writeOptions = nullptr);
171 
172 /// Write a Document as XML to a new string, returned by value.
173 /// @param doc The Document to be written.
174 /// @param writeOptions An optional pointer to an XmlWriteOptions object.
175 /// If provided, then the given options will affect the behavior of the
176 /// write function. Defaults to a null pointer.
177 /// @return The output string, returned by value
178 MX_FORMAT_API string writeToXmlString(DocumentPtr doc, const XmlWriteOptions* writeOptions = nullptr);
179 
180 /// @}
181 /// @name Edit Functions
182 /// @{
183 
184 /// Add an XInclude reference to the top of a Document, creating a generic
185 /// element to hold the reference filename.
186 /// @param doc The Document to be modified.
187 /// @param filename The filename of the XInclude reference to be added.
188 MX_FORMAT_API void prependXInclude(DocumentPtr doc, const FilePath& filename);
189 
190 /// @}
191 
193 
194 #endif
GLuint GLuint stream
Definition: glcorearb.h:1832
MX_FORMAT_API void readFromXmlStream(DocumentPtr doc, std::istream &stream, FileSearchPath searchPath=FileSearchPath(), const XmlReadOptions *readOptions=nullptr)
GT_API const UT_StringHolder filename
StringVec parentXIncludes
Definition: XmlIo.h:55
Definition: File.h:26
std::function< bool(ConstElementPtr)> ElementPredicate
A standard function taking an ElementPtr and returning a boolean.
Definition: Element.h:72
#define MATERIALX_NAMESPACE_BEGIN
Definition: Generated.h:25
vector< string > StringVec
A vector of strings.
Definition: Library.h:57
MX_FORMAT_API void writeToXmlFile(DocumentPtr doc, const FilePath &filename, const XmlWriteOptions *writeOptions=nullptr)
#define MX_FORMAT_API
Definition: Export.h:18
bool readNewlines
Definition: XmlIo.h:43
bool upgradeVersion
Definition: XmlIo.h:47
MX_FORMAT_API const string MTLX_EXTENSION
MX_FORMAT_API void readFromXmlFile(DocumentPtr doc, FilePath filename, FileSearchPath searchPath=FileSearchPath(), const XmlReadOptions *readOptions=nullptr)
MX_FORMAT_API void readFromXmlBuffer(DocumentPtr doc, const char *buffer, FileSearchPath searchPath=FileSearchPath(), const XmlReadOptions *readOptions=nullptr)
Definition: core.h:760
MX_FORMAT_API void writeToXmlStream(DocumentPtr doc, std::ostream &stream, const XmlWriteOptions *writeOptions=nullptr)
XmlReadFunction readXIncludeFunction
Definition: XmlIo.h:51
bool writeXIncludeEnable
Definition: XmlIo.h:68
MX_FORMAT_API void readFromXmlString(DocumentPtr doc, const string &str, const FileSearchPath &searchPath=FileSearchPath(), const XmlReadOptions *readOptions=nullptr)
shared_ptr< Document > DocumentPtr
A shared pointer to a Document.
Definition: Document.h:22
~XmlReadOptions()
Definition: XmlIo.h:35
~XmlWriteOptions()
Definition: XmlIo.h:64
bool readComments
Definition: XmlIo.h:39
Exception(const string &msg)
Definition: Exception.h:24
MX_FORMAT_API string writeToXmlString(DocumentPtr doc, const XmlWriteOptions *writeOptions=nullptr)
#define MATERIALX_NAMESPACE_END
Definition: Generated.h:26
MX_FORMAT_API void prependXInclude(DocumentPtr doc, const FilePath &filename)
std::function< void(DocumentPtr, const FilePath &, const FileSearchPath &, const XmlReadOptions *)> XmlReadFunction
Definition: XmlIo.h:27
ElementPredicate elementPredicate
Definition: XmlIo.h:72