[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 08/10] java: document new features
From: |
Akim Demaille |
Subject: |
[PATCH 08/10] java: document new features |
Date: |
Tue, 7 Apr 2020 07:13:55 +0200 |
* data/skeletons/lalr1.java: More comments.
(Context.EMPTY): Remove.
* doc/bison.texi (Java Parser Context Interface): New.
---
data/skeletons/lalr1.java | 27 ++++++++++------
doc/bison.texi | 67 +++++++++++++++++++++++++++++++++++++++
2 files changed, 84 insertions(+), 10 deletions(-)
diff --git a/data/skeletons/lalr1.java b/data/skeletons/lalr1.java
index f2e64e44..58957a2d 100644
--- a/data/skeletons/lalr1.java
+++ b/data/skeletons/lalr1.java
@@ -876,17 +876,20 @@ b4_dollar_popdef[]dnl
private YYStack yystack;
+
+ /**
+ * The symbol kind of the lookahead token.
+ */
public SymbolKind getToken ()
{
return yytoken;
}
+ private SymbolKind yytoken;]b4_locations_if([[
+
/**
- * Value returned by getToken when there is no token.
+ * The location of the lookahead.
*/
- public static final int EMPTY = ]b4_parser_class[.YYEMPTY_;
-
- private SymbolKind yytoken;]b4_locations_if([[
public ]b4_location_type[ getLocation ()
{
return yylocation;
@@ -895,10 +898,12 @@ b4_dollar_popdef[]dnl
private ]b4_location_type[ yylocation;]])[
static final int NTOKENS = ]b4_parser_class[.YYNTOKENS_;
- /* Put in YYARG at most YYARGN of the expected tokens given the
- current YYCTX, and return the number of tokens stored in YYARG. If
- YYARG is null, return the number of expected tokens (guaranteed to
- be less than YYNTOKENS). */
+ /**
+ * Put in YYARG at most YYARGN of the expected tokens given the
+ * current YYCTX, and return the number of tokens stored in YYARG. If
+ * YYARG is null, return the number of expected tokens (guaranteed to
+ * be less than YYNTOKENS).
+ */
int getExpectedTokens (SymbolKind yyarg[], int yyargn)
{
return getExpectedTokens (yyarg, 0, yyargn);
@@ -933,8 +938,10 @@ b4_dollar_popdef[]dnl
return yycount - yyoffset;
}
- /* The user-facing name of the symbol whose (internal) number is
- YYSYMBOL. No bounds checking. */
+ /**
+ * The user-facing name of the symbol whose (internal) number is
+ * YYSYMBOL. No bounds checking.
+ */
static String yysymbolName (SymbolKind yysymbol)
{
return ]b4_parser_class[.yysymbolName (yysymbol);
diff --git a/doc/bison.texi b/doc/bison.texi
index ef77d618..9693fa09 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -433,6 +433,7 @@ Java Parsers
* Java Semantic Values:: %token and %nterm vs. Java
* Java Location Values:: The position and location classes
* Java Parser Interface:: Instantiating and running the parser
+* Java Parser Context Interface:: Circumstances of a syntax error
* Java Scanner Interface:: Specifying the scanner for the parser
* Java Action Features:: Special features for use in actions
* Java Push Parser Interface:: Instantiating and running the a push parser
@@ -12673,6 +12674,7 @@ main (int argc, char *argv[])
* Java Semantic Values:: %token and %nterm vs. Java
* Java Location Values:: The position and location classes
* Java Parser Interface:: Instantiating and running the parser
+* Java Parser Context Interface:: Circumstances of a syntax error
* Java Scanner Interface:: Specifying the scanner for the parser
* Java Action Features:: Special features for use in actions
* Java Push Parser Interface:: Instantiating and running the a push parser
@@ -12917,6 +12919,37 @@ Identify the Bison version and skeleton used to
generate this parser.
@end deftypecv
+@node Java Parser Context Interface
+@subsection Java Parser Context Interface
+
+The parser context provides information to build error reports when you
+invoke @samp{%define parse.error custom}.
+
+@deftypemethod {YYParser.Context} {YYParser.SymbolKind} getToken ()
+The kind of the lookahead. Maybe return @code{null} when there is no
+lookahead.
+@end deftypemethod
+
+@deftypemethod {YYParser.Context} {YYParser.Location} getLocation ()
+The location of the lookahead.
+@end deftypemethod
+
+@deftypemethod {YYParser.Context} {int} getExpectedTokens
(@code{YYParser.SymbolKind[]} @var{argv}, @code{int} @var{argc})
+Fill @var{argv} with the expected tokens, which never includes
+@code{YYSYMBOL_YYEMPTY}, @code{YYSYMBOL_YYERROR}, or
+@code{YYSYMBOL_YYUNDEF}.
+
+Never put more than @var{argc} elements into @var{argv}, and on success
+return the effective number of tokens stored in @var{argv}. Return 0 if
+there are more than @var{argc} expected tokens, yet fill @var{argv} up to
+@var{argc}. When LAC is enabled, may return a negative number on errors,
+such as @code{YYNOMEM} on memory exhaustion.
+
+If @var{argv} is null, return the size needed to store all the possible
+values, which is always less than @code{YYNTOKENS}.
+@end deftypemethod
+
+
@node Java Scanner Interface
@subsection Java Scanner Interface
@c - %code lexer
@@ -12979,6 +13012,40 @@ The return type can be changed using @samp{%define
api.value.type
@{@var{class-name}@}}.
@end deftypemethod
+@deftypemethod {Lexer} {void} reportSyntaxError (@code{YYParser.Context}
@var{ctx})
+If you invoke @samp{%define parse.error custom} (@pxref{Bison
+Declarations}), then the parser no longer passes syntax error messages to
+@code{yyerror}, rather it delegates that task to the user by calling the
+@code{reportSyntaxError} function.
+
+Whether it uses @code{yyerror} is up to the user.
+
+Here is a typical example of a reporting function.
+
+@example
+public void yyreportSyntaxError (YYParser.Context ctx)
+@{
+ System.err.print (ctx.getLocation () + ": syntax error");
+ // Report the expected tokens.
+ @{
+ final int TOKENMAX = 5;
+ YYParser.SymbolKind[] arg = new YYParser.SymbolKind[TOKENMAX];
+ int n = ctx.getExpectedTokens (arg, TOKENMAX);
+ for (int i = 0; i < n; ++i)
+ System.err.print ((i == 0 ? ": expected " : " or ")
+ + ctx.yysymbolName (arg[i]));
+ @}
+ // Report the unexpected token which triggered the error.
+ @{
+ YYParser.SymbolKind lookahead = ctx.getToken ();
+ if (lookahead != null)
+ System.err.print (" before " + ctx.yysymbolName (lookahead));
+ @}
+ System.err.println ("");
+@}
+@end example
+@end deftypemethod
+
@node Java Action Features
@subsection Special Features for Use in Java Actions
--
2.26.0
- [PATCH 00/10] Make recent feature better looking, Akim Demaille, 2020/04/07
- [PATCH 01/10] c: make the generated YYSTYPE nicer to read, Akim Demaille, 2020/04/07
- [PATCH 02/10] c: make the token kind definition nicer to read, Akim Demaille, 2020/04/07
- [PATCH 03/10] c: make the symbol kind definition nicer to read, Akim Demaille, 2020/04/07
- [PATCH 05/10] java: use getExpectedTokens, not yyexpectedTokens, Akim Demaille, 2020/04/07
- [PATCH 04/10] java: style: fix coding style, Akim Demaille, 2020/04/07
- [PATCH 07/10] java: prefer null to YYSYMBOL_YYEMPTY, Akim Demaille, 2020/04/07
- [PATCH 10/10] todo: update, Akim Demaille, 2020/04/07
- [PATCH 06/10] java: rename Lexer.yyreportSyntaxError as reportSyntaxError, Akim Demaille, 2020/04/07
- [PATCH 08/10] java: document new features,
Akim Demaille <=
- [PATCH 09/10] skeletons: beware not to use yyarg when it's null, Akim Demaille, 2020/04/07