3.7.14 Analysis

3.7.14 %define Summary

Issues:
Suppose there is a directive "a.b.c" that has a value, then often these 
things are missing:
1: If the directive is not used, what is the default value?
2: If %define a.b.c         is entered, what is the default value?
3: if %define a.b.c "value" is entered, what are the legal values for value?
4: if %define a.b.c {value} is entered, what are the legal values for value?

To specify there is no default value implies the directive is required. 
The intent of this section seems to be that the directives are all 
optional. This means that if a directive is not supplied some default is 
used. The default may be nothing (nil, "", ...), but this is still a 
default.

If an error in processing a directive is found, what action is taken:
1: Is Bison processing halted?
2: Is a diagnostic message issued, Bison processing continues but 
generation of a parser terminated?
3: Is a diagnostic message issued, Bison processing continues and 
generation of a parser continues with some default supplied for the 
incorrect directive?
4: Or some other action taken?

Often when <file>, file, filename is used what is meant is 
<path>/filename. The discussion of filename appears to be a discussion 
of <path>, things such as relative path and absolute path do not exist 
for a filename. Could this be corrected in future Bison documentation?

Different means of describing the name of the generated parser file and 
it's header are used. Would it be possible to make this uniform 
throughout this document? For example, sometimes "basename.<ext>" is 
used and has been identified as being the actual output of the parser 
files. Could this be used throughout?

Some directives change the behavior of Bison, some directives alter the 
form of the Bison generated parser, and some directives have no effect 
on Bison but are just inserted into the generated parser. Would it be 
useful to specify this in the directive descriptions? It is done in some 
cases as an artifact of the description, but not as a separate attribute.

Can I do a "%define dedicated_directive value" as well as 
%"dedicated_directive"?
    What/where are the lists of "dedicated directives"? Can you 
hyperlink to this list?

"What variables are accepted, as well as their meanings and default 
values, depend on the selected target language and/or the parser 
skeleton (see Bison Declaration Summary, see Bison Declaration Summary). "

    Does this apply to Boolean variables? If it does it may be better to 
move this statement to precede the Boolean Variables. If it does not, 
since a Boolean Variable is a variable, what does "variable" mean in 
this context.

    What do you mean by "accept"? How can something be not accepted? Are 
you saying that a user can put an incorrect value in for a variable and 
that this value is rejected?

    "(see Bison Declaration Summary, see Bison Declaration Summary))" 
should be changed to "(see Bison Declaration Summary)"


