More jDoc, a new BasicElementProcessor

[gofetch.git] / src / be / nikiroo / gofetch / support / BasicSupport.java

diff --git a/src/be/nikiroo/gofetch/support/BasicSupport.java b/src/be/nikiroo/gofetch/support/BasicSupport.java
index 102023eb051a02b6c13a41e5ddc0d64e98743156..f3348e366f1ceeece3c6bec39ea01f031ffe8c95 100644 (file)
--- a/src/be/nikiroo/gofetch/support/BasicSupport.java
+++ b/src/be/nikiroo/gofetch/support/BasicSupport.java
@@ -23,25 +23,86 @@ public abstract class BasicSupport {
                SLASHDOT, PIPEDOT, LWN, LEMONDE,
        }
 
-       public interface QuoteProcessor {
+       /**
+        * Used to process an element into lines.
+        * 
+        * @author niki
+        */
+       public interface ElementProcessor {
+               /**
+                * Detect if this node is a quote and should be trated as such.
+                * 
+                * @param node
+                *            the node to check
+                * @return TRUE if it is
+                */
                public boolean detectQuote(Node node);
 
+               /**
+                * Process text content (will be called on each text element, allowing
+                * you to modify it if needed).
+                * 
+                * @param text
+                *            the text to process
+                * @return
+                */
                public String processText(String text);
 
+               /**
+                * Ignore this node.
+                * 
+                * @param node
+                *            the node to ignore
+                * @return TRUE if it has to be ignored
+                */
                public boolean ignoreNode(Node node);
 
                /**
-                * Manually process this node if so desired.
+                * Manually process this node (and return the manual processing value)
+                * if so desired.
+                * <p>
+                * If the node is manually processed, it and its children will not be
+                * automatically processed.
                 * 
                 * @param node
                 *            the node to optionally process
                 * 
-                * @return NULL if not processed, a {@link String} (may be empty) if we
-                *         must not process it any further
+                * @return NULL if not processed (will thus be automatically processed
+                *         as usual), a {@link String} (may be empty) if we process it
+                *         manually -- the given {@link String} will be used instead of
+                *         the usual automatic processing if not NULL
                 */
                public String manualProcessing(Node node);
        }
 
+       /**
+        * A default {@link ElementProcessor} (will not detect or process anything
+        * manually).
+        * 
+        * @author niki
+        */
+       public class BasicElementProcessor implements ElementProcessor {
+               @Override
+               public boolean detectQuote(Node node) {
+                       return false;
+               }
+
+               @Override
+               public String processText(String text) {
+                       return text;
+               }
+
+               @Override
+               public boolean ignoreNode(Node node) {
+                       return false;
+               }
+
+               @Override
+               public String manualProcessing(Node node) {
+                       return null;
+               }
+       }
+
        static private String preselector;
 
        private Type type;
@@ -92,6 +153,15 @@ public abstract class BasicSupport {
                BasicSupport.preselector = preselector;
        }
 
+       /**
+        * Return a {@link BasicSupport} that is compatible with the given
+        * {@link Type} if it exists (or NULL if not).
+        * 
+        * @param type
+        *            the type
+        * 
+        * @return a compatible {@link BasicSupport} if it exists (or NULL if not)
+        */
        static public BasicSupport getSupport(Type type) {
                BasicSupport support = null;
 
@@ -175,8 +245,20 @@ public abstract class BasicSupport {
                return new Element("span");
        }
 
+       /**
+        * Process the given element into text (each line is a text paragraph and
+        * can be prepended with ">" signs to indicate a quote or sub-quote or
+        * sub-sub-quote...).
+        * 
+        * @param element
+        *            the element to process
+        * @param elementProcessor
+        *            the element processor, must not be NULL
+        * 
+        * @return text lines, each line is a paragraph
+        */
        static protected List<String> toLines(Element element,
-                       final QuoteProcessor quoteProcessor) {
+                       final ElementProcessor elementProcessor) {
                final List<String> lines = new ArrayList<String>();
                final StringBuilder currentLine = new StringBuilder();
                final List<Integer> quoted = new ArrayList<Integer>();
@@ -187,10 +269,10 @@ public abstract class BasicSupport {
                                @Override
                                public void head(Node node, int depth) {
                                        String manual = null;
-                                       boolean ignore = quoteProcessor.ignoreNode(node)
+                                       boolean ignore = elementProcessor.ignoreNode(node)
                                                        || ignoredNodes.contains(node.parentNode());
                                        if (!ignore) {
-                                               manual = quoteProcessor.manualProcessing(node);
+                                               manual = elementProcessor.manualProcessing(node);
                                                if (manual != null) {
                                                        currentLine.append(manual);
                                                        ignore = true;
@@ -208,7 +290,7 @@ public abstract class BasicSupport {
                                        }
                                        prep += " ";
 
-                                       boolean enterQuote = quoteProcessor.detectQuote(node);
+                                       boolean enterQuote = elementProcessor.detectQuote(node);
                                        boolean leaveQuote = quoted.contains(depth);
 
                                        if (enterQuote) {
@@ -243,7 +325,7 @@ public abstract class BasicSupport {
                                                String line = StringUtil.normaliseWhitespace(textNode
                                                                .getWholeText());
 
-                                               currentLine.append(quoteProcessor.processText(line));
+                                               currentLine.append(elementProcessor.processText(line));
                                                currentLine.append(" ");
                                        }
                                }