diff options
| -rw-r--r-- | src/main/java/org/anarres/cpp/LexerSource.java | 21 | ||||
| -rw-r--r-- | src/main/java/org/anarres/cpp/Preprocessor.java | 41 | ||||
| -rw-r--r-- | src/main/java/org/anarres/cpp/SourceIterator.java | 2 | ||||
| -rw-r--r-- | src/main/java/org/anarres/cpp/Token.java | 27 |
4 files changed, 78 insertions, 13 deletions
diff --git a/src/main/java/org/anarres/cpp/LexerSource.java b/src/main/java/org/anarres/cpp/LexerSource.java index 82d76b6..931f4a7 100644 --- a/src/main/java/org/anarres/cpp/LexerSource.java +++ b/src/main/java/org/anarres/cpp/LexerSource.java @@ -68,11 +68,25 @@ public class LexerSource extends Source { this.reader.init(pp, this); } + /** + * Returns the line number of the last read character in this source. + * + * Lines are numbered from 1. + * + * @return the line number of the last read character in this source. + */ @Override public int getLine() { return line; } + /** + * Returns the column number of the last read character in this source. + * + * Columns are numbered from 0. + * + * @return the column number of the last read character in this source. + */ @Override public int getColumn() { return column; @@ -513,8 +527,7 @@ public class LexerSource extends Source { flags |= NumericValue.F_DOUBLE; text.append((char) d); d = read(); - } - else if (Character.isUnicodeIdentifierPart(d)) { + } else if (Character.isUnicodeIdentifierPart(d)) { String reason = "Invalid suffix \"" + (char) d + "\" on numeric constant"; // We've encountered something initially identified as a number. // Read in the rest of this token as an identifer but return it as an invalid. @@ -628,9 +641,9 @@ public class LexerSource extends Source { /** * Section 6.4.4.1 of C99 - * + * * (Not pasted here, but says that the initial negation is a separate token.) - * + * * Section 6.4.4.2 of C99 * * A floating constant has a significand part that may be followed diff --git a/src/main/java/org/anarres/cpp/Preprocessor.java b/src/main/java/org/anarres/cpp/Preprocessor.java index 27f609f..a790813 100644 --- a/src/main/java/org/anarres/cpp/Preprocessor.java +++ b/src/main/java/org/anarres/cpp/Preprocessor.java @@ -351,6 +351,8 @@ public class Preprocessor implements Closeable { * * The given {@link Macro} object encapsulates both the name * and the expansion. + * + * @throws LexerException if the definition fails or is otherwise illegal. */ public void addMacro(@Nonnull Macro m) throws LexerException { // System.out.println("Macro " + m); @@ -366,6 +368,8 @@ public class Preprocessor implements Closeable { * * The String value is lexed into a token stream, which is * used as the macro expansion. + * + * @throws LexerException if the definition fails or is otherwise illegal. */ public void addMacro(@Nonnull String name, @Nonnull String value) throws LexerException { @@ -389,6 +393,8 @@ public class Preprocessor implements Closeable { * * This is a convnience method, and is equivalent to * <code>addMacro(name, "1")</code>. + * + * @throws LexerException if the definition fails or is otherwise illegal. */ public void addMacro(@Nonnull String name) throws LexerException { @@ -453,6 +459,8 @@ public class Preprocessor implements Closeable { /** * Returns the Map of Macros parsed during the run of this * Preprocessor. + * + * @return The {@link Map} of macros currently defined. */ @Nonnull public Map<String, Macro> getMacros() { @@ -464,9 +472,11 @@ public class Preprocessor implements Closeable { * * While you can modify the returned object, unexpected things * might happen if you do. + * + * @return the Macro object, or null if not found. */ @CheckForNull - public Macro getMacro(String name) { + public Macro getMacro(@Nonnull String name) { return macros.get(name); } @@ -510,6 +520,8 @@ public class Preprocessor implements Closeable { * @see Source * @see #push_source(Source,boolean) * @see #pop_source() + * + * @return the top Source on the input stack. */ // @CheckForNull protected Source getSource() { @@ -519,6 +531,8 @@ public class Preprocessor implements Closeable { /** * Pushes a Source onto the input stack. * + * @param source the new Source to push onto the top of the input stack. + * @param autopop if true, the Source is automatically removed from the input stack at EOF. * @see #getSource() * @see #pop_source() */ @@ -538,6 +552,9 @@ public class Preprocessor implements Closeable { * * @see #getSource() * @see #push_source(Source,boolean) + * + * @param linemarker TODO: currently ignored, might be a bug? + * @throws IOException if an I/O error occurs. */ @CheckForNull protected Token pop_source(boolean linemarker) @@ -1114,10 +1131,13 @@ public class Preprocessor implements Closeable { * * User code may override this method to implement a virtual * file system. + * + * @param file The VirtualFile to attempt to include. + * @return true if the file was successfully included, false otherwise. + * @throws IOException if an I/O error occurs. */ protected boolean include(@Nonnull VirtualFile file) - throws IOException, - LexerException { + throws IOException { // System.out.println("Try to include " + ((File)file).getAbsolutePath()); if (!file.isFile()) return false; @@ -1129,11 +1149,15 @@ public class Preprocessor implements Closeable { } /** - * Includes a file from an include path, by name. + * Attempts to include a file from an include path, by name. + * + * @param path The list of virtual directories to search for the given name. + * @param name The name of the file to attempt to include. + * @return true if the file was successfully included, false otherwise. + * @throws IOException if an I/O error occurs. */ protected boolean include(@Nonnull Iterable<String> path, @Nonnull String name) - throws IOException, - LexerException { + throws IOException { for (String dir : path) { VirtualFile file = getFileSystem().getFile(dir, name); if (include(file)) @@ -1144,6 +1168,9 @@ public class Preprocessor implements Closeable { /** * Handles an include directive. + * + * @throws IOException if an I/O error occurs. + * @throws LexerException if the include fails, and the error handler is fatal. */ private void include( @CheckForNull String parent, int line, @@ -2093,6 +2120,8 @@ public class Preprocessor implements Closeable { * Returns the next preprocessor token. * * @see Token + * @return The next fully preprocessed token. + * @throws IOException if an I/O error occurs. * @throws LexerException if a preprocessing error occurs. * @throws InternalException if an unexpected error condition arises. */ diff --git a/src/main/java/org/anarres/cpp/SourceIterator.java b/src/main/java/org/anarres/cpp/SourceIterator.java index 82e36d9..240b3b3 100644 --- a/src/main/java/org/anarres/cpp/SourceIterator.java +++ b/src/main/java/org/anarres/cpp/SourceIterator.java @@ -79,7 +79,7 @@ public class SourceIterator implements Iterator<Token> { /** * Not supported. * - * @throws UnsupportedOperationException. + * @throws UnsupportedOperationException unconditionally. */ public void remove() { throw new UnsupportedOperationException(); diff --git a/src/main/java/org/anarres/cpp/Token.java b/src/main/java/org/anarres/cpp/Token.java index 3e6eb3e..b80c1ae 100644 --- a/src/main/java/org/anarres/cpp/Token.java +++ b/src/main/java/org/anarres/cpp/Token.java @@ -16,6 +16,9 @@ */ package org.anarres.cpp; +import javax.annotation.CheckForNull; +import javax.annotation.Nonnull; + /** * A Preprocessor token. * @@ -57,6 +60,9 @@ public final class Token { /** * Returns the semantic type of this token. + * + * @return the semantic type of this token. + * @see #getTokenName(int) */ public int getType() { return type; @@ -70,8 +76,12 @@ public final class Token { /** * Returns the line at which this token started. * - * Lines are numbered from zero. + * Lines are numbered from 1. + * + * @return the line at which this token started. + * @see LexerSource#getLine() */ + // Not @Nonnegative - might not have been assigned? public int getLine() { return line; } @@ -79,8 +89,12 @@ public final class Token { /** * Returns the column at which this token started. * - * Columns are numbered from zero. + * Columns are numbered from 0. + * + * @return the column at which this token started. + * @see LexerSource#getColumn() */ + // Not @Nonnegative - might not have been assigned? public int getColumn() { return column; } @@ -90,8 +104,10 @@ public final class Token { * * This is distinct from the semantic value of the token. * + * @return the original or generated text of this token. * @see #getValue() */ + // Not @Nonnull - might not have been assigned? public String getText() { return text; } @@ -103,8 +119,10 @@ public final class Token { * For integers, this is an Integer object. * For other token types, as appropriate. * + * @return the semantic value of this token, or null. * @see #getText() */ + @CheckForNull public Object getValue() { return value; } @@ -138,7 +156,12 @@ public final class Token { * Returns the descriptive name of the given token type. * * This is mostly used for stringification and debugging. + * + * @param type The type constant from this class to name. + * @return the descriptive name of the given token type. + * @see Token#getType() */ + @Nonnull public static String getTokenName(int type) { return TokenType.getTokenName(type); } |