001package org.apache.maven.doxia.parser; 002 003/* 004 * Licensed to the Apache Software Foundation (ASF) under one 005 * or more contributor license agreements. See the NOTICE file 006 * distributed with this work for additional information 007 * regarding copyright ownership. The ASF licenses this file 008 * to you under the Apache License, Version 2.0 (the 009 * "License"); you may not use this file except in compliance 010 * with the License. You may obtain a copy of the License at 011 * 012 * http://www.apache.org/licenses/LICENSE-2.0 013 * 014 * Unless required by applicable law or agreed to in writing, 015 * software distributed under the License is distributed on an 016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 017 * KIND, either express or implied. See the License for the 018 * specific language governing permissions and limitations 019 * under the License. 020 */ 021 022import org.apache.maven.doxia.logging.LogEnabled; 023import org.apache.maven.doxia.sink.Sink; 024 025import java.io.Reader; 026 027/** 028 * A Parser is responsible for parsing any document in a supported front-end 029 * format, and emitting the standard Doxia events, which can then be consumed 030 * by any Doxia Sink. 031 * 032 * @author <a href="mailto:jason@maven.org">Jason van Zyl</a> 033 * @version $Id$ 034 * @since 1.0 035 */ 036public interface Parser 037 extends LogEnabled 038{ 039 /** The Plexus lookup role. */ 040 String ROLE = Parser.class.getName(); 041 042 /** Unknown parser type */ 043 int UNKNOWN_TYPE = 0; 044 045 /** Text parser type */ 046 int TXT_TYPE = 1; 047 048 /** XML parser type */ 049 int XML_TYPE = 2; 050 051 /** 052 * Parses the given source model and emits Doxia events into the given sink. 053 * 054 * @param source not null reader that provides the source document. 055 * You could use <code>newReader</code> methods from {@link org.codehaus.plexus.util.ReaderFactory}. 056 * @param sink A sink that consumes the Doxia events. 057 * @throws org.apache.maven.doxia.parser.ParseException if the model could not be parsed. 058 */ 059 void parse( Reader source, Sink sink ) 060 throws ParseException; 061 062 /** 063 * Parses the given source model and emits Doxia events into the given sink. 064 * 065 * @param source not null reader that provides the source document. 066 * You could use <code>newReader</code> methods from {@link org.codehaus.plexus.util.ReaderFactory}. 067 * @param sink A sink that consumes the Doxia events. 068 * @throws org.apache.maven.doxia.parser.ParseException if the model could not be parsed. 069 */ 070 void parse( Reader source, Sink sink, String reference ) 071 throws ParseException; 072 073 /** 074 * The parser type value could be {@link #UNKNOWN_TYPE}, {@link #TXT_TYPE} or 075 * {@link #XML_TYPE}. 076 * 077 * @return the type of Parser 078 */ 079 int getType(); 080 081 /** 082 * When comments are found in source markup, emit comment Doxia events or just ignore? 083 * 084 * @param emitComments <code>true</code> (default value) to emit comment Doxia events 085 */ 086 void setEmitComments( boolean emitComments ); 087 088 /** 089 * Does the parser emit Doxia comments event when comments found in source? 090 * 091 * @return <code>true</code> (default value) if comment Doxia events are emitted 092 */ 093 boolean isEmitComments(); 094}