In C/C++ and Java (I don't know D) the format a.b.c has a well-defined 
meaning. It is nowhere defined what meaning this syntax has in Bison. If 
you mean that "a.b.c" implies that "a" has members, one of which is "b" 
and that "b" has members, one of which is "c" then I think this should 
be mentioned somewhere. Then a user can infer that, e.g., for "api.", 
that api has more than 1 subordinate variable or variable category.

Directive: %define api.filename.type {type}

    Only one value seems to be defined this value does not seem to have 
any code component in the generated code (see Purpose).

    What is the purpose of this variable? In what context is it used? Is 
it possible to provide a rationale and an example?

    The hyperlink in Purpose, Exposing the Location Classes, does not 
clarify the meaniing of a file type. Where does the api.filename.type go?

    Accepted Values: Why is compatibility with '=' and "!=" an issue? 
Can an example and/or additional explanations be given?

    Constraints: Are there any constraints? For exemple, can <type> int 
be successfully used? Does the undervailing type have to derived from a 
string?


Directive: %define api.header.include {"header.h"}
Directive: %define api.header.include {<header.h>}

    Language(s): Shouldn't C++ be included?

    Purpose:
       "In all cases where y.tab is an issue", could you provide a 
hyperlink to the appropriate forward reference?

       "...generated a header and pasted an exact copy of it into the 
generated parser..."
     do you mean generated a #include "filename.h" or do you mean 
generated an include file and copied the include file contents into the 
generated parser? I assume the former.

    "The api.header.include variable allows to control how.." it might 
be better to say "The api.header.include variable allows control of how...".

    "Using api.header.include does not change the name of the generated 
header, only how it is included." I assume you mean "basename.h" for the 
name of the generated header. If this is accurate, could you hange 
"parser.h" to "basename.h"? If this is not accurate, could you explane 
what is meant?

    Default Value: ‘"header-basename"’
       It seems that the name of this file can be any one of 
"basename.h", "parser.h", "header-basename". Could this section be 
improved if the name of this file were made consistent?

Directive: %define api.location.file "file"
Directive: %define api.location.file none
     Purpose: Define the name of the file"
       Don't you mean path and file? The hyperlinked reference showing 
an example of use has "<path>/filename".

     Accept: none
       Is there any difference between not using this directive and 
including this directive with a "none" option? In either case, shouldn't 
this be mentioned?

       "...otherwise in the parser implementation" Shouldn't this be the 
Bison generated parser file?

    Accept: "file"
       Filenames are neither relative nor absolute. This applies to 
paths. Should the text be altered to identify that the path can be 
relative or absolute?

       Are there any constraints on "file", for example, does "file" 
have to be a legal <path>/filename in the current operating system?

    Default Value: Not applicable.
       Isn't the description indicate what the default is?

    What happens if this directive is used and %locations is not 
specified, is it ignored, a warning or error issued?

Directive: %define api.location.include {"file"}
Directive: %define api.location.include {<file>}

    I am confused between the difference and use of api.location.file 
and this. Does apo.location.file specify <path>/filename and this 
directive specify "include "<path>/filename"? What happens if they 
differ, as in api.location.file "mimi/location.hh" and 
api.location.include {george/location.hh}? What happens if there is a 
difference between -output=mimi/parser.cc and api.location.include 
{"george"/location.hh"}?

    Shouldn't perser.cc be changed to basename.cc to be consistent with 
other referencs to the generated output parser include file and source file?

Directive: %define api.location.type {type}

    Languages: Java
    Java doesn't have a typedef. The example given in 3.5.1 Data Type of 
Locations is unimplementable in Java. Since this is meant for Java, and 
example and explanation would be uservul

    Purpose:
       The examples given in 3.5.1 Data Type of Locations and 10.1.5.4 
User Defined Location Type don't seem to describe how to do anything. in 
3.5.1 Data Type it is proabably sutable to change the example given to 
something like:

       typedef struct newType
          int first_line;
          int first_column;
          int last_line;
          int last_column;
       } newType;

       or something which you find more appropriately represents intent.

       As a nit, {location_t} is used in 3.5.1 Data Type of Locations 
and {locatioTtype} is used in 10.1.5.4 User Defined Location Type. 
Between these tww there is an inconsitent use of a different names for 
the same thing, and the use of underscores is not consistentl

       Accepted Values: String
       Is "_&13NFO" an accetable value? If not then some constraints are 
needed.

       Default Value: none
       Isn't YYLTYPE the default value?

Directive: %define api.namespace {namespace}

    Accepted Values: Any absolute or relative ...
       What's a relative namespace? See 
https://en.cppreference.com/w/cpp/language/namespace

Directive: %define api.prefix {prefix}

    Since there are 3 api.[...].prefix directives {%define api.prefix, 
%define api.symbol.prefix, %define api.token.prefix {prefix}}, wouldn't 
it be more consistent if this was renamed to "%define 
api.export.prefix", or if alphabetic order is important, to rename all 
to {api.prefix.export, api.prefixsymbol, api.prefix.token}?

    Accepted Values: String
       Shouldn't this be an accepted identifier prefix?


Directive: %define api.pure purity

    "I.e., if ‘%locations %define api.pure’"
       Can you put two (or more) directives on the same line? Would you 
specify the delimeters which identify gthe end of one directive and the 
beginning of another? If %token is a dedicated directive, or some other 
(unspecified) tyhpe of directive, are these delimieters to same for a 
single, multi-line %token statement (see 3.7.2 Token Kind Names)>

    Default Value: false
       Is this a contradiction to
       Accepted Balues: "The value may be omitted: this is equivalent to 
specifying tru"?
       Is a missing value the same as a default value?

Directive: %define api.symbol.prefix {prefix} ¶

    There is no definition of "symbol kind" up to this point? What is a 
symbol kind and can yuo distinguish this to an "exported symbol" 
mentioned in %define api.prefix {prefix}? If there is an existing talbe 
for either exported symbol or symbol kind, coud a hyperlink to this 
table be provided?

    Accepted Values: Any non empty string.
       Ypu have conradicted the "Any" in the very next sentence. The 
only valid prefix values are identifiers in the languagae of choice. An 
empty string is not legal in any language that I am aware of (Ada, 
Algol, Bison, C/C++, COBOL, CSS, Fortran, GPSS, HTML, Lisp, MAD, Modula, 
Prolog, PL/I, Pascal, Simscript, Snobol), so saying it must be a legal 
identifier excludes the empty string.

Directive: %define api.token.constructor
    Purpose: Request that symbols be handled as a whole (type, value, 
and possibly location) in the scanner.
       What does this mean? What is a "whole"? If by scanner do you mean 
lexer? If it is the lexer could you use lexer instead of scanner? If it 
is not the lexer, could you provide a hyperlink to where this is 
defined? I note  here that 10.1.7 C++ Scanner Interface seems to call 
the lexer (yylex) the scanner. Parenthetically, how does the lexer 
handle a non-whole type?

Directive: %define api.token.raw
    Purpose:
       No definition of 'scanner' has been provided in this manual. For 
uniform use it is recommended that a definition of scanner be provided 
in a prominent place, or that all instances of scanner be replaced by 
'yylex' or lexor with a defnition specifying that for this documen the 
lexer implementation is yylex.

       In 3.7.2 Token Kind Names there is no mention of the relation 
between token codes and 257. It is best to make this number obvious and 
useful by provided its definition, use, and cautions in 3.7.2. It is 
hidden here and auser would not come across it except by accident.

    Accepted Value: Boolean
       The directive has no value. The definitino should be changed to 
"%define api.token.raw boolean", or an appropriate equivalent.

Directive: %define api.value.automove

    Accepted Value: Boolean
       The directive has no value. The definitino should be changed to 
"%define api.token.raw boolean", or an appropriate equivalent.

Directive: %define api.value.type support
Directive: %define api.value.type {type}

    Accepted VAlues:
       Is there an order relationship that has to be preserved in using 
these directives., for example in union-directive, %union follows the 
directive, and in variant the sruct precedes the directive.

       There is no variant dedicated directive or defined directeive, 
but there is a union dedicated directive. Will there be a variant 
dedicated directive in the future or the removal of a %union dedicated 
directive or status quo ante?

       The variant example shows the us of a union, not a variant, see 
https://en.cppreference.com/w/cpp/utility/variant. Eill s variant 
example be provided?


    Default VAlue: Undefined
       What does 'undefined' mean? How are the issues addressed in this 
definition addressed if the directive is not used?

Directive: %define api.value.union.name name

    Purpose:
       Where is 'name' used? The text references 'id' but nowhere 
references 'name'. Plase provide some verbiage that specifies where 
'name' is  used.The implication is that 'name' is a selection amongst 
several choices, see %define api.push-pull kind. Since there is only one 
choice wouldn't it be better to not have 'name'. However, if this thing 
is supposed to be an identifier, t hen the syntax given in 3.7.14 
requires that this directive be %define api.value.union.name "name".

Directive: %define parse.assert

    Accepted Values: Boolean
       The format of the define does not allow for a value. It should be 
"%define parse.asser value", see 3.7.14 %define Summary.


Directive: %define parse.trace

    Accepted Values: Boolean
       The format of the define does not allow for a value. It should be 
"%define parse.asser value", see 3.7.14 %define Summary.