1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 package org.apache.maven.doxia.parser; 20 21 import java.io.Reader; 22 23 import org.apache.maven.doxia.index.IndexingSink; 24 import org.apache.maven.doxia.sink.Sink; 25 import org.apache.maven.doxia.sink.impl.SinkWrapperFactory; 26 27 /** 28 * A Parser is responsible for parsing any document in a supported front-end 29 * format, and emitting the standard Doxia events, which can then be consumed 30 * by any Doxia Sink. 31 * 32 * @author <a href="mailto:jason@maven.org">Jason van Zyl</a> 33 * @since 1.0 34 */ 35 public interface Parser { 36 37 /** Unknown parser type */ 38 int UNKNOWN_TYPE = 0; 39 40 /** Text parser type */ 41 int TXT_TYPE = 1; 42 43 /** XML parser type */ 44 int XML_TYPE = 2; 45 46 /** 47 * Parses the given source model and emits Doxia events into the given sink. 48 * Shortcut for {@link #parse(Reader, Sink, String)} with last argument being {@code null}. 49 * 50 * @param source not null reader that provides the source document. 51 * You could use <code>newReader</code> methods from {@link org.codehaus.plexus.util.ReaderFactory}. 52 * @param sink A sink that consumes the Doxia events. 53 * @throws org.apache.maven.doxia.parser.ParseException if the model could not be parsed. 54 * 55 */ 56 void parse(Reader source, Sink sink) throws ParseException; 57 58 /** 59 * Parses the given source model and emits Doxia events into the given sink. 60 * 61 * @param source not null reader that provides the source document. 62 * You could use <code>newReader</code> methods from {@link org.codehaus.plexus.util.ReaderFactory}. 63 * @param sink A sink that consumes the Doxia events. 64 * @param reference a string identifying the source (for file based documents the source file path) 65 * @throws org.apache.maven.doxia.parser.ParseException if the model could not be parsed. 66 */ 67 void parse(Reader source, Sink sink, String reference) throws ParseException; 68 69 /** 70 * The parser type value could be {@link #UNKNOWN_TYPE}, {@link #TXT_TYPE} or 71 * {@link #XML_TYPE}. 72 * 73 * @return the type of Parser 74 */ 75 int getType(); 76 77 /** 78 * When comments are found in source markup, emit comment Doxia events or just ignore? 79 * 80 * @param emitComments <code>true</code> (default value) to emit comment Doxia events 81 */ 82 void setEmitComments(boolean emitComments); 83 84 /** 85 * Does the parser emit Doxia comments event when comments found in source? 86 * 87 * @return <code>true</code> (default value) if comment Doxia events are emitted 88 */ 89 boolean isEmitComments(); 90 91 /** 92 * Registers a given {@link SinkWrapperFactory} with the parser used in subsequent calls of {@code parse(...)} 93 * @param factory the factory to create the sink wrapper 94 * @since 2.0.0 95 */ 96 void addSinkWrapperFactory(SinkWrapperFactory factory); 97 98 /** 99 * Determines whether to automatically generate anchors for each index entry found by {@link IndexingSink} or not. 100 * By default no anchors are generated. 101 * 102 * @param emitAnchors {@code true} to emit anchors otherwise {@code false} (the default) 103 * @since 2.0.0 104 */ 105 void setEmitAnchorsForIndexableEntries(boolean emitAnchors); 106 107 /** 108 * Returns whether anchors are automatically generated for each index entry found by {@link IndexingSink} or not. 109 * @return {@code true} if anchors are emitted otherwise {@code false} 110 * @since 2.0.0 111 */ 112 boolean isEmitAnchorsForIndexableEntries(); 113 }