001/*
002    Licensed to the Apache Software Foundation (ASF) under one
003    or more contributor license agreements.  See the NOTICE file
004    distributed with this work for additional information
005    regarding copyright ownership.  The ASF licenses this file
006    to you under the Apache License, Version 2.0 (the
007    "License"); you may not use this file except in compliance
008    with the License.  You may obtain a copy of the License at
009
010       http://www.apache.org/licenses/LICENSE-2.0
011
012    Unless required by applicable law or agreed to in writing,
013    software distributed under the License is distributed on an
014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015    KIND, either express or implied.  See the License for the
016    specific language governing permissions and limitations
017    under the License.
018*/
019package org.apache.wiki.htmltowiki;
020
021import org.jdom2.Element;
022import org.jdom2.JDOMException;
023import org.jdom2.Text;
024
025import java.io.PrintWriter;
026import java.util.Deque;
027import java.util.Map;
028
029
030/**
031 * Decorates Xhtml elements with wiki syntax
032 */
033public interface SyntaxDecorator {
034
035    /**
036     * Prepares the syntax decorator.
037     * 
038     * @param out writer that will hold the resulting wiki markup.
039     * @param liStack stack containing the amount of nested {@code li}s.
040     * @param preStack stack containing the amount of nested {@code pre}s.
041     * @param outTrimmer writer capable of trimming whitespaces and of checking if it's currently writing a line start.
042     * @param config xhtml to wiki configuration object.
043     * @param chain chain (in the chain of responsabilities pattern) that is expected to be called by the different xhtml decorations.
044     */
045    void init( PrintWriter out, Deque< String > liStack, Deque< String > preStack, WhitespaceTrimWriter outTrimmer, XHtmlToWikiConfig config, XHtmlElementToWikiTranslator chain );
046
047    /**
048     * Decorates an {@code a} element.
049     * 
050     * @param e XHTML element being translated.
051     * @param ref actual link.
052     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
053     */
054    void a( Element e, final String ref ) throws JDOMException;
055
056    /**
057     * Decorates an {@code a} element, pointing to a footnote.
058     *
059     * @param text text link of the footnote.
060     * @param ref link to footnote.
061     */
062    void aFootnote( final String text, final String ref );
063
064    /**
065     * Decorates an {@code a} element to an undefined page.
066     *
067     * @param e XHTML element being translated.
068     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
069     */
070    void aUndefined( Element e ) throws JDOMException;
071
072    /**
073     * Decorates a {@code br} element.
074     *
075     * @param base parent of the XHTML element being translated.
076     * @param e XHTML element being translated.
077     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
078     */
079    void br( Element base, Element e ) throws JDOMException;
080
081    /**
082     * Decorates a {@code code} ot {@code tt} element.
083     *
084     * @param e XHTML element being translated.
085     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
086     */
087    void code( Element e ) throws JDOMException;
088
089    /**
090     * Decorates a {@code dd} element.
091     *
092     * @param e XHTML element being translated.
093     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
094     */
095    void dd( Element e ) throws JDOMException;
096
097    /**
098     * Decorates a {@code dl} element.
099     *
100     * @param e XHTML element being translated.
101     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
102     */
103    void dl( Element e ) throws JDOMException;
104
105    /**
106     * Decorates a {@code dt} element.
107     *
108     * @param e XHTML element being translated.
109     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
110     */
111    void dt( Element e ) throws JDOMException;
112
113    /**
114     * Decorates an {@code em}, {@code i} or {@code address} element.
115     *
116     * @param e XHTML element being translated.
117     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
118     */
119    void em( Element e ) throws JDOMException;
120
121    /**
122     * Decorates a {@code form} element.
123     *
124     * @param e XHTML element being translated.
125     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
126     */
127    void form( Element e ) throws JDOMException;
128
129    /**
130     * Decorates an {@code hr} element.
131     *
132     * @param e XHTML element being translated.
133     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
134     */
135    void hr( Element e ) throws JDOMException;
136
137    /**
138     * Decorates an {@code h1} element.
139     *
140     * @param e XHTML element being translated.
141     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
142     */
143    void h1( Element e ) throws JDOMException;
144
145    /**
146     * Decorates an {@code h2} element.
147     *
148     * @param e XHTML element being translated.
149     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
150     */
151    void h2( Element e ) throws JDOMException;
152
153    /**
154     * Decorates an {@code h3} element.
155     *
156     * @param e XHTML element being translated.
157     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
158     */
159    void h3( Element e ) throws JDOMException;
160
161    /**
162     * Decorates an {@code h4} element.
163     *
164     * @param e XHTML element being translated.
165     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
166     */
167    void h4( Element e ) throws JDOMException;
168
169    /**
170     * Decorates an image element. This is a terminal operation, that is, chain is not expected to be called by this method.
171     *
172     * @param src image source
173     * @param imageAttrs image attributes
174     */
175    void image( String src, Map< String, Object > imageAttrs );
176
177    /**
178     * Decorates an image element. This is a terminal operation, that is, chain is not expected to be called by this method.
179     *
180     * @param e XHTML element being translated.
181     */
182    void img( Element e );
183
184    /**
185     * Decorates an {@code input} element.
186     *
187     * @param e XHTML element being translated.
188     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
189     */
190    void input( Element e ) throws JDOMException;
191
192    /**
193     * Decorates a {@code li} element.
194     *
195     * @param base parent of the XHTML element being translated.
196     * @param e XHTML element being translated.
197     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
198     */
199    void li( Element base, Element e ) throws JDOMException;
200
201    /**
202     * Decorates an {@code ol} element.
203     *
204     * @param e XHTML element being translated.
205     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
206     */
207    void ol( Element e ) throws JDOMException;
208
209    /**
210     * Decorates an {@code option} element.
211     *
212     * @param base parent of the XHTML element being translated.
213     * @param e XHTML element being translated.
214     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
215     */
216    void option( Element base, Element e ) throws JDOMException;
217
218    /**
219     * Decorates a {@code p} element.
220     *
221     * @param e XHTML element being translated.
222     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
223     */
224    void p( Element e ) throws JDOMException;
225
226    /**
227     * Decorates a text paragraph.
228     *
229     * @param dto XHTML element being translated.
230     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
231     */
232    void paragraph( XHtmlElementToWikiTranslator.ElementDecoratorData dto ) throws JDOMException;
233
234    /**
235     * Decorates a {@code pre} element.
236     *
237     * @param e XHTML element being translated.
238     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
239     */
240    void pre( Element e ) throws JDOMException;
241
242    /**
243     * Decorates a {@code strong} or {@code b} element.
244     *
245     * @param e XHTML element being translated.
246     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
247     */
248    void strong( Element e ) throws JDOMException;
249
250    /**
251     * Decorates a {@code table} element.
252     *
253     * @param e XHTML element being translated.
254     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
255     */
256    void table( Element e ) throws JDOMException;
257
258    /**
259     * Decorates a {@code tbody} element.
260     *
261     * @param e XHTML element being translated.
262     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
263     */
264    void tbody( Element e ) throws JDOMException;
265
266    /**
267     * Decorates an {@code td} element.
268     *
269     * @param e XHTML element being translated.
270     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
271     */
272    void td( Element e ) throws JDOMException;
273
274    /**
275     * Decorates a text element. This is a terminal operation, that is, chain is not expected to be called by this method.
276     *
277     * @param e XHTML element being translated.
278     */
279    void text( Text e );
280
281    /**
282     * Decorates a {@code textarea} element.
283     *
284     * @param e XHTML element being translated.
285     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
286     */
287    void textarea( Element e ) throws JDOMException;
288
289    /**
290     * Decorates a {@code th} element.
291     *
292     * @param e XHTML element being translated.
293     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
294     */
295    void th( Element e ) throws JDOMException;
296
297    /**
298     * Decorates a {@code thead} element.
299     *
300     * @param e XHTML element being translated.
301     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
302     */
303    void thead( Element e ) throws JDOMException;
304
305    /**
306     * Decorates a {@code tr} element.
307     *
308     * @param e XHTML element being translated.
309     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
310     */
311    void tr( Element e ) throws JDOMException;
312
313    /**
314     * Decorates a {@code select} element.
315     *
316     * @param e XHTML element being translated.
317     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
318     */
319    void select( Element e ) throws JDOMException;
320
321    /**
322     * Decorates a {@code strike} element.
323     *
324     * @param e XHTML element being translated.
325     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
326     */
327    void strike( Element e ) throws JDOMException;
328
329    /**
330     * Decorates a {@code sub} element.
331     *
332     * @param e XHTML element being translated.
333     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
334     */
335    void sub( Element e ) throws JDOMException;
336
337    /**
338     * Decorates an {@code sup} element.
339     *
340     * @param e XHTML element being translated.
341     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
342     */
343    void sup( Element e ) throws JDOMException;
344
345    /**
346     * Decorates an {@code ul} element.
347     *
348     * @param e XHTML element being translated.
349     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
350     */
351    void ul( Element e ) throws JDOMException;
352
353    /**
354     * Decorates an {@code underline} element.
355     *
356     * @param e XHTML element being translated.
357     * @throws JDOMException if an error has ocurred parsing the xhtml chain.
358     */
359    void underline( Element e ) throws JDOMException;
360
361}