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.maven.doxia.parser;
020
021import java.io.Reader;
022
023import org.apache.maven.doxia.index.IndexingSink;
024import org.apache.maven.doxia.sink.Sink;
025import org.apache.maven.doxia.sink.impl.SinkWrapperFactory;
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 * @since 1.0
034 */
035public interface Parser {
036
037    /** Unknown parser type */
038    int UNKNOWN_TYPE = 0;
039
040    /** Text parser type */
041    int TXT_TYPE = 1;
042
043    /** XML parser type */
044    int XML_TYPE = 2;
045
046    /**
047     * Parses the given source model and emits Doxia events into the given sink.
048     * Shortcut for {@link #parse(Reader, Sink, String)} with last argument being {@code null}.
049     *
050     * @param source not null reader that provides the source document.
051     * You could use <code>newReader</code> methods from {@link org.codehaus.plexus.util.ReaderFactory}.
052     * @param sink A sink that consumes the Doxia events.
053     * @throws org.apache.maven.doxia.parser.ParseException if the model could not be parsed.
054     *
055     */
056    void parse(Reader source, Sink sink) throws ParseException;
057
058    /**
059     * Parses the given source model and emits Doxia events into the given sink.
060     *
061     * @param source not null reader that provides the source document.
062     * You could use <code>newReader</code> methods from {@link org.codehaus.plexus.util.ReaderFactory}.
063     * @param sink A sink that consumes the Doxia events.
064     * @param reference a string identifying the source (for file based documents the source file path)
065     * @throws org.apache.maven.doxia.parser.ParseException if the model could not be parsed.
066     */
067    void parse(Reader source, Sink sink, String reference) throws ParseException;
068
069    /**
070     * The parser type value could be {@link #UNKNOWN_TYPE}, {@link #TXT_TYPE} or
071     * {@link #XML_TYPE}.
072     *
073     * @return the type of Parser
074     */
075    int getType();
076
077    /**
078     * When comments are found in source markup, emit comment Doxia events or just ignore?
079     *
080     * @param emitComments <code>true</code> (default value) to emit comment Doxia events
081     */
082    void setEmitComments(boolean emitComments);
083
084    /**
085     * Does the parser emit Doxia comments event when comments found in source?
086     *
087     * @return <code>true</code> (default value) if comment Doxia events are emitted
088     */
089    boolean isEmitComments();
090
091    /**
092     * Registers a given {@link SinkWrapperFactory} with the parser used in subsequent calls of {@code parse(...)}
093     * @param factory the factory to create the sink wrapper
094     * @since 2.0.0
095     */
096    void addSinkWrapperFactory(SinkWrapperFactory factory);
097
098    /**
099     * 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}