Module Name: src
Committed By: christos
Date: Sun Jun 5 16:24:34 UTC 2016
Modified Files:
src/external/bsd/byacc/bin: yacc.1
Log Message:
Sync mdoc page with the one provided from upstream.
To generate a diff of this commit:
cvs rdiff -u -r1.4 -r1.5 src/external/bsd/byacc/bin/yacc.1
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/external/bsd/byacc/bin/yacc.1
diff -u src/external/bsd/byacc/bin/yacc.1:1.4 src/external/bsd/byacc/bin/yacc.1:1.5
--- src/external/bsd/byacc/bin/yacc.1:1.4 Sat Sep 10 17:38:59 2011
+++ src/external/bsd/byacc/bin/yacc.1 Sun Jun 5 12:24:34 2016
@@ -1,4 +1,4 @@
-.\" $NetBSD: yacc.1,v 1.4 2011/09/10 21:38:59 christos Exp $
+.\" $NetBSD: yacc.1,v 1.5 2016/06/05 16:24:34 christos Exp $
.\"
.\" Copyright (c) 1989, 1990 The Regents of the University of California.
.\" All rights reserved.
@@ -31,10 +31,10 @@
.\" SUCH DAMAGE.
.\"
.\" from: @(#)yacc.1 5.7 (Berkeley) 7/30/91
-.\" from: Id: yacc.1,v 1.12 2011/09/08 00:40:44 tom Exp
-.\" $NetBSD: yacc.1,v 1.4 2011/09/10 21:38:59 christos Exp $
+.\" from: Id: yacc.1,v 1.24 2014/10/06 00:03:48 tom Exp
+.\" $NetBSD: yacc.1,v 1.5 2016/06/05 16:24:34 christos Exp $
.\"
-.Dd September 7, 2011
+.Dd October 5, 2014
.Dt YACC 1
.Os
.Sh NAME
@@ -44,9 +44,9 @@
parser generator
.Sh SYNOPSIS
.Nm
-.Op Fl dgilPrtVv
-.Op Fl b Ar prefix
-.Op Fl o Ar outputfile
+.Op Fl BdgilLPrtvVy
+.Op Fl b Ar file_prefix
+.Op Fl o Ar output_file
.Op Fl p Ar symbol_prefix
.Ar filename
.Sh DESCRIPTION
@@ -65,15 +65,18 @@ normally writes the parse tables and the
.Pa y.tab.c .
.Pp
The following options are available:
-.Bl -tag -width Ar
-.It Fl b Ar prefix
+.Bl -tag -width symbol_prefixXXX
+.It Fl b Ar file_prefix
The
.Fl b
option changes the prefix prepended to the output file names to
the string denoted by
-.Ar prefix .
+.Ar file_prefix .
The default prefix is the character
.Ar y .
+.It Fl B
+Create a backtracking parser (compile-type configuration for
+.Nm ) .
.It Fl d
The
.Fl d
@@ -124,11 +127,19 @@ option is specified,
.Nm
will not insert the #line directives.
#line directives specified by the user will be retained.
-.It Fl o Ar outputfile
-The
-.Fl o
-option specifies an explicit output file name should be used instead
-of the default.
+.It Fl L
+Enable position processing, e.g.,
+.Dq %locations
+(compile-type configuration for
+.Nm ) .
+.It Fl o Ar output_file
+Specify the filename for the parser file.
+If this option is not given, the output filename is
+the file prefix concatenated with the file suffix, e.g.
+.Pa y.tab.c .
+This overrides the
+.Fl b
+option.
.It Fl P
The
.Fl P
@@ -155,6 +166,53 @@ The code file is named
.Pa y.code.c ,
and the tables file is named
.Pa y.tab.c .
+The prefix
+.Dq y.
+can be overridden using the
+.Fl b
+option.
+.It Fl s
+Suppress
+.Dq #define
+statements generated for string literals in a
+.Dq %token
+statement, to more closely match original
+.Nm
+behavior.
+.Pp
+Normally when
+.Nm
+sees a line such as
+.Dq %token OP_ADD "ADD"
+it notices that the quoted
+.Dq ADD
+is a valid C identifier, and generates a #define not only for
+.Dv OP_ADD ,
+but for
+.Dv ADD
+as well,
+e.g.,
+.Bd -literal -offset indent
+#define OP_ADD 257
+#define ADD 258
+.Ed
+The original
+.Nm
+does not generate the second
+.Dq #define .
+The
+.Fl s
+option suppresses this
+.Dq #define .
+.Pp
+.St -p1003.1
+documents only names and numbers for
+.Dq %token ,
+though the original
+.Nm
+and
+.Xr bison 1
+also accept string literals.
.It Fl t
The
.Fl t
@@ -171,14 +229,87 @@ The
option causes a human-readable description of the generated parser to
be written to the file
.Pa y.output .
+.It Fl y
+.Nm
+ignores this option,
+which
+.Xr bison 1
+supports for ostensible POSIX compatibility.
.El
.Sh EXTENSIONS
.Nm
-provides some extensions for compatibility with
+provides some extensions for
+compatibility with
.Xr bison 1
-and other implementations
-of
-.Nm :
+and other implementations of yacc.
+The
+.Dq %destructor
+and
+.Dq %locations
+features are available only if
+.Nm yacc
+has been configured and compiled to support the back-tracking functionality.
+The remaining features are always available:
+.Pp
+.Dv %destructor {
+.Dv code }
+.Dv symbol+
+.Pp
+Defines code that is invoked when a symbol is automatically
+discarded during error recovery.
+This code can be used to
+reclaim dynamically allocated memory associated with the corresponding
+semantic value for cases where user actions cannot manage the memory
+explicitly.
+.Pp
+On encountering a parse error, the generated parser
+discards symbols on the stack and input tokens until it reaches a state
+that will allow parsing to continue.
+This error recovery approach results in a memory leak
+if the
+.Dq YYSTYPE
+value is, or contains, pointers to dynamically allocated memory.
+.Pp
+The bracketed
+.Dv code
+is invoked whenever the parser discards one of the symbols.
+Within
+.Dv code ,
+.Dq $$
+or
+.Dq $\*[Lt]tag\*[Gt]$
+designates the semantic value associated with the discarded symbol, and
+.Dq @$
+designates its location (see
+.Dq %locations
+directive).
+.Pp
+A per-symbol destructor is defined by listing a grammar symbol
+in
+.Dv symbol+ .
+A per-type destructor is defined by listing a semantic type tag (e.g.,
+.Dq \*[Lt]some_tag\*[Gt] )
+in
+.Dv symbol+ ;
+in this case, the parser will invoke
+.Dv code
+whenever it discards any grammar symbol that has that semantic type tag,
+unless that symbol has its own per-symbol destructor.
+.Pp
+Two categories of default destructor are supported that are
+invoked when discarding any grammar symbol that has no per-symbol and no
+per-type destructor:
+.Pp
+The code for
+.Dq \*[Lt]*\*[Gt]
+is used
+for grammar symbols that have an explicitly declared semantic type tag
+(via
+.Dq %type ) ;
+.Pp
+the code for
+.Dq \*[Lt]\*[Gt]
+is used for grammar symbols that have no declared semantic type tag.
.Pp
.Bl -tag -width "%expect-rr number" -compact
.It Dv %expect Ar number
@@ -196,6 +327,71 @@ This is (unlike
allowable in
.Tn LALR(1)
parsers.
+.It Dv %locations
+Tell
+.Nm
+to enable management of position information associated with each token,
+provided by the lexer in the global variable
+.Dv yylloc ,
+similar to management of semantic value information provided in
+.Dv yylval .
+.Pp
+As for semantic values, locations can be referenced within actions using
+.Dv @$
+to refer to the location of the left hand side symbol, and
+.Dv @N (
+.Dv N
+an integer) to refer to the location of one of the right hand side
+symbols.
+Also as for semantic values, when a rule is matched, a default
+action is used the compute the location represented by
+.Dv @$
+as the beginning of the first symbol and the end of the last symbol
+in the right hand side of the rule.
+This default computation can be overridden by
+explicit assignment to
+.Dv @$
+in a rule action.
+.Pp
+The type of
+.Dv yylloc
+is
+.Dv YYLTYPE ,
+which is defined by default as:
+.Bd -literal -offset indent
+typedef struct YYLTYPE {
+ int first_line;
+ int first_column;
+ int last_line;
+ int last_column;
+} YYLTYPE;
+.Ed
+.Pp
+.Dv YYLTYPE
+can be redefined by the user (
+.Dv YYLTYPE_IS_DEFINED
+must be defined, to inhibit the default)
+in the declarations section of the specification file.
+As in
+.Xr bison 1 ,
+the macro
+.Dv YYLLOC_DEFAULT
+is invoked each time a rule is matched to calculate a position for the
+left hand side of the rule, before the associated action is executed;
+this macro can be redefined by the user.
+.Pp
+This directive adds a
+.Dv YYLTYPE
+parameter to
+.Fn yyerror .
+If the
+.Dq %pure-parser
+directive is present,
+a
+.Dv YYLTYPE
+parameter is added to
+.Fn yylex
+calls.
.It Dv %lex-param Ar { Ar argument-declaration Ar }
By default, the lexer accepts no parameters, e.g.,
.Fn yylex .
@@ -212,6 +408,120 @@ and
are allocated on the stack within
.Fn yyparse ,
making the parser reasonably reentrant.
+.It Dv %token-table
+Make the parser's names for tokens available in the
+.Dv yytname
+array.
+However,
+.Nm
+yacc
+does not predefine
+.Dq $end ,
+.Dq $error
+or
+.Dq $undefined
+in this array.
+.El
+.Sh PORTABILITY
+According to Robert Corbett:
+.Bd -offset indent
+Berkeley Yacc is an LALR(1) parser generator.
+Berkeley Yacc has been made as compatible as possible with AT\*[Am]T Yacc.
+Berkeley Yacc can accept any input specification that conforms to the
+AT\*[Am]T Yacc documentation.
+Specifications that take advantage of undocumented features of AT\*[Am]T
+Yacc will probably be rejected.
+.Ed
+.Pp
+The rationale in
+.%U http://pubs.opengroup.org/onlinepubs/9699919799/utilities/yacc.html
+documents some features of AT\*[Am]T yacc which are no longer required for
+POSIX compliance.
+.Pp
+That said, you may be interested in reusing grammar files with some
+other implementation which is not strictly compatible with AT\*[Am]T yacc.
+For instance, there is
+.Xr bison 1.
+Here are a few differences:
+.Nm
+accepts an equals mark preceding the left curly brace
+of an action (as in the original grammar file
+.Dv ftp.y ) :
+.Bd -literal -offset indent
+| STAT CRLF
+ = {
+ statcmd();
+ }
+.Ed
+.Nm
+and
+.Xr bison 1
+emit code in different order, and in particular
+.Xr bison 1
+makes forward reference to common functions such as
+.Fn yylex ,
+.Fn yyparse
+and
+.Fn yyerror
+without providing prototypes.
+.Pp
+.Xr bison 1
+support for
+.Dq %expect
+is broken in more than one release.
+For best results using
+.Xr bison 1 ,
+delete that directive.
+.Pp
+.Xr bison 1
+no equivalent for some of
+.Nm 's
+command-line options, relying on directives embedded in the grammar file.
+.Pp
+.Xr bison 1
+.Fl y
+option does not affect bison's lack of support for
+features of AT\*[Am]T yacc which were deemed obsolescent.
+.Pp
+.Nm
+accepts multiple parameters with
+.Dq %lex-param
+and
+.Dq %parse-param
+in two forms
+.Bd -literal -offset indent
+{type1 name1} {type2 name2} ...
+{type1 name1, type2 name2 ...}
+.Ed
+.Pp
+.Xr bison 1
+accepts the latter (though undocumented), but depending on the
+release may generate bad code.
+.Pp
+Like
+.Xr bison 1 ,
+.Nm
+will add parameters specified via
+.Dq %parse-param
+to
+.Fn yyparse ,
+.Fn yyerror
+and (if configured for back-tracking)
++to the destructor declared using
+.Dq %destructor .
+.Pp
+.Xr bison 1
+puts the additional parameters
+.Dv first
+for
+.Fn yyparse
+and
+.Fn yyerror
+but
+.Dv last
+for destructors.
+.Nm
+matches this behavior.
.El
.Sh ENVIRONMENT
The following environment variable is referenced by
