1 /** 2 * @file MathML.h 3 * @brief Utilities for reading and writing MathML to/from text strings. 4 * @author Ben Bornstein 5 * 6 * <!-------------------------------------------------------------------------- 7 * This file is part of libSBML. Please visit http://sbml.org for more 8 * information about SBML, and the latest version of libSBML. 9 * 10 * Copyright (C) 2020 jointly by the following organizations: 11 * 1. California Institute of Technology, Pasadena, CA, USA 12 * 2. University of Heidelberg, Heidelberg, Germany 13 * 3. University College London, London, UK 14 * 15 * Copyright (C) 2019 jointly by the following organizations: 16 * 1. California Institute of Technology, Pasadena, CA, USA 17 * 2. University of Heidelberg, Heidelberg, Germany 18 * 19 * Copyright (C) 2013-2018 jointly by the following organizations: 20 * 1. California Institute of Technology, Pasadena, CA, USA 21 * 2. EMBL European Bioinformatics Institute (EMBL-EBI), Hinxton, UK 22 * 3. University of Heidelberg, Heidelberg, Germany 23 * 24 * Copyright (C) 2009-2013 jointly by the following organizations: 25 * 1. California Institute of Technology, Pasadena, CA, USA 26 * 2. EMBL European Bioinformatics Institute (EMBL-EBI), Hinxton, UK 27 * 28 * Copyright (C) 2006-2008 by the California Institute of Technology, 29 * Pasadena, CA, USA 30 * 31 * Copyright (C) 2002-2005 jointly by the following organizations: 32 * 1. California Institute of Technology, Pasadena, CA, USA 33 * 2. Japan Science and Technology Agency, Japan 34 * 35 * This library is free software; you can redistribute it and/or modify it 36 * under the terms of the GNU Lesser General Public License as published by 37 * the Free Software Foundation. A copy of the license agreement is provided 38 * in the file named "LICENSE.txt" included with this software distribution and 39 * also available online as http://sbml.org/software/libsbml/license.html 40 * ---------------------------------------------------------------------- -->*/ 41 42 #ifndef MathML_h 43 #define MathML_h 44 45 46 #include <sbml/common/extern.h> 47 #include <sbml/common/sbmlfwd.h> 48 49 50 #ifdef __cplusplus 51 52 #include <limits> 53 #include <iomanip> 54 #include <string> 55 #include <sstream> 56 57 #include <cstdlib> 58 59 LIBSBML_CPP_NAMESPACE_BEGIN 60 61 /** @cond doxygenLibsbmlInternal */ 62 63 class ASTNode; 64 class XMLInputStream; 65 class XMLOutputStream; 66 67 68 /** 69 * Reads the MathML from the given XMLInputStream, constructs a corresponding 70 * abstract syntax tree and returns a pointer to the root of the tree. 71 */ 72 LIBSBML_EXTERN 73 ASTNode* 74 readMathML (XMLInputStream& stream, std::string reqd_prefix="", bool inRead = true); 75 76 77 /** 78 * Writes the given ASTNode (and its children) to the XMLOutputStream_t as 79 * MathML. 80 */ 81 LIBSBML_EXTERN 82 void 83 writeMathML (const ASTNode* node, XMLOutputStream& stream, SBMLNamespaces *sbmlns=NULL); 84 /** @endcond */ 85 86 87 #ifndef SWIG 88 89 /** 90 * Writes the given ASTNode to an in-memory string that is returned. 91 * 92 * @param node the root of an AST to write out to the string. 93 * 94 * @return the string containing the written-out MathML representation 95 * of the given AST on success or an empty string, 96 * if one of the underlying parser 97 * components fail. 98 * 99 */ 100 LIBSBML_EXTERN 101 std::string 102 writeMathMLToStdString(const ASTNode* node); 103 104 /** 105 * Writes the given ASTNode to an in-memory string that is returned. 106 * 107 * @param node the root of an AST to write out to the string. 108 * @param ns the optional sbml namespace to be used when specifying units 109 * 110 * @return the string containing the written-out MathML representation 111 * of the given AST on success or an empty string, 112 * if one of the underlying parser 113 * components fail. 114 * 115 */ 116 LIBSBML_EXTERN 117 std::string 118 writeMathMLToStdString(const ASTNode* node, SBMLNamespaces* ns); 119 120 121 #endif 122 123 LIBSBML_CPP_NAMESPACE_END 124 125 #endif /* __cplusplus */ 126 127 LIBSBML_CPP_NAMESPACE_BEGIN 128 BEGIN_C_DECLS 129 130 131 /** 132 * Reads the MathML from the given XML string, constructs a corresponding 133 * abstract syntax tree, and returns a pointer to the root of the tree. 134 * 135 * @param xml a string containing a full MathML expression. 136 * 137 * @return the root of an AST corresponding to the given mathematical 138 * expression, otherwise @c NULL is returned if the given string is @c NULL 139 * or invalid. 140 * 141 * @if conly 142 * @memberof ASTNode_t 143 * @endif 144 */ 145 LIBSBML_EXTERN 146 ASTNode_t * 147 readMathMLFromString (const char *xml); 148 149 150 /** 151 * Reads the MathML from the given XML string, constructs a corresponding 152 * abstract syntax tree, and returns a pointer to the root of the tree. 153 * 154 * @param xml a string containing a full MathML expression. 155 * @param xmlns an @if conly XMLNamespaces_t structure @else XMLNamespaces 156 * object@endif@~ containing namespaces that are considered active during the 157 * read. (For example, an SBML Level 3 package namespace.) 158 * 159 * @return the root of an AST corresponding to the given mathematical 160 * expression, otherwise @c NULL is returned if the given string is @c NULL 161 * or invalid. 162 * 163 * @if conly 164 * @memberof ASTNode_t 165 * @endif 166 */ 167 LIBSBML_EXTERN 168 ASTNode_t * 169 readMathMLFromStringWithNamespaces (const char *xml, XMLNamespaces_t * xmlns); 170 171 172 /** 173 * Writes the given AST node (and its children) to a string as MathML, and 174 * returns the string. 175 * 176 * @param node the root of an AST to write out to the stream. 177 * 178 * @return a string containing the written-out MathML representation 179 * of the given AST. 180 * 181 * @note The string is owned by the caller and should be freed (with 182 * free()) when no longer needed. @c NULL is returned if the given 183 * argument is @c NULL. 184 * 185 * @if conly 186 * @memberof ASTNode_t 187 * @endif 188 */ 189 LIBSBML_EXTERN 190 char * 191 writeMathMLToString (const ASTNode_t* node); 192 193 194 /** 195 * Writes the given AST node (and its children) to a string as MathML, and 196 * returns the string. 197 * 198 * @param node the root of an AST to write out to the stream. 199 * @param sbmlns the SBML namespace to be used 200 * 201 * @return a string containing the written-out MathML representation 202 * of the given AST. 203 * 204 * @note The string is owned by the caller and should be freed (with 205 * free()) when no longer needed. @c NULL is returned if the given 206 * argument is @c NULL. 207 * 208 * @if conly 209 * @memberof ASTNode_t 210 * @endif 211 */ 212 LIBSBML_EXTERN 213 char * 214 writeMathMLWithNamespaceToString(const ASTNode_t* node, SBMLNamespaces_t* sbmlns); 215 216 217 END_C_DECLS 218 LIBSBML_CPP_NAMESPACE_END 219 220 #endif /** MathML_h **/ 221 222