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