Class JSONTokener
- java.lang.Object
-
- com.github.openjson.JSONTokener
-
public class JSONTokener extends java.lang.Object
Parses a JSON (RFC 4627) encoded string into the corresponding object. Most clients of this class will use only need theconstructor
andnextValue()
method. Example usage:String json = "{" + " \"query\": \"Pizza\", " + " \"locations\": [ 94043, 90210 ] " + "}"; JSONObject object = (JSONObject) new JSONTokener(json).nextValue(); String query = object.getString("query"); JSONArray locations = object.getJSONArray("locations");
For the best interoperability and performance use JSON that complies with RFC 4627, such as that generated by
JSONStringer
. For legacy reasons, this parser is lenient, so a successful parse does not indicate that the input string was valid JSON. All of the following syntax errors will be ignored:- End of line comments starting with
//
or#
and ending with a newline character. - C-style comments starting with
/*
and ending with*
/
. Such comments may not be nested. - Strings that are unquoted or
'single quoted'
. - Hexadecimal integers prefixed with
0x
or0X
. - Octal integers prefixed with
0
. - Array elements separated by
;
. - Unnecessary array separators. These are interpreted as if null was the omitted value.
- Key-value pairs separated by
=
or=>
. - Key-value pairs separated by
;
.
Each tokener may be used to parse a single JSON string. Instances of this class are not thread safe. Although this class is non-final, it was not designed for inheritance and should not be subclassed. In particular, self-use by overrideable methods is not specified. See Effective Java Item 17, "Design and Document or inheritance or else prohibit it" for further information.
- End of line comments starting with
-
-
Field Summary
Fields Modifier and Type Field Description private java.lang.String
in
The input JSON.static int
MAX_NESTING_LEVEL
Maximum allowed JSON nesting level supported by the parser.private int
pos
The index of the next character to be returned bynext()
.
-
Constructor Summary
Constructors Constructor Description JSONTokener(java.io.Reader input)
JSONTokener(java.lang.String in)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
back()
Unreads the most recent character of input.static int
dehexchar(char hex)
Returns the integer [0..15] value for the given hex character, or -1 for non-hex input.boolean
more()
Returns true until the input has been exhausted.char
next()
Returns the next available character, or the null character '\0' if all inputs have been exhausted.char
next(char c)
Returns the next available character if it equalsc
.java.lang.String
next(int length)
Returns the nextlength
characters of the input.char
nextClean()
Returns the next character that is not whitespace and does not belong to a comment.private int
nextCleanInternal()
java.lang.String
nextString(char quote)
Returns the string up to but not includingquote
, unescaping any character escape sequences encountered along the way.java.lang.String
nextTo(char excluded)
Equivalent tonextTo(String.valueOf(excluded))
.java.lang.String
nextTo(java.lang.String excluded)
Returns thetrimmed
string holding the characters up to but not including the first of: any character inexcluded
a newline character '\n' a carriage return '\r'private java.lang.String
nextToInternal(java.lang.String excluded)
Returns the string up to but not including any of the given characters or a newline character.java.lang.Object
nextValue()
Returns the next value from the input.private java.lang.Object
nextValue(int nestingLevel)
private JSONArray
readArray(int nestingLevel)
Reads a sequence of values and the trailing closing brace ']' of an array.private char
readEscapeCharacter()
Unescapes the character identified by the character or characters that immediately follow a backslash.private java.lang.Object
readLiteral()
Reads a null, boolean, numeric or unquoted string literal value.private JSONObject
readObject(int nestingLevel)
Reads a sequence of key/value pairs and the trailing closing brace '}' of an object.void
skipPast(java.lang.String thru)
Advances past all input up to and including the next occurrence ofthru
.char
skipTo(char to)
Advances past all inputs up to but not including the next occurrence ofto
.private void
skipToEndOfLine()
Advances the position until after the next newline character.JSONException
syntaxError(java.lang.String message)
Returns an exception containing the given message plus the current position and the entire input string.java.lang.String
toString()
Returns the current position and the entire input string.
-
-
-
Field Detail
-
MAX_NESTING_LEVEL
public static final int MAX_NESTING_LEVEL
Maximum allowed JSON nesting level supported by the parser. Used to avoid StackOverflow errors. For backward compatibility, the value can be changed (globally) using a system property.
-
in
private final java.lang.String in
The input JSON.
-
pos
private int pos
The index of the next character to be returned bynext()
. When the input is exhausted, this equals the input's length.
-
-
Constructor Detail
-
JSONTokener
public JSONTokener(java.lang.String in)
- Parameters:
in
- JSON encoded string. Null is not permitted and will yield a tokener that throwsNullPointerExceptions
when methods are called.
-
JSONTokener
public JSONTokener(java.io.Reader input) throws java.io.IOException
- Throws:
java.io.IOException
-
-
Method Detail
-
nextValue
public java.lang.Object nextValue() throws JSONException
Returns the next value from the input.- Returns:
- a
JSONObject
,JSONArray
, String, Boolean, Integer, Long, Double orJSONObject.NULL
. - Throws:
JSONException
- if the input is malformed.
-
nextValue
private java.lang.Object nextValue(int nestingLevel) throws JSONException
- Throws:
JSONException
-
nextCleanInternal
private int nextCleanInternal() throws JSONException
- Throws:
JSONException
-
skipToEndOfLine
private void skipToEndOfLine()
Advances the position until after the next newline character. If the line is terminated by "\r\n", the '\n' must be consumed as whitespace by the caller.
-
nextString
public java.lang.String nextString(char quote) throws JSONException
Returns the string up to but not includingquote
, unescaping any character escape sequences encountered along the way. The opening quote should have already been read. This consumes the closing quote, but does not include it in the returned string.- Parameters:
quote
- either ' or ".- Returns:
- The unescaped string.
- Throws:
JSONException
- if the string isn't terminated by a closing quote correctly.
-
readEscapeCharacter
private char readEscapeCharacter() throws JSONException
Unescapes the character identified by the character or characters that immediately follow a backslash. The backslash '\' should have already been read. This supports both unicode escapes "u000A" and two-character escapes "\n".- Throws:
JSONException
-
readLiteral
private java.lang.Object readLiteral() throws JSONException
Reads a null, boolean, numeric or unquoted string literal value. Numeric values will be returned as an Integer, Long, or Double, in that order of preference.- Throws:
JSONException
-
nextToInternal
private java.lang.String nextToInternal(java.lang.String excluded)
Returns the string up to but not including any of the given characters or a newline character. This does not consume the excluded character.
-
readObject
private JSONObject readObject(int nestingLevel) throws JSONException
Reads a sequence of key/value pairs and the trailing closing brace '}' of an object. The opening brace '{' should have already been read.- Throws:
JSONException
-
readArray
private JSONArray readArray(int nestingLevel) throws JSONException
Reads a sequence of values and the trailing closing brace ']' of an array. The opening brace '[' should have already been read. Note that "[]" yields an empty array, but "[,]" returns a two-element array equivalent to "[null,null]".- Throws:
JSONException
-
syntaxError
public JSONException syntaxError(java.lang.String message)
Returns an exception containing the given message plus the current position and the entire input string.- Parameters:
message
- The message we want to include.- Returns:
- An exception that we can throw.
-
toString
public java.lang.String toString()
Returns the current position and the entire input string.- Overrides:
toString
in classjava.lang.Object
-
more
public boolean more()
Returns true until the input has been exhausted.- Returns:
- true if more input exists.
-
next
public char next()
Returns the next available character, or the null character '\0' if all inputs have been exhausted. The return value of this method is ambiguous for JSON strings that contain the character '\0'.- Returns:
- the next character.
-
next
public char next(char c) throws JSONException
Returns the next available character if it equalsc
. Otherwise, an exception is thrown.- Parameters:
c
- The character we are looking for.- Returns:
- the next character.
- Throws:
JSONException
- If the next character isn'tc
-
nextClean
public char nextClean() throws JSONException
Returns the next character that is not whitespace and does not belong to a comment. If the input is exhausted before such a character can be found, the null character '\0' is returned. The return value of this method is ambiguous for JSON strings that contain the character '\0'.- Returns:
- The next non-whitespace character.
- Throws:
JSONException
- Should not be possible.
-
next
public java.lang.String next(int length) throws JSONException
Returns the nextlength
characters of the input.The returned string shares its backing character array with this tokener's input string. If a reference to the returned string may be held indefinitely, you should use
new String(result)
to copy it first to avoid memory leaks.- Parameters:
length
- The desired number of characters to return.- Returns:
- The next few characters.
- Throws:
JSONException
- if the remaining input is not long enough to satisfy this request.
-
nextTo
public java.lang.String nextTo(java.lang.String excluded)
Returns thetrimmed
string holding the characters up to but not including the first of:- any character in
excluded
- a newline character '\n'
- a carriage return '\r'
The returned string shares its backing character array with this tokener's input string. If a reference to the returned string may be held indefinitely, you should use
new String(result)
to copy it first to avoid memory leaks.- Parameters:
excluded
- The limiting string where the search should stop.- Returns:
- a possibly-empty string
- any character in
-
nextTo
public java.lang.String nextTo(char excluded)
Equivalent tonextTo(String.valueOf(excluded))
.- Parameters:
excluded
- The limiting character.- Returns:
- a possibly-empty string
-
skipPast
public void skipPast(java.lang.String thru)
Advances past all input up to and including the next occurrence ofthru
. If the remaining input doesn't containthru
, the input is exhausted.- Parameters:
thru
- The string to skip over.
-
skipTo
public char skipTo(char to)
Advances past all inputs up to but not including the next occurrence ofto
. If the remaining input doesn't containto
, the input is unchanged.- Parameters:
to
- The character we want to skip to.- Returns:
- The value of
to
or null.
-
back
public void back()
Unreads the most recent character of input. If no input characters have been read, the input is unchanged.
-
dehexchar
public static int dehexchar(char hex)
Returns the integer [0..15] value for the given hex character, or -1 for non-hex input.- Parameters:
hex
- a character in the ranges [0-9], [A-F] or [a-f]. Any other character will yield a -1 result.- Returns:
- The decoded integer.
-
-