001/*
002 * JDrupes MDoclet
003 * Copyright (C) 2017, 2021  Michael N. Lipp
004 * 
005 * This program is free software; you can redistribute it and/or modify it 
006 * under the terms of the GNU Affero General Public License as published by 
007 * the Free Software Foundation; either version 3 of the License, or 
008 * (at your option) any later version.
009 *
010 * This program is distributed in the hope that it will be useful, but 
011 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
012 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License 
013 * for more details.
014 *
015 * You should have received a copy of the GNU Affero General Public License along 
016 * with this program; if not, see <http://www.gnu.org/licenses/>.
017 */
018
019package org.jdrupes.mdoclet;
020
021import javax.tools.OptionChecker;
022
023/**
024 * Provides the interface to the Markdown processor.
025 */
026public interface MarkdownProcessor extends OptionChecker {
027
028    final String INTERNAL_OPT_DISABLE_AUTO_HIGHLIGHT
029        = "_disable-auto-highlight_";
030
031    /**
032     * Starts the processor with the given options.
033     * 
034     * All processors should support the special option `_disable-auto-highlight_`.
035     * The doclet maps its option `-disable-auto-highlight` to this special
036     * processor option because disabling the auto highlight feature is usually
037     * implemented by configuring the processors HTML renderer in some way.
038     *  
039     * @param options an array of options
040     */
041    void start(String[] options);
042
043    /**
044     * Converts the given markdown text to HTML.
045     * 
046     * @param markdown the markdown text
047     * @return the HTML
048     */
049    String toHtml(String markdown);
050
051    /**
052     * Converts the given markdown snippet to HTML. If the text does
053     * not start with an HTML tag, the markdown processor will most
054     * likely surround it with an additional block tag such as a
055     * paragraph tag. This method should return a result where any
056     * additional tag is removed. 
057     * 
058     * @param markdown the markdown text
059     * @return the HTML
060     * @since 2.0
061     */
062    String toHtmlFragment(String markdown);
063
064}