    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 responsibilities patterns) 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}