Add a TokenProducer3 which works with a new TokenHandler3 interface

They can handle checked exceptions.

src/main/java/io/sf/carte/uparser/CommentRemovalHandler.java

@@ -11,15 +11,45 @@
 
 package io.sf.carte.uparser;
 
+/**
+ * A handler that removes comments.
+ * <p>
+ * Example:
+ * </p>
+ * 
+ * <pre><code>
+ * String removeComments(String text) {
+ *     String[] opening = { "/{@literal *}", "&lt;!--" };
+ *     String[] closing = { "{@literal *}/", "--&gt;" };
+ *     CommentRemovalHandler handler = new CommentRemovalHandler(text.length());
+ *     TokenProducer tp = new TokenProducer(handler);
+ *     try {
+ *         tp.parseMultiComment(new StringReader(text), opening, closing);
+ *     } catch (IOException e) {
+ *     }
+ *     return handler.getBuffer().toString();
+ * }
+ * </code></pre>
+ */
 public class CommentRemovalHandler implements TokenHandler2 {
 
 	private final StringBuilder buffer;
 
+	/**
+	 * Construct the handler with the given initial buffer size.
+	 * 
+	 * @param bufSize the initial buffer size.
+	 */
 	public CommentRemovalHandler(int bufSize) {
 		super();
 		buffer = new StringBuilder(bufSize);
 	}
 
+	/**
+	 * Get the buffer.
+	 * 
+	 * @return the buffer.
+	 */
 	public StringBuilder getBuffer() {
 		return buffer;
 	}

src/main/java/io/sf/carte/uparser/TokenControl.java

@@ -63,15 +63,15 @@ public interface TokenControl {
 	 * 
 	 * @return the {@code TokenHandler}.
 	 */
-	TokenHandler2 getTokenHandler();
+	TokenHandler3<?> getTokenHandler();
 
 	/**
 	 * Set a new {@code TokenHandler}.
 	 * 
 	 * @param handler
 	 *            the new {@code TokenHandler}.
 	 */
-	void setTokenHandler(TokenHandler2 handler);
+	void setTokenHandler(TokenHandler3<?> handler);
 
 	/**
 	 * Disable the handling of all types of comments.

src/main/java/io/sf/carte/uparser/TokenHandler.java

@@ -15,39 +15,39 @@
  * A {@link TokenHandler2} that is backwards-compatible with
  * {@code TokenProducer} 1.x.
  * <p>
- * You may consider using {@link TokenHandler2} instead.
+ * You may consider using {@link TokenHandler2} or {@link TokenHandler3} instead.
  * </p>
  */
 public interface TokenHandler extends TokenHandler2 {
 
 	@Override
 	default void leftParenthesis(int index) {
-		openGroup(index, TokenProducer.CHAR_LEFT_PAREN);
+		openGroup(index, TokenProducer3.CHAR_LEFT_PAREN);
 	}
 
 	@Override
 	default void leftSquareBracket(int index) {
-		openGroup(index, TokenProducer.CHAR_LEFT_SQ_BRACKET);
+		openGroup(index, TokenProducer3.CHAR_LEFT_SQ_BRACKET);
 	}
 
 	@Override
 	default void leftCurlyBracket(int index) {
-		openGroup(index, TokenProducer.CHAR_LEFT_CURLY_BRACKET);
+		openGroup(index, TokenProducer3.CHAR_LEFT_CURLY_BRACKET);
 	}
 
 	@Override
 	default void rightParenthesis(int index) {
-		closeGroup(index, TokenProducer.CHAR_RIGHT_PAREN);
+		closeGroup(index, TokenProducer3.CHAR_RIGHT_PAREN);
 	}
 
 	@Override
 	default void rightSquareBracket(int index) {
-		closeGroup(index, TokenProducer.CHAR_RIGHT_SQ_BRACKET);
+		closeGroup(index, TokenProducer3.CHAR_RIGHT_SQ_BRACKET);
 	}
 
 	@Override
 	default void rightCurlyBracket(int index) {
-		closeGroup(index, TokenProducer.CHAR_RIGHT_CURLY_BRACKET);
+		closeGroup(index, TokenProducer3.CHAR_RIGHT_CURLY_BRACKET);
 	}
 
 	/**

src/main/java/io/sf/carte/uparser/TokenHandler2.java

@@ -12,10 +12,17 @@
 package io.sf.carte.uparser;
 
 /**
- * To be implemented by listeners that handle the different events generated by
- * the <code>TokenProducer</code>.
+ * A {@link TokenHandler3} that has no checked exceptions, backwards-compatible
+ * with {@code TokenProducer} 2.x.
+ * <p>
+ * Most token handlers will report problems through error handlers and produce
+ * no checked exceptions, in which case you should use this handler together
+ * with {@link TokenProducer}. In other use cases your handler may want to throw
+ * checked exceptions, and then you must use {@link TokenProducer3} together
+ * with {@link TokenHandler3} instead.
+ * </p>
  */
-public interface TokenHandler2 {
+public interface TokenHandler2 extends TokenHandler3<RuntimeException> {
 
 	/**
 	 * At the beginning of parsing, this method is called, passing the {@link TokenControl}
@@ -24,6 +31,7 @@ public interface TokenHandler2 {
 	 * @param control
 	 *            the <code>TokenControl</code> object in charge of parsing.
 	 */
+	@Override
 	void tokenStart(TokenControl control);
 
 	/**
@@ -34,6 +42,7 @@ public interface TokenHandler2 {
 	 * @param word
 	 *            the word.
 	 */
+	@Override
 	void word(int index, CharSequence word);
 
 	/**
@@ -44,6 +53,7 @@ public interface TokenHandler2 {
 	 * @param codePoint
 	 *            the codepoint of the found separator.
 	 */
+	@Override
 	void separator(int index, int codePoint);
 
 	/**
@@ -56,6 +66,7 @@ public interface TokenHandler2 {
 	 * @param quote
 	 *            the quote character.
 	 */
+	@Override
 	void quoted(int index, CharSequence quoted, int quote);
 
 	/**
@@ -68,6 +79,7 @@ public interface TokenHandler2 {
 	 * @param quoteCp
 	 *            the quote character codepoint.
 	 */
+	@Override
 	void quotedWithControl(int index, CharSequence quoted, int quoteCp);
 
 	/**
@@ -78,6 +90,7 @@ public interface TokenHandler2 {
 	 * @param codePoint
 	 *            the FF/LF/CR codepoint.
 	 */
+	@Override
 	void quotedNewlineChar(int index, int codePoint);
 
 	/**
@@ -86,6 +99,7 @@ public interface TokenHandler2 {
 	 * @param index
 	 *            the index at which the codepoint was found.
 	 */
+	@Override
 	void leftParenthesis(int index);
 
 	/**
@@ -94,6 +108,7 @@ public interface TokenHandler2 {
 	 * @param index
 	 *            the index at which the codepoint was found.
 	 */
+	@Override
 	void leftSquareBracket(int index);
 
 	/**
@@ -102,6 +117,7 @@ public interface TokenHandler2 {
 	 * @param index
 	 *            the index at which the codepoint was found.
 	 */
+	@Override
 	void leftCurlyBracket(int index);
 
 	/**
@@ -110,6 +126,7 @@ public interface TokenHandler2 {
 	 * @param index
 	 *            the index at which the codepoint was found.
 	 */
+	@Override
 	void rightParenthesis(int index);
 
 	/**
@@ -118,6 +135,7 @@ public interface TokenHandler2 {
 	 * @param index
 	 *            the index at which the codepoint was found.
 	 */
+	@Override
 	void rightSquareBracket(int index);
 
 	/**
@@ -126,6 +144,7 @@ public interface TokenHandler2 {
 	 * @param index
 	 *            the index at which the codepoint was found.
 	 */
+	@Override
 	void rightCurlyBracket(int index);
 
 	/**
@@ -138,6 +157,7 @@ public interface TokenHandler2 {
 	 * @param codePoint
 	 *            the found codepoint.
 	 */
+	@Override
 	default void startPunctuation(int index, int codePoint) {
 		character(index, codePoint);
 	}
@@ -152,6 +172,7 @@ default void startPunctuation(int index, int codePoint) {
 	 * @param codePoint
 	 *            the found codepoint.
 	 */
+	@Override
 	default void endPunctuation(int index, int codePoint) {
 		character(index, codePoint);
 	}
@@ -169,6 +190,7 @@ default void endPunctuation(int index, int codePoint) {
 	 * @param codePoint
 	 *            the codepoint of the found punctuation.
 	 */
+	@Override
 	void character(int index, int codePoint);
 
 	/**
@@ -179,6 +201,7 @@ default void endPunctuation(int index, int codePoint) {
 	 * @param codePoint
 	 *            the escaped codepoint.
 	 */
+	@Override
 	void escaped(int index, int codePoint);
 
 	/**
@@ -189,6 +212,7 @@ default void endPunctuation(int index, int codePoint) {
 	 * @param codePoint
 	 *            the control codepoint.
 	 */
+	@Override
 	void control(int index, int codePoint);
 
 	/**
@@ -201,6 +225,7 @@ default void endPunctuation(int index, int codePoint) {
 	 * @param comment
 	 *            the commented string.
 	 */
+	@Override
 	void commented(int index, int commentType, String comment);
 
 	/**
@@ -209,6 +234,7 @@ default void endPunctuation(int index, int codePoint) {
 	 * @param len
 	 *            the length of the processed stream.
 	 */
+	@Override
 	void endOfStream(int len);
 
 	/**
@@ -225,5 +251,6 @@ default void endPunctuation(int index, int codePoint) {
 	 *            a context sequence. If a string was parsed, it will contain up to 16
 	 *            characters before and after the error.
 	 */
+	@Override
 	void error(int index, byte errCode, CharSequence context);
 }