1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22 package org.millscript.millscript.render;
23
24 import org.millscript.commons.util.IList;
25 import org.millscript.millscript.datatypes.CDATA;
26 import org.millscript.millscript.datatypes.XmlComment;
27 import org.millscript.millscript.datatypes.XmlElement;
28
29 import java.io.IOException;
30
31 /**
32 * This is MillScripts rendering interface. Implementations of this are used to
33 * render objects to the different output formats MillScript provides.
34 */
35 public interface Renderer {
36
37 /**
38 * Appends the specified character, allowing the character to be escaped
39 * as appropriate for this renderer.
40 *
41 * @param ch the character to append, allowing it to be escaped
42 * @throws IOException thrown if an IO problem occurs
43 */
44 void append( final char ch ) throws IOException;
45
46 /**
47 * Appends the specified character sequence, allowing any the sequences
48 * characters to be escaped as appropriate for this renderer.
49 *
50 * @param ch the character sequence to append, allowing its characters
51 * to be escaped
52 * @throws IOException thrown if an IO problem occurs
53 */
54 void append( final CharSequence cs ) throws IOException;
55
56 /**
57 * Appends the escape sequence for the specified character.
58 *
59 * @param ch the character to append an escape sequence for
60 * @throws IOException thrown if an IO problem occurs
61 */
62 void appendEscapeFor( final char ch ) throws IOException;
63
64 /**
65 * Appends the specified character, without using an escape sequence. This
66 * method will raise an alert if the character cannot be appended without
67 * an escape sequence.
68 *
69 * @param ch the character to append, without using an escape sequence.
70 * @throws IOException thrown if an IO problem occurs
71 */
72 void appendNoEscape( final char ch ) throws IOException;
73
74 /**
75 * Appends the specified character sequence, without escaping any
76 * characters in the sequence. This method will raise an alert if any of
77 * the characters cannot be appended without an escape sequence.
78 *
79 * @param ch the character sequence to append, without escaping any of
80 * the characters in the sequence
81 * @throws IOException thrown if an IO problem occurs
82 */
83 void appendNoEscape( final CharSequence cs ) throws IOException;
84
85 /**
86 * Checks if the specified character can be encoded by this renderer.
87 *
88 * @param ch the character to check
89 * @return <code>true</code> if the character can be encoded by this
90 * renderer
91 */
92 boolean canEncode( final char ch );
93
94 /**
95 * Renders the specified object with this renderer.
96 *
97 * @param o the object to render
98 * @throws IOException thrown if an IO problem occurs
99 */
100 void render( final Object o ) throws IOException;
101
102 /**
103 * Renders the specified object to the output file and then closes it. A
104 * document will have a DOCTYPE relevant to the specific type of file being
105 * rendered.
106 *
107 * @param o the object to render to the file
108 */
109 void renderAsDocument( final Object o );
110
111 /**
112 * Renders the specified object to the output file as a fragment of a
113 * complete document. A fragment will not have a DOCTYPE, just the
114 * incomplete fragment of a complete document.
115 *
116 * @param l the list of objects to write to the file
117 */
118 void renderAsFragment( final IList< ? > l );
119
120 /**
121 * Renders the specified CDATA object using this renderer.
122 *
123 * @param c the CDATA object to render
124 * @throws IOException thrown if an IO problem occurs
125 */
126 void renderCDATA( final CDATA c ) throws IOException;
127
128 /**
129 * Renders the required document footer for this renderer.
130 *
131 * @throws IOException thrown if an IO problem occurs
132 */
133 void renderDocumentFooter() throws IOException;
134
135 /**
136 * Renders the required document header for this renderer.
137 *
138 * @throws IOException thrown if an IO problem occurs
139 */
140 void renderDocumentHeader() throws IOException;
141
142 /**
143 * Renders the specified object using this renderer.
144 *
145 * @param o the object to render
146 * @throws IOException thrown if an IO problem occurs
147 */
148 void renderObject( final Object o ) throws IOException;
149
150 /**
151 * Renders the specified XML comment using this renderer.
152 *
153 * @param c the XML comment to render
154 * @throws IOException thrown if an IO problem occurs
155 */
156 void renderXMLComment( final XmlComment c ) throws IOException;
157
158 /**
159 * Renders the specified XML element using this renderer.
160 *
161 * @param e the XML element to render
162 * @throws IOException thrown if an IO problem occurs
163 */
164 void renderXMLElement( final XmlElement e ) throws IOException;
165
166 }