public final class JsDocInfoParser
extends java.lang.Object
Modifier and Type | Class and Description |
---|---|
private static class |
JsDocInfoParser.ExtendedTypeInfo
Tuple for recording extended types
|
private static class |
JsDocInfoParser.ExtractionInfo
Tuple for returning both the string extracted and the
new token following a call to any of the extract*Block
methods.
|
private static class |
JsDocInfoParser.State |
private static class |
JsDocInfoParser.WhitespaceOption |
Modifier and Type | Field and Description |
---|---|
private java.util.Map<java.lang.String,Annotation> |
annotationNames |
private ErrorReporter |
errorReporter |
private JSDocInfoBuilder |
fileLevelJsDocBuilder |
private JSDocInfo |
fileOverviewJSDocInfo |
private static java.util.Set<java.lang.String> |
idGeneratorAnnotationKeywords |
private JSDocInfoBuilder |
jsdocBuilder |
private static java.util.Set<java.lang.String> |
modifiesAnnotationKeywords |
private static JsDocToken |
NO_UNREAD_TOKEN
Specific value indicating that the
unreadToken contains no token. |
private boolean |
preserveWhitespace |
private StaticSourceFile |
sourceFile |
private JsDocInfoParser.State |
state |
private JsDocTokenStream |
stream |
private java.util.Set<java.lang.String> |
suppressionNames |
private Node |
templateNode |
private JsDocToken |
unreadToken
One token buffer.
|
Constructor and Description |
---|
JsDocInfoParser(JsDocTokenStream stream,
java.lang.String comment,
int commentPosition,
StaticSourceFile sourceFile,
Config config,
ErrorReporter errorReporter) |
Modifier and Type | Method and Description |
---|---|
private void |
addMissingTypeWarning(int lineno,
int charno) |
private void |
addParserWarning(java.lang.String messageId) |
private void |
addParserWarning(java.lang.String messageId,
int lineno,
int charno) |
private void |
addParserWarning(java.lang.String messageId,
java.lang.String messageArg) |
private void |
addParserWarning(java.lang.String messageId,
java.lang.String messageArg,
int lineno,
int charno) |
private void |
addTypeWarning(java.lang.String messageId) |
private void |
addTypeWarning(java.lang.String messageId,
int lineno,
int charno) |
private void |
addTypeWarning(java.lang.String messageId,
java.lang.String messageArg) |
private void |
addTypeWarning(java.lang.String messageId,
java.lang.String messageArg,
int lineno,
int charno) |
private void |
checkExtendedTypes(java.util.List<JsDocInfoParser.ExtendedTypeInfo> extendedTypes) |
(package private) JSTypeExpression |
createJSTypeExpression(Node n)
Constructs a new
JSTypeExpression . |
private Node |
createTemplateNode() |
private JsDocToken |
current()
Gets the current token, invalidating it in the process.
|
private JsDocToken |
eatTokensUntilEOL()
Eats tokens until
JsDocToken.EOL included, and switches back the
state to JsDocInfoParser.State.SEARCHING_ANNOTATION . |
private JsDocToken |
eatTokensUntilEOL(JsDocToken token)
Eats tokens until
JsDocToken.EOL included, and switches back the
state to JsDocInfoParser.State.SEARCHING_ANNOTATION . |
private JsDocToken |
eatUntilEOLIfNotAnnotation() |
private JsDocToken |
eatUntilEOLIfNotAnnotation(JsDocToken token) |
private JsDocInfoParser.ExtractionInfo |
extractBlockComment(JsDocToken token)
Extracts the top-level block comment from the JsDoc comment, if any.
|
private JsDocInfoParser.ExtractionInfo |
extractMultilineComment(JsDocToken token,
JsDocInfoParser.WhitespaceOption option,
boolean isMarker,
boolean includeAnnotations)
Extracts text from the stream until the end of the comment, end of the
file, or an annotation token is encountered.
|
private JsDocInfoParser.ExtractionInfo |
extractMultilineTextualBlock(JsDocToken token) |
private JsDocInfoParser.ExtractionInfo |
extractMultilineTextualBlock(JsDocToken token,
JsDocInfoParser.WhitespaceOption option,
boolean includeAnnotations)
Extracts the text found on the current line and all subsequent
until either an annotation, end of comment or end of file is reached.
|
private JsDocInfoParser.ExtractionInfo |
extractSingleLineBlock()
Extracts the text found on the current line starting at token.
|
(package private) JSDocInfo |
getFileOverviewJSDocInfo()
Gets the fileoverview JSDocInfo, if any.
|
private static JsDocInfoParser |
getParser(java.lang.String toParse) |
private java.lang.String |
getRemainingJSDocLine()
Returns the remainder of the line.
|
private java.lang.String |
getSourceName() |
private JsDocInfoParser.WhitespaceOption |
getWhitespaceOption(JsDocInfoParser.WhitespaceOption defaultValue) |
private boolean |
hasParsedFileOverviewDocInfo()
Determines whether the parser has been populated with docinfo with a
fileoverview tag.
|
private boolean |
lookAheadFor(char expect)
Look ahead by advancing the character stream.
|
private boolean |
lookAheadForAnnotation() |
private boolean |
lookAheadForType()
Look ahead for a type annotation by advancing the character stream.
|
private boolean |
match(JsDocToken token)
Tests whether the next symbol of the token stream matches the specific
token.
|
private boolean |
match(JsDocToken token1,
JsDocToken token2)
Tests that the next symbol of the token stream matches one of the specified
tokens.
|
private Node |
newNode(int type) |
private Node |
newStringNode(java.lang.String s) |
private Node |
newStringNode(java.lang.String s,
int lineno,
int charno) |
private JsDocToken |
next()
Gets the next token of the token stream or the buffered token if a matching
was previously made.
|
private void |
padLine(java.lang.StringBuilder builder,
int lineStartChar,
JsDocInfoParser.WhitespaceOption option) |
(package private) boolean |
parse()
Parses a
JSDocInfo object. |
private Node |
parseAndRecordParamTypeNode(JsDocToken token)
Looks for a type expression at the current token and if found,
returns it.
|
private Node |
parseAndRecordTypeNameNode(JsDocToken token,
int lineno,
int startCharno,
boolean matchingLC)
Looks for a type expression at the current token and if found,
returns it.
|
(package private) Node |
parseAndRecordTypeNode(JsDocToken token)
Looks for a type expression at the current token and if found,
returns it.
|
private Node |
parseAndRecordTypeNode(JsDocToken token,
int lineno,
int startCharno,
boolean matchingLC,
boolean onlyParseSimpleNames)
Looks for a parameter type expression at the current token and if found,
returns it.
|
private JsDocToken |
parseAnnotation(JsDocToken token,
java.util.List<JsDocInfoParser.ExtendedTypeInfo> extendedTypes) |
private Node |
parseBasicTypeExpression(JsDocToken token)
BasicTypeExpression := '*' | 'null' | 'undefined' | TypeName
| FunctionType | UnionType | RecordType
|
private Node |
parseContextTypeExpression(JsDocToken token)
ContextTypeExpression := BasicTypeExpression | '?'
For expressions on the right hand side of a this: or new:
|
private Node |
parseFieldName(JsDocToken token)
FieldName := NameExpression | StringLiteral | NumberLiteral |
ReservedIdentifier
|
private Node |
parseFieldType(JsDocToken token)
FieldType := FieldName | FieldName ':' TypeExpression
|
private Node |
parseFieldTypeList(JsDocToken token)
FieldTypeList := FieldType | FieldType ',' FieldTypeList
|
private Node |
parseFunctionType(JsDocToken token)
FunctionType := 'function' FunctionSignatureType
FunctionSignatureType :=
TypeParameters '(' 'this' ':' TypeName, ParametersType ')' ResultType
|
private boolean |
parseHelperLoop(JsDocToken token,
java.util.List<JsDocInfoParser.ExtendedTypeInfo> extendedTypes) |
private JsDocToken |
parseIdGeneratorTag(JsDocToken token)
Parse a
@idgenerator tag of the form
@idgenerator or
@idgenerator{consistent} . |
JSDocInfo |
parseInlineTypeDoc()
Parse a description as a
@type . |
static JSDocInfo |
parseJsdoc(java.lang.String toParse)
Parses a string containing a JsDoc declaration, returning the entire JSDocInfo
if the parsing succeeded or
null if it failed. |
private JsDocToken |
parseModifiesTag(JsDocToken token)
Parse a
@modifies tag of the form
@modifies{this|arguments|param} . |
private Node |
parseParametersType(JsDocToken token)
ParametersType := RestParameterType | NonRestParametersType
| NonRestParametersType ',' RestParameterType
RestParameterType := '...' Identifier
NonRestParametersType := ParameterType ',' NonRestParametersType
| ParameterType
| OptionalParametersType
OptionalParametersType := OptionalParameterType
| OptionalParameterType, OptionalParametersType
OptionalParameterType := ParameterType=
ParameterType := TypeExpression | Identifier ':' TypeExpression
|
private Node |
parseParamTypeExpression(JsDocToken token)
ParamTypeExpression :=
OptionalParameterType |
TopLevelTypeExpression |
'...' TopLevelTypeExpression
OptionalParameterType :=
TopLevelTypeExpression '='
|
private Node |
parseParamTypeExpressionAnnotation(JsDocToken token)
ParamTypeExpressionAnnotation := '{' ParamTypeExpression '}'
|
private Node |
parseRecordType(JsDocToken token)
RecordType := '{' FieldTypeList '}'
|
private Node |
parseResultType()
ResultType :=
|
private JsDocToken |
parseSuppressTag(JsDocToken token)
Parse a
@suppress tag of the form
@suppress{warning1|warning2} . |
private Node |
parseTopLevelTypeExpression(JsDocToken token)
TopLevelTypeExpression := TypeExpression
| TypeUnionList
We made this rule up, for the sake of backwards compatibility.
|
private Node |
parseTypeExpression(JsDocToken token)
TypeExpression := BasicTypeExpression
| '?' BasicTypeExpression
| '!' BasicTypeExpression
| BasicTypeExpression '?'
| BasicTypeExpression '!'
| '?'
|
private Node |
parseTypeExpressionAnnotation(JsDocToken token)
TypeExpressionAnnotation := TypeExpression |
'{' TopLevelTypeExpression '}'
|
private Node |
parseTypeExpressionList(JsDocToken token)
TypeExpressionList := TopLevelTypeExpression
| TopLevelTypeExpression ',' TypeExpressionList
|
private Node |
parseTypeName(JsDocToken token)
TypeName := NameExpression | NameExpression TypeApplication
TypeApplication := '.<' TypeExpressionList '>'
|
private Node |
parseTypeNameAnnotation(JsDocToken token)
TypeNameAnnotation := TypeName | '{' TypeName '}'
|
static Node |
parseTypeString(java.lang.String typeString)
Parses a string containing a JsDoc type declaration, returning the
type if the parsing succeeded or
null if it failed. |
private Node |
parseUnionType(JsDocToken token)
UnionType := '(' TypeUnionList ')'
TypeUnionList := TypeExpression | TypeExpression '|' TypeUnionList
We've removed the empty union type.
|
private Node |
parseUnionTypeWithAlternate(JsDocToken token,
Node alternate)
Create a new union type, with an alternate that has already been
parsed.
|
private JsDocToken |
recordDescription(JsDocToken token)
Records a marker's description if there is one available and record it in
the current marker.
|
private void |
recordTypeNode(int lineno,
int startCharno,
Node typeAst,
boolean matchingLC) |
private Node |
reportGenericTypeSyntaxWarning() |
private Node |
reportTypeSyntaxWarning(java.lang.String warning) |
private void |
restoreLookAhead(JsDocToken token)
Restores the lookahead token to the token stream
|
(package private) JSDocInfo |
retrieveAndResetParsedJSDocInfo() |
(package private) void |
setFileLevelJsDocBuilder(JSDocInfoBuilder fileLevelJsDocBuilder)
Sets the JsDocBuilder for the file-level (root) node of this parse.
|
(package private) void |
setFileOverviewJSDocInfo(JSDocInfo fileOverviewJSDocInfo)
Sets the file overview JSDocInfo, in order to warn about multiple uses of
the @fileoverview tag in a file.
|
private void |
skipEOLs()
Skips all EOLs and all empty lines in the JSDoc.
|
private java.lang.String |
toString(JsDocToken token)
Converts a JSDoc token to its string representation.
|
private static java.lang.String |
trimEnd(java.lang.String s)
Trim characters from only the end of a string.
|
private static boolean |
validTemplateTypeName(java.lang.String name)
The types in @template annotations must start with a capital letter, and contain
only letters, digits, and underscores.
|
private Node |
wrapNode(int type,
Node n) |
private final JsDocTokenStream stream
private final JSDocInfoBuilder jsdocBuilder
private final StaticSourceFile sourceFile
private final ErrorReporter errorReporter
private final Node templateNode
private JSDocInfo fileOverviewJSDocInfo
private JsDocInfoParser.State state
private final java.util.Map<java.lang.String,Annotation> annotationNames
private final java.util.Set<java.lang.String> suppressionNames
private final boolean preserveWhitespace
private static final java.util.Set<java.lang.String> modifiesAnnotationKeywords
private static final java.util.Set<java.lang.String> idGeneratorAnnotationKeywords
private JSDocInfoBuilder fileLevelJsDocBuilder
private static final JsDocToken NO_UNREAD_TOKEN
unreadToken
contains no token.private JsDocToken unreadToken
JsDocInfoParser(JsDocTokenStream stream, java.lang.String comment, int commentPosition, StaticSourceFile sourceFile, Config config, ErrorReporter errorReporter)
private void addParserWarning(java.lang.String messageId, java.lang.String messageArg)
private void addParserWarning(java.lang.String messageId, java.lang.String messageArg, int lineno, int charno)
private void addParserWarning(java.lang.String messageId)
private void addParserWarning(java.lang.String messageId, int lineno, int charno)
private void addTypeWarning(java.lang.String messageId, java.lang.String messageArg)
private void addTypeWarning(java.lang.String messageId, java.lang.String messageArg, int lineno, int charno)
private void addTypeWarning(java.lang.String messageId)
private void addTypeWarning(java.lang.String messageId, int lineno, int charno)
private void addMissingTypeWarning(int lineno, int charno)
void setFileLevelJsDocBuilder(JSDocInfoBuilder fileLevelJsDocBuilder)
fileLevelJsDocBuilder
- void setFileOverviewJSDocInfo(JSDocInfo fileOverviewJSDocInfo)
private java.lang.String getSourceName()
public JSDocInfo parseInlineTypeDoc()
@type
.private void recordTypeNode(int lineno, int startCharno, Node typeAst, boolean matchingLC)
public static Node parseTypeString(java.lang.String typeString)
null
if it failed.public static JSDocInfo parseJsdoc(java.lang.String toParse)
null
if it failed.private static JsDocInfoParser getParser(java.lang.String toParse)
boolean parse()
JSDocInfo
object. This parsing method reads all tokens
returned by the JsDocTokenStream.getJsDocToken()
method until the
JsDocToken.EOC
is returned.true
if JSDoc information was correctly parsed,
false
otherwiseprivate boolean parseHelperLoop(JsDocToken token, java.util.List<JsDocInfoParser.ExtendedTypeInfo> extendedTypes)
private JsDocToken parseAnnotation(JsDocToken token, java.util.List<JsDocInfoParser.ExtendedTypeInfo> extendedTypes)
private static boolean validTemplateTypeName(java.lang.String name)
private JsDocToken recordDescription(JsDocToken token)
private void checkExtendedTypes(java.util.List<JsDocInfoParser.ExtendedTypeInfo> extendedTypes)
private JsDocToken parseSuppressTag(JsDocToken token)
@suppress
tag of the form
@suppress{warning1|warning2}
.token
- The current token.private JsDocToken parseModifiesTag(JsDocToken token)
@modifies
tag of the form
@modifies{this|arguments|param}
.token
- The current token.private JsDocToken parseIdGeneratorTag(JsDocToken token)
@idgenerator
tag of the form
@idgenerator
or
@idgenerator{consistent}
.token
- The current token.Node parseAndRecordTypeNode(JsDocToken token)
token
- The current token.private Node parseAndRecordTypeNameNode(JsDocToken token, int lineno, int startCharno, boolean matchingLC)
token
- The current token.lineno
- The line of the type expression.startCharno
- The starting character position of the type expression.matchingLC
- Whether the type expression starts with a "{".private Node parseAndRecordParamTypeNode(JsDocToken token)
token
- The current token.private Node parseAndRecordTypeNode(JsDocToken token, int lineno, int startCharno, boolean matchingLC, boolean onlyParseSimpleNames)
token
- The current token.lineno
- The line of the type expression.startCharno
- The starting character position of the type expression.matchingLC
- Whether the type expression starts with a "{".onlyParseSimpleNames
- If true, only simple type names are parsed
(via a call to parseTypeNameAnnotation instead of
parseTypeExpressionAnnotation).private java.lang.String toString(JsDocToken token)
JSTypeExpression createJSTypeExpression(Node n)
JSTypeExpression
.n
- A node. May be null.private JsDocInfoParser.ExtractionInfo extractSingleLineBlock()
private JsDocInfoParser.ExtractionInfo extractMultilineTextualBlock(JsDocToken token)
private JsDocInfoParser.WhitespaceOption getWhitespaceOption(JsDocInfoParser.WhitespaceOption defaultValue)
private JsDocInfoParser.ExtractionInfo extractMultilineTextualBlock(JsDocToken token, JsDocInfoParser.WhitespaceOption option, boolean includeAnnotations)
token
- The start token.option
- How to handle whitespace.includeAnnotations
- Whether the extracted text may include
annotations. If set to false, text extraction will stop on the first
encountered annotation token.private JsDocInfoParser.ExtractionInfo extractBlockComment(JsDocToken token)
token
- The starting token.private JsDocInfoParser.ExtractionInfo extractMultilineComment(JsDocToken token, JsDocInfoParser.WhitespaceOption option, boolean isMarker, boolean includeAnnotations)
token
- The starting token.option
- How to handle whitespace.isMarker
- Whether the extracted text is for a JSDoc marker or a
block comment.includeAnnotations
- Whether the extracted text may include
annotations. If set to false, text extraction will stop on the first
encountered annotation token.private void padLine(java.lang.StringBuilder builder, int lineStartChar, JsDocInfoParser.WhitespaceOption option)
private static java.lang.String trimEnd(java.lang.String s)
s
- String to be trimmedprivate Node parseTypeExpressionAnnotation(JsDocToken token)
private Node parseParamTypeExpression(JsDocToken token)
private Node parseParamTypeExpressionAnnotation(JsDocToken token)
private Node parseTypeNameAnnotation(JsDocToken token)
private Node parseTopLevelTypeExpression(JsDocToken token)
private Node parseTypeExpressionList(JsDocToken token)
private Node parseTypeExpression(JsDocToken token)
private Node parseContextTypeExpression(JsDocToken token)
private Node parseBasicTypeExpression(JsDocToken token)
private Node parseTypeName(JsDocToken token)
private Node parseFunctionType(JsDocToken token)
The Node that is produced has type Token.FUNCTION but does not look like a typical function node. If there is a 'this:' or 'new:' type, that type is added as a child. Then, if there are parameters, a PARAM_LIST node is added as a child. Finally, if there is a return type, it is added as a child. This means that the parameters could be the first or second child, and the return type could be the first, second, or third child.
private Node parseParametersType(JsDocToken token)
private Node parseResultType()
private Node parseUnionType(JsDocToken token)
private Node parseUnionTypeWithAlternate(JsDocToken token, Node alternate)
private Node parseRecordType(JsDocToken token)
private Node parseFieldTypeList(JsDocToken token)
private Node parseFieldType(JsDocToken token)
private Node parseFieldName(JsDocToken token)
private Node newNode(int type)
private Node newStringNode(java.lang.String s)
private Node newStringNode(java.lang.String s, int lineno, int charno)
private Node createTemplateNode()
private Node reportTypeSyntaxWarning(java.lang.String warning)
private Node reportGenericTypeSyntaxWarning()
private JsDocToken eatUntilEOLIfNotAnnotation()
private JsDocToken eatUntilEOLIfNotAnnotation(JsDocToken token)
private JsDocToken eatTokensUntilEOL()
JsDocToken.EOL
included, and switches back the
state to JsDocInfoParser.State.SEARCHING_ANNOTATION
.private JsDocToken eatTokensUntilEOL(JsDocToken token)
JsDocToken.EOL
included, and switches back the
state to JsDocInfoParser.State.SEARCHING_ANNOTATION
.private void restoreLookAhead(JsDocToken token)
private boolean match(JsDocToken token)
private boolean match(JsDocToken token1, JsDocToken token2)
private JsDocToken next()
private JsDocToken current()
private void skipEOLs()
private java.lang.String getRemainingJSDocLine()
private boolean hasParsedFileOverviewDocInfo()
JSDocInfo retrieveAndResetParsedJSDocInfo()
JSDocInfo getFileOverviewJSDocInfo()
private boolean lookAheadForType()
private boolean lookAheadForAnnotation()
private boolean lookAheadFor(char expect)