001: /**
002: * Licensed under the GNU LESSER GENERAL PUBLIC LICENSE, version 2.1, dated February 1999.
003: *
004: * This program is free software; you can redistribute it and/or modify
005: * it under the terms of the latest version of the GNU Lesser General
006: * Public License as published by the Free Software Foundation;
007: *
008: * This program is distributed in the hope that it will be useful,
009: * but WITHOUT ANY WARRANTY; without even the implied warranty of
010: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
011: * GNU Lesser General Public License for more details.
012: *
013: * You should have received a copy of the GNU Lesser General Public License
014: * along with this program (LICENSE.txt); if not, write to the Free Software
015: * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
016: */package org.jamwiki.parser;
017:
018: import org.jamwiki.utils.WikiLogger;
019:
020: /**
021: * Abstract class to be used when implementing new parsers. New parsers
022: * should extend this class and override any methods that need to be
023: * implemented differently.
024: */
025: public abstract class AbstractParser {
026:
027: private static final WikiLogger logger = WikiLogger
028: .getLogger(AbstractParser.class.getName());
029: /** Parser configuration information. */
030: protected ParserInput parserInput = null;
031:
032: /**
033: * The constructor creates a parser instance, initialized with the
034: * specified parser input settings.
035: *
036: * @param parserInput Input configuration settings for this parser
037: * instance.
038: */
039: public AbstractParser(ParserInput parserInput) {
040: this .parserInput = parserInput;
041: }
042:
043: /**
044: * Return a parser-specific value that can be used as the content of a
045: * topic representing a redirect. For the Mediawiki syntax parser the
046: * value returned would be of the form "#REDIRECT [[Topic]]".
047: *
048: * @param topicName The name of the topic to redirect to.
049: * @return A parser-specific value that can be used as the content of a
050: * topic representing a redirect.
051: */
052: public abstract String buildRedirectContent(String topicName);
053:
054: /**
055: * This method parses content, performing all transformations except for
056: * layout changes such as adding paragraph tags. It is suitable to be used
057: * when parsing the contents of a link or performing similar internal
058: * manipulation.
059: *
060: * @param parserOutput A ParserOutput object containing parser
061: * metadata output.
062: * @param raw The raw Wiki syntax to be converted into HTML.
063: * @param mode The parser mode to use when parsing. Mode affects what
064: * type of parsing actions are taken when processing raw text.
065: * @return The parsed content.
066: * @throws Exception Thrown if any error occurs during parsing.
067: */
068: // FIXME - should this have a mode flag???
069: public abstract String parseFragment(ParserOutput parserOutput,
070: String raw, int mode) throws Exception;
071:
072: /**
073: * Returns a HTML representation of the given wiki raw text for online
074: * representation.
075: *
076: * @param parserOutput A ParserOutput object containing parser
077: * metadata output.
078: * @param raw The raw Wiki syntax to be converted into HTML.
079: * @return The parsed content.
080: * @throws Exception Thrown if any error occurs during parsing.
081: */
082: public abstract String parseHTML(ParserOutput parserOutput,
083: String raw) throws Exception;
084:
085: /**
086: * This method provides a way to parse content and set all output
087: * metadata, such as link values used by the search engine.
088: *
089: * @param parserOutput A ParserOutput object containing parser
090: * metadata output.
091: * @param raw The raw Wiki syntax to be converted into HTML.
092: * @throws Exception Thrown if any error occurs during parsing.
093: */
094: public abstract void parseMetadata(ParserOutput parserOutput,
095: String raw) throws Exception;
096:
097: /**
098: * Perform a bare minimum of parsing as required prior to saving a topic
099: * to the database. In general this method will simply parse signature
100: * tags are return.
101: *
102: * @param raw The raw Wiki syntax to be converted into HTML.
103: * @return The parsed content.
104: * @throws Exception Thrown if any error occurs during parsing.
105: */
106: public abstract String parseMinimal(String raw) throws Exception;
107:
108: /**
109: * When making a section edit this function provides the capability to retrieve
110: * all text within a specific heading level. For example, if targetSection is
111: * specified as five, and the sixth heading is an <h2>, then this method
112: * will return the heading tag and all text up to either the next <h2>,
113: * <h1>, or the end of the document, whichever comes first.
114: *
115: * @param parserOutput A ParserOutput object containing parser
116: * metadata output.
117: * @param raw The raw Wiki text that is to be parsed.
118: * @param targetSection The section (counted from zero) that is to be returned.
119: * @return Returns the raw topic content for the target section.
120: * @throws Exception Thrown if any error occurs during parsing.
121: */
122: public abstract String parseSlice(ParserOutput parserOutput,
123: String raw, int targetSection) throws Exception;
124:
125: /**
126: * This method provides the capability for re-integrating a section edit back
127: * into the main topic. The text to be re-integrated is provided along with the
128: * full Wiki text and a targetSection. All of the content of targetSection
129: * is then replaced with the new text.
130: *
131: * @param parserOutput A ParserOutput object containing parser
132: * metadata output.
133: * @param raw The raw Wiki text that is to be parsed.
134: * @param targetSection The section (counted from zero) that is to be returned.
135: * @param replacementText The text to replace the target section text with.
136: * @return The raw topic content including the new replacement text.
137: * @throws Exception Thrown if any error occurs during parsing.
138: */
139: public abstract String parseSplice(ParserOutput parserOutput,
140: String raw, int targetSection, String replacementText)
141: throws Exception;
142: }
|