new fortune
[feisty_meow.git] / nucleus / library / textual / xml_generator.h
1 #ifndef XML_GENERATOR_CLASS
2 #define XML_GENERATOR_CLASS
3
4 /*****************************************************************************\
5 *                                                                             *
6 *  Name   : xml_generator                                                     *
7 *  Author : Chris Koeritz                                                     *
8 *                                                                             *
9 *******************************************************************************
10 * Copyright (c) 2007-$now By Author.  This program is free software; you can  *
11 * redistribute it and/or modify it under the terms of the GNU General Public  *
12 * License as published by the Free Software Foundation; either version 2 of   *
13 * the License or (at your option) any later version.  This is online at:      *
14 *     http://www.fsf.org/copyleft/gpl.html                                    *
15 * Please send any updates to: fred@gruntose.com                               *
16 \*****************************************************************************/
17
18 #include <basis/astring.h>
19 #include <basis/contracts.h>
20 #include <structures/string_table.h>
21
22 namespace textual {
23
24 class tag_info;
25 class tag_stack;
26
27 //! Supports simple XML output with consistency checking.
28
29 class xml_generator
30 {
31 public:
32   enum behavioral_mods {
33     HUMAN_READABLE = 0x1,
34     CLEAN_ILLEGAL_CHARS = 0x2
35   };
36
37   xml_generator(int modifiers = HUMAN_READABLE | CLEAN_ILLEGAL_CHARS);
38     //!< creates an xml generator with the specified behavior.
39
40   virtual ~xml_generator();
41
42   DEFINE_CLASS_NAME("xml_generator");
43
44   //! the possible ways that operations here can complete.
45   enum outcomes {
46     OKAY = basis::common::OKAY,
47     NOT_FOUND = basis::common::NOT_FOUND,
48     ERRONEOUS_TAG = basis::common::INVALID //temporary until we can shed a compatibility concern.
49 //    DEF INE_OUTCOME(ERRONEOUS_TAG, -75, "The most recently opened tag must be "
50 //        "closed before a new tag can be opened and before any other tag can "
51 //        "be closed"),
52   };
53
54   static const char *outcome_name(const basis::outcome &to_name);
55     //!< reports the string version of "to_name".
56
57   void reset();  //!< throws out all accumulated information.
58
59   basis::astring generate();
60     //!< writes the current state into a string and returns it.
61     /*!< if there was an error during generation, the string will be empty.
62     note that unclosed tags are not considered an error; they will simply be
63     closed.  note that the accumulated string is not cleared after the
64     generate() invocation.  use reset() to clear out all prior state. */
65
66   void generate(basis::astring &generated);
67     //!< synonym method, writes the current state into "generated".
68
69   basis::outcome add_header(const basis::astring &tag_name, const structures::string_table &attributes);
70     //!< adds an xml style header with the "tag_name" and "attributes".
71     /*!< headers can be located anywhere in the file. */
72
73   basis::outcome open_tag(const basis::astring &tag_name, const structures::string_table &attributes);
74     //!< adds a tag with "tag_name" and the "attributes", if any.
75     /*!< this adds an item into the output string in the form: @code
76        <tag_name attrib1="value1" attrib2="value2"...> @endcode
77     it is required that you close the tag later on, after the tag's contents
78     have been added. */
79
80   basis::outcome open_tag(const basis::astring &tag_name);
81     //!< adds a tag with "tag_name" without any attributes.
82
83   basis::outcome close_tag(const basis::astring &tag_name);
84     //!< closes a previously added "tag_name".
85     /*!< this will generate xml code like so: @code
86        </tag_name> @endcode
87     note that it is an error to try to close any tag but the most recently
88     opened one. */
89
90   void close_all_tags();
91     //!< a wide-bore method that closes all outstanding tags.
92
93   basis::outcome add_content(const basis::astring &content);
94     //!< stores content into the currently opened tag.
95     /*!< it is an error to add content when no tag is open. */
96
97   void set_indentation(int to_indent);
98     //!< sets the number of spaces to indent for the human readable form.
99
100   static basis::astring clean_reserved(const basis::astring &to_modify,
101           bool replace_spaces = false);
102     //!< returns a cleaned version of "to_modify" to make it XML appropriate.
103     /*!< if "replace_spaces" is true, then any spaces will be turned into
104     their html code equivalent; this helps in attribute names. */
105
106   static void clean_reserved_mod(basis::astring &to_modify,
107           bool replace_spaces = false);
108     //!< ensures that "to_modify" contains only characters valid for XML.
109     /*!< this is only different from the other clean method because this
110     one modifies the string in place. */
111
112 private:
113   tag_stack *_tags;  //!< the already opened tags.
114   basis::astring *_accumulator;  //!< stores our output.
115   bool _human_read;  //!< true if the output should be human readable.
116   bool _clean_chars;  //!< true if strings should be validated and repaired.
117   int _indentation;  //!< number of spaces per level of xml.
118
119   enum open_types { NORMAL_TAG, HEADER_TAG };
120   void print_open_tag(const tag_info &to_print, int type = NORMAL_TAG);
121     //!< opens the tag for to_print by showing the tag name and attributes.
122   void print_close_tag(const basis::astring &tag_name);
123     //!< closes the tag for "tag_name" in the output string.
124 };
125
126 } //namespace.
127
128 #endif
129