1 package org.apache.maven.doxia.parser; 2 3 /* 4 * Licensed to the Apache Software Foundation (ASF) under one 5 * or more contributor license agreements. See the NOTICE file 6 * distributed with this work for additional information 7 * regarding copyright ownership. The ASF licenses this file 8 * to you under the Apache License, Version 2.0 (the 9 * "License"); you may not use this file except in compliance 10 * with the License. You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, 15 * software distributed under the License is distributed on an 16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17 * KIND, either express or implied. See the License for the 18 * specific language governing permissions and limitations 19 * under the License. 20 */ 21 22 import org.apache.maven.doxia.logging.LogEnabled; 23 import org.apache.maven.doxia.sink.Sink; 24 25 import java.io.Reader; 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 * @version $Id$ 34 * @since 1.0 35 */ 36 public interface Parser 37 extends LogEnabled 38 { 39 /** The Plexus lookup role. */ 40 String ROLE = Parser.class.getName(); 41 42 /** Unknown parser type */ 43 int UNKNOWN_TYPE = 0; 44 45 /** Text parser type */ 46 int TXT_TYPE = 1; 47 48 /** XML parser type */ 49 int XML_TYPE = 2; 50 51 /** 52 * Parses the given source model and emits Doxia events into the given sink. 53 * 54 * @param source not null reader that provides the source document. 55 * You could use <code>newReader</code> methods from {@link org.codehaus.plexus.util.ReaderFactory}. 56 * @param sink A sink that consumes the Doxia events. 57 * @throws org.apache.maven.doxia.parser.ParseException if the model could not be parsed. 58 */ 59 void parse( Reader source, Sink sink ) 60 throws ParseException; 61 62 /** 63 * Parses the given source model and emits Doxia events into the given sink. 64 * 65 * @param source not null reader that provides the source document. 66 * You could use <code>newReader</code> methods from {@link org.codehaus.plexus.util.ReaderFactory}. 67 * @param sink A sink that consumes the Doxia events. 68 * @throws org.apache.maven.doxia.parser.ParseException if the model could not be parsed. 69 */ 70 void parse( Reader source, Sink sink, String reference ) 71 throws ParseException; 72 73 /** 74 * The parser type value could be {@link #UNKNOWN_TYPE}, {@link #TXT_TYPE} or 75 * {@link #XML_TYPE}. 76 * 77 * @return the type of Parser 78 */ 79 int getType(); 80 81 /** 82 * When comments are found in source markup, emit comment Doxia events or just ignore? 83 * 84 * @param emitComments <code>true</code> (default value) to emit comment Doxia events 85 */ 86 void setEmitComments( boolean emitComments ); 87 88 /** 89 * Does the parser emit Doxia comments event when comments found in source? 90 * 91 * @return <code>true</code> (default value) if comment Doxia events are emitted 92 */ 93 boolean isEmitComments(); 94 }