Add extractSpans method so that we can deprecate renderLinks (#21)

With spans, the code for renderLinks can just be written as a normal
loop with an if statement. This makes it possible to render the text
between links in a special way too (e.g. escape it).

Author: robinst

CHANGELOG.md

@@ -6,7 +6,13 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
+### Added
+- Add `extractSpans` method that also returns the text pieces of the
+  input before, between and after links. This makes it more convenient
+  to write code that transforms the whole input text without having to
+  manually keep track of indexes.
 ### Changed
+- Deprecated `Autolink.renderLinks` and `LinkRenderer`, see "added".
 - Stop URLs when encountering an `"`. This is consistent with RFC 3986,
   and it seems unlikely that a user would have an unescaped `"` in a URL
   anyway, as browsers escape it when you copy an URL that contains one.

README.md

@@ -52,26 +52,38 @@ Note that by default all supported types of links are extracted. If
 you're only interested in specific types, narrow it down using the
 `linkTypes` method.
 
-There's also a static method to replace links found in the text. Here's
-an example of using that for wrapping URLs in an `<a>` tag. Note that it
-doesn't handle escaping at all:
+There's another method which is convenient for when you want to transform
+all of the input text to something else. Here's an example of using that
+to transform the text to HTML and wrapping URLs in an `<a>` tag (escaping
+is done using owasp-java-encoder):
 
 ```java
 import org.nibor.autolink.*;
+import org.owasp.encoder.Encode;
 
 String input = "wow http://test.com such linked";
 LinkExtractor linkExtractor = LinkExtractor.builder()
         .linkTypes(EnumSet.of(LinkType.URL)) // limit to URLs
         .build();
-Iterable<LinkSpan> links = linkExtractor.extractLinks(input);
-String result = Autolink.renderLinks(input, links, (link, text, sb) -> {
-    sb.append("<a href=\"");
-    sb.append(text, link.getBeginIndex(), link.getEndIndex());
-    sb.append("\">");
-    sb.append(text, link.getBeginIndex(), link.getEndIndex());
-    sb.append("</a>");
-});
-result;  // "wow <a href=\"http://test.com\">http://test.com</a> such linked"
+Iterable<Span> spans = linkExtractor.extractSpans(input);
+
+StringBuilder sb = new StringBuilder();
+for (Span span : spans) {
+    String text = input.substring(span.getBeginIndex(), span.getEndIndex());
+    if (span instanceof LinkSpan) {
+        // span is a URL
+        sb.append("<a href=\"");
+        sb.append(Encode.forHtmlAttribute(text));
+        sb.append("\">");
+        sb.append(Encode.forHtml(text));
+        sb.append("</a>");
+    } else {
+        // span is plain text before/after link
+        sb.append(Encode.forHtml(text));
+    }
+}
+
+sb.toString();  // "wow <a href=\"http://test.com\">http://test.com</a> such linked"
 ```
 
 Features

src/main/java/org/nibor/autolink/Autolink.java

@@ -13,7 +13,9 @@ public class Autolink {
      * @param links the links to render, see {@link LinkExtractor} to extract them
      * @param linkRenderer the link rendering implementation
      * @return the rendered string
+     * @deprecated use {@link LinkExtractor#extractSpans(CharSequence)} instead
      */
+    @Deprecated
     public static String renderLinks(CharSequence input, Iterable<LinkSpan> links, LinkRenderer linkRenderer) {
         if (input == null) {
             throw new NullPointerException("input must not be null");

src/main/java/org/nibor/autolink/LinkExtractor.java

@@ -1,9 +1,7 @@
 package org.nibor.autolink;
 
-import org.nibor.autolink.internal.EmailScanner;
+import org.nibor.autolink.internal.*;
 import org.nibor.autolink.internal.Scanner;
-import org.nibor.autolink.internal.UrlScanner;
-import org.nibor.autolink.internal.WwwScanner;
 
 import java.util.*;
 
@@ -33,6 +31,7 @@ public static Builder builder() {
      *
      * @param input the input text, must not be null
      * @return a lazy iterable for the links in order that they appear in the input, never null
+     * @see #extractSpans(CharSequence) extractSpans to also get spans for the plain text pieces of the input
      */
     public Iterable<LinkSpan> extractLinks(final CharSequence input) {
         if (input == null) {
@@ -46,6 +45,28 @@ public Iterator<LinkSpan> iterator() {
         };
     }
 
+    /**
+     * Extract spans from the input text. A span is a substring of the input and represents either a link
+     * (see {@link LinkSpan}) or plain text outside a link.
+     * <p>
+     * Using this is more convenient than {@link #extractLinks} if you want to transform the whole input text to
+     * a different format.
+     *
+     * @param input the input text, must not be null
+     * @return a lazy iterable for the spans in order that they appear in the input, never null
+     */
+    public Iterable<Span> extractSpans(final CharSequence input) {
+        if (input == null) {
+            throw new NullPointerException("input must not be null");
+        }
+        return new Iterable<Span>() {
+            @Override
+            public Iterator<Span> iterator() {
+                return new SpanIterator(input, new LinkIterator(input));
+            }
+        };
+    }
+
     private Scanner trigger(char c) {
         switch (c) {
             case ':':
@@ -83,7 +104,7 @@ public Builder linkTypes(Set<LinkType> linkTypes) {
 
         /**
          * @param emailDomainMustHaveDot true if the domain in an email address is required to have more than one part,
-         *                               false if it can also just have single part (e.g. foo@com); true by default
+         * false if it can also just have single part (e.g. foo@com); true by default
          * @return this builder
          */
         public Builder emailDomainMustHaveDot(boolean emailDomainMustHaveDot) {
@@ -160,4 +181,60 @@ private void setNext() {
             }
         }
     }
+
+    private class SpanIterator implements Iterator<Span> {
+
+        private final CharSequence input;
+        private final LinkIterator linkIterator;
+
+        private int index = 0;
+        private LinkSpan nextLink = null;
+
+        public SpanIterator(CharSequence input, LinkIterator linkIterator) {
+            this.input = input;
+            this.linkIterator = linkIterator;
+        }
+
+        @Override
+        public boolean hasNext() {
+            return index < input.length();
+        }
+
+        private Span nextTextSpan(int endIndex) {
+            Span span = new SpanImpl(index, endIndex);
+            index = endIndex;
+            return span;
+        }
+
+        @Override
+        public Span next() {
+            if (!hasNext()) {
+                throw new NoSuchElementException();
+            }
+
+            if (nextLink == null) {
+                if (linkIterator.hasNext()) {
+                    nextLink = linkIterator.next();
+                } else {
+                    return nextTextSpan(input.length());
+                }
+            }
+
+            if (index < nextLink.getBeginIndex()) {
+                // text before link, return plain
+                return nextTextSpan(nextLink.getBeginIndex());
+            } else {
+                // at link, return it and make sure we continue after it next time
+                Span span = nextLink;
+                index = nextLink.getEndIndex();
+                nextLink = null;
+                return span;
+            }
+        }
+
+        @Override
+        public void remove() {
+            throw new UnsupportedOperationException("remove");
+        }
+    }
 }

src/main/java/org/nibor/autolink/LinkRenderer.java

@@ -1,8 +1,11 @@
 package org.nibor.autolink;
 
 /**
- * Renderer for a link.
+ * Renderer for a link
+ *
+ * @deprecated use {@link LinkExtractor#extractSpans(CharSequence)} instead.
  */
+@Deprecated
 public interface LinkRenderer {
 
     /**

src/main/java/org/nibor/autolink/LinkSpan.java

@@ -3,22 +3,11 @@
 /**
  * Information for an extracted link.
  */
-public interface LinkSpan {
+public interface LinkSpan extends Span {
 
     /**
      * @return the type of link
      */
     LinkType getType();
 
-    /**
-     * @return begin index (inclusive) in the original input that this link starts at
-     */
-    int getBeginIndex();
-
-    /**
-     * @return end index (exclusive) in the original input that this link ends at; in other words, index of first
-     * character after link
-     */
-    int getEndIndex();
-
 }

src/main/java/org/nibor/autolink/Span.java

@@ -0,0 +1,19 @@
+package org.nibor.autolink;
+
+/**
+ * A reference to a piece of the input text, either a link (see {@link LinkSpan}) or plain text.
+ */
+public interface Span {
+
+    /**
+     * @return begin index (inclusive) in the original input that this link starts at
+     */
+    int getBeginIndex();
+
+    /**
+     * @return end index (exclusive) in the original input that this link ends at; in other words, index of first
+     * character after link
+     */
+    int getEndIndex();
+
+}

src/main/java/org/nibor/autolink/internal/SpanImpl.java

@@ -0,0 +1,29 @@
+package org.nibor.autolink.internal;
+
+import org.nibor.autolink.Span;
+
+public class SpanImpl implements Span {
+
+    private final int beginIndex;
+    private final int endIndex;
+
+    public SpanImpl(int beginIndex, int endIndex) {
+        this.beginIndex = beginIndex;
+        this.endIndex = endIndex;
+    }
+
+    @Override
+    public int getBeginIndex() {
+        return beginIndex;
+    }
+
+    @Override
+    public int getEndIndex() {
+        return endIndex;
+    }
+
+    @Override
+    public String toString() {
+        return "Span{beginIndex=" + beginIndex + ", endIndex=" + endIndex + "}";
+    }
+}

src/test/java/org/nibor/autolink/AutolinkBenchmark.java

@@ -32,7 +32,7 @@ public static void main(String[] args) throws Exception {
 
     @Benchmark
     public void generatedText() {
-        link(GENERATED_INPUT, "|", null);
+        renderExtractedLinks(GENERATED_INPUT, "|", null);
     }
 
     @Override

src/test/java/org/nibor/autolink/AutolinkTestCase.java

@@ -5,18 +5,25 @@
 public abstract class AutolinkTestCase {
 
     protected void assertLinked(String input, String expected, LinkType expectedLinkType) {
-        String result = link(input, "|", expectedLinkType);
+        String result = renderExtractedLinks(input, "|", expectedLinkType);
         assertEquals(expected, result);
+
+        result = renderExtractedSpans(input, "|", expectedLinkType);
+        assertEquals(expected, result);
+
     }
 
     protected void assertNotLinked(String input) {
-        String result = link(input, "|", null);
+        String result = renderExtractedLinks(input, "|", null);
+        assertEquals(input, result);
+
+        result = renderExtractedSpans(input, "|", null);
         assertEquals(input, result);
     }
 
     protected abstract LinkExtractor getLinkExtractor();
 
-    protected String link(String input, final String marker, final LinkType expectedLinkType) {
+    protected String renderExtractedLinks(String input, final String marker, final LinkType expectedLinkType) {
         Iterable<LinkSpan> links = getLinkExtractor().extractLinks(input);
         return Autolink.renderLinks(input, links, new LinkRenderer() {
             @Override
@@ -31,4 +38,23 @@ public void render(LinkSpan link, CharSequence text, StringBuilder sb) {
         });
     }
 
+    protected String renderExtractedSpans(String input, final String marker, final LinkType expectedLinkType) {
+        Iterable<Span> spans = getLinkExtractor().extractSpans(input);
+        StringBuilder sb = new StringBuilder();
+        for (Span span : spans) {
+            if (span instanceof LinkSpan) {
+                LinkType type = ((LinkSpan) span).getType();
+                if (expectedLinkType != null) {
+                    assertEquals(expectedLinkType, type);
+                }
+                sb.append(marker);
+                sb.append(input, span.getBeginIndex(), span.getEndIndex());
+                sb.append(marker);
+            } else {
+                sb.append(input, span.getBeginIndex(), span.getEndIndex());
+            }
+        }
+        return sb.toString();
+    }
+
 }