001/*
002 * Portions of this software was developed by employees of the National Institute
003 * of Standards and Technology (NIST), an agency of the Federal Government and is
004 * being made available as a public service. Pursuant to title 17 United States
005 * Code Section 105, works of NIST employees are not subject to copyright
006 * protection in the United States. This software may be subject to foreign
007 * copyright. Permission in the United States and in foreign countries, to the
008 * extent that NIST may hold copyright, to use, copy, modify, create derivative
009 * works, and distribute this software and its documentation without fee is hereby
010 * granted on a non-exclusive basis, provided that this notice and disclaimer
011 * of warranty appears in all copies.
012 *
013 * THE SOFTWARE IS PROVIDED 'AS IS' WITHOUT ANY WARRANTY OF ANY KIND, EITHER
014 * EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY
015 * THAT THE SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY IMPLIED WARRANTIES OF
016 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND FREEDOM FROM
017 * INFRINGEMENT, AND ANY WARRANTY THAT THE DOCUMENTATION WILL CONFORM TO THE
018 * SOFTWARE, OR ANY WARRANTY THAT THE SOFTWARE WILL BE ERROR FREE.  IN NO EVENT
019 * SHALL NIST BE LIABLE FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT,
020 * INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES, ARISING OUT OF, RESULTING FROM,
021 * OR IN ANY WAY CONNECTED WITH THIS SOFTWARE, WHETHER OR NOT BASED UPON WARRANTY,
022 * CONTRACT, TORT, OR OTHERWISE, WHETHER OR NOT INJURY WAS SUSTAINED BY PERSONS OR
023 * PROPERTY OR OTHERWISE, AND WHETHER OR NOT LOSS WAS SUSTAINED FROM, OR AROSE OUT
024 * OF THE RESULTS OF, OR USE OF, THE SOFTWARE OR SERVICES PROVIDED HEREUNDER.
025 */
026
027package gov.nist.secauto.metaschema.core.datatype.markup.flexmark;
028
029import com.vladsch.flexmark.ast.AutoLink;
030import com.vladsch.flexmark.ast.BlockQuote;
031import com.vladsch.flexmark.ast.Code;
032import com.vladsch.flexmark.ast.CodeBlock;
033import com.vladsch.flexmark.ast.FencedCodeBlock;
034import com.vladsch.flexmark.ast.HardLineBreak;
035import com.vladsch.flexmark.ast.Heading;
036import com.vladsch.flexmark.ast.HtmlBlock;
037import com.vladsch.flexmark.ast.HtmlCommentBlock;
038import com.vladsch.flexmark.ast.HtmlEntity;
039import com.vladsch.flexmark.ast.HtmlInline;
040import com.vladsch.flexmark.ast.Image;
041import com.vladsch.flexmark.ast.IndentedCodeBlock;
042import com.vladsch.flexmark.ast.Link;
043import com.vladsch.flexmark.ast.ListBlock;
044import com.vladsch.flexmark.ast.ListItem;
045import com.vladsch.flexmark.ast.MailLink;
046import com.vladsch.flexmark.ast.Paragraph;
047import com.vladsch.flexmark.ast.Text;
048import com.vladsch.flexmark.ast.TextBase;
049import com.vladsch.flexmark.ast.ThematicBreak;
050import com.vladsch.flexmark.ext.escaped.character.EscapedCharacter;
051import com.vladsch.flexmark.ext.tables.TableBlock;
052import com.vladsch.flexmark.ext.typographic.TypographicQuotes;
053import com.vladsch.flexmark.ext.typographic.TypographicSmarts;
054import com.vladsch.flexmark.util.ast.Node;
055
056import gov.nist.secauto.metaschema.core.datatype.markup.flexmark.InsertAnchorExtension.InsertAnchorNode;
057import gov.nist.secauto.metaschema.core.util.CollectionUtil;
058
059import java.util.Map;
060
061import javax.xml.namespace.QName;
062
063import edu.umd.cs.findbugs.annotations.NonNull;
064import edu.umd.cs.findbugs.annotations.Nullable;
065import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
066
067@SuppressFBWarnings(value = "THROWS_METHOD_THROWS_CLAUSE_THROWABLE",
068    justification = "There is a need to support varying exceptions from multiple stream writers")
069public interface IMarkupWriter<T, E extends Throwable> { // NOPMD
070  @NonNull
071  QName asQName(@NonNull String localName);
072
073  default void writeElement(
074      @NonNull String localName,
075      @NonNull Node node,
076      @Nullable ChildHandler<T, E> childHandler) throws E {
077    writeElement(localName, node, CollectionUtil.emptyMap(), childHandler);
078  }
079
080  default void writeElement(
081      @NonNull String localName,
082      @NonNull Node node,
083      @NonNull Map<String, String> attributes,
084      @Nullable ChildHandler<T, E> childHandler) throws E {
085    QName qname = asQName(localName);
086    writeElement(qname, node, attributes, childHandler);
087  }
088
089  void writeElement(
090      @NonNull QName qname,
091      @NonNull Node node,
092      @NonNull Map<String, String> attributes,
093      @Nullable ChildHandler<T, E> childHandler) throws E;
094
095  default void writeEmptyElement(
096      @NonNull String localName,
097      @NonNull Map<String, String> attributes) throws E {
098    QName qname = asQName(localName);
099    writeEmptyElement(qname, attributes);
100  }
101
102  void writeEmptyElement(
103      @NonNull QName qname,
104      @NonNull Map<String, String> attributes) throws E;
105
106  default void writeElementStart(
107      @NonNull QName qname) throws E {
108    writeElementStart(qname, CollectionUtil.emptyMap());
109  }
110
111  void writeElementStart(
112      @NonNull QName qname,
113      @NonNull Map<String, String> attributes) throws E;
114
115  void writeElementEnd(@NonNull QName qname) throws E;
116
117  void writeText(@NonNull Text node) throws E;
118
119  /**
120   * Handle a combination of {@link Text} and {@link EscapedCharacter} node
121   * children.
122   *
123   * @param node
124   *          the text node to write
125   * @throws E
126   *           if an error occured while writing
127   */
128  void writeText(@NonNull TextBase node) throws E;
129
130  void writeText(@NonNull CharSequence text) throws E;
131
132  void writeHtmlEntity(@NonNull HtmlEntity node) throws E;
133
134  void writeHtmlEntity(@NonNull TypographicSmarts node) throws E;
135
136  void writeParagraph(
137      @NonNull Paragraph node,
138      @NonNull ChildHandler<T, E> childHandler) throws E;
139
140  void writeLink(
141      @NonNull Link node,
142      @NonNull ChildHandler<T, E> childHandler) throws E;
143
144  void writeLink(@NonNull MailLink node) throws E;
145
146  void writeLink(@NonNull AutoLink node) throws E;
147
148  void writeTypographicQuotes(
149      @NonNull TypographicQuotes node,
150      @NonNull ChildHandler<T, E> childHandler) throws E;
151
152  void writeInlineHtml(@NonNull HtmlInline node) throws E;
153
154  void writeBlockHtml(@NonNull HtmlBlock node) throws E;
155
156  void writeTable(
157      @NonNull TableBlock node,
158      @NonNull ChildHandler<T, E> cellChilddHandler) throws E;
159
160  void writeImage(@NonNull Image node) throws E;
161
162  void writeInsertAnchor(@NonNull InsertAnchorNode node) throws E;
163
164  void writeHeading(
165      @NonNull Heading node,
166      @NonNull ChildHandler<T, E> childHandler) throws E;
167
168  void writeCode(
169      @NonNull Code node,
170      @NonNull ChildHandler<T, E> childHandler) throws E;
171
172  void writeCodeBlock(
173      @NonNull IndentedCodeBlock node,
174      @NonNull ChildHandler<T, E> childHandler) throws E;
175
176  void writeCodeBlock(
177      @NonNull FencedCodeBlock node,
178      @NonNull ChildHandler<T, E> childHandler) throws E;
179
180  void writeCodeBlock(
181      @NonNull CodeBlock node,
182      @NonNull ChildHandler<T, E> childHandler) throws E;
183
184  void writeBlockQuote(
185      @NonNull BlockQuote node,
186      @NonNull ChildHandler<T, E> childHandler) throws E;
187
188  default void writeList(
189      @NonNull String localName,
190      @NonNull ListBlock node,
191      @NonNull ChildHandler<T, E> listItemHandler) throws E {
192    QName qname = asQName(localName);
193    writeList(qname, node, listItemHandler);
194  }
195
196  void writeList(
197      @NonNull QName qname,
198      @NonNull ListBlock node,
199      @NonNull ChildHandler<T, E> listItemHandler) throws E;
200
201  void writeListItem(
202      @NonNull ListItem node,
203      @NonNull ChildHandler<T, E> listItemHandler) throws E;
204
205  void writeBreak(@NonNull HardLineBreak node) throws E;
206
207  void writeBreak(@NonNull ThematicBreak node) throws E;
208
209  void writeComment(@NonNull HtmlCommentBlock node) throws E;
210
211  /**
212   * Provides a callback to handle node children.
213   *
214   * @param <T>
215   *          the type of stream to write to
216   * @param <E>
217   *          the type of exception that can be thrown when a writing error occurs
218   */
219  @FunctionalInterface
220  interface ChildHandler<T, E extends Throwable> { // NOPMD
221    void accept(@NonNull Node node, @NonNull IMarkupWriter<T, E> writer) throws E;
222  }
223
224}