1351 – Discrepancies in the language specification

In the process of writing my own lexer and parser of the D programming language, I have found plenty of discrepancies in the language specification and I have some suggestions. Here we go:
.) module.html
The DeclDef rule has many subrules which should link to the page where they're defined.
	DebugSpecification // Replace with ConditionalDeclaration
	VersionSpecification // ditto
.) declaration.html
Introduce a new rule "IntegralType" which will contain only the integral types of D (bool - void from BasicType). This is useful for a subrule in PrimaryExpression (see below.)
	IntegralType:
		bool
		byte
		...
		void
	BasicType:
		IntegralType
		.IdentifierList
		IdentifierList
		Typeof
		Typeof . IdentifierList
	BasicType2:
		[ Expression .. Expression ] // Slice expression is missing.
	Declarator:
		() Declarator // Has a trailing space. Should be "( Declarator )".
		Identifier DeclaratorSuffixes
		() Declarator DeclaratorSuffixes // Should be "( Declarator ) DeclaratorSuffixes"
	DeclaratorSuffix:
		[ Expression .. Expression ] // Slice expression is missing.
.) attribute.html
Attribute:
	synchronized // missing
.) expression.html
EqualExpression:
	ShiftExpression
	ShiftExpression == ShiftExpression
	ShiftExpression != ShiftExpression
	ShiftExpression is ShiftExpression // This is covered in IdentityExpression already.
	ShiftExpression !is ShiftExpression // ditto
UnaryExpression:
	NewExpression
	NewAnonClassExpression // Should be contained by NewExpression.
NewExpression:
	NewArguments ClassArguments BaseClasslistopt { DeclDefs } // Should be removed and replaced by NewAnonClassExpression.
PostfixExpression:
	PostfixExpression . Identifier // Identifier should be replaced by IdentifierList so that TemplateInstance is covered as well.
PrimaryExpression:
	Identifier // Should be replaced by IdentifierList
	.Identifier // Should be replaced by ". IdentifierList"
	BasicType . Identifier // BasicType should be replaced by IntegralType as suggested above.
	typeof ( Expression ) // missing
	typeof ( Expression ) . IdentifierList // missing
KeyExpression:
	ConditionalExpression // Should be AssignExpression.
ValueExpression:
	ConditionalExpression // Should be AssignExpression.
FunctionLiteral // missing colon
	function Typeopt ( ParameterList )opt FunctionBody // Allows for literals like "function int {}". Is this legal?
IsExpression:
	is ( Type Identifier ) // Doesn't allow for "is (int x[] == int[])"
	is ( Type Identifier : TypeSpecialization )
	is ( Type Identifier == TypeSpecialization )
TypeSpecialization:
	return // missing
.) class.html
Protection:
	private
	package
	public
	export // inheriting by export doesn't make any sense.
.) enum.html
EnumDeclaration:
	enum EnumBody // Allows for "enum;"
.) template.html
TemplateDeclaration:
	template TemplateIdentifier ( TemplateParameterList )
		{ DeclDefs } // Should be on the above line.
TemplateParameterList // Has no colon.

Forgot the following:
.) statement.html#SwitchStatement
Quote: "The case expressions, ExpressionList, are a comma separated list of expressions."
"expressions" should be <a href="...">AssignExpression</a>s.

Reply to d-bugmail@puremagic.com,
> http://d.puremagic.com/issues/show_bug.cgi?id=1351
> 
> ------- Comment #1 from aziz.kerim@gmail.com 2007年07月20日 15:36 -------
> Forgot the following:
> 
> .) statement.html#SwitchStatement
> Quote: "The case expressions, ExpressionList, are a comma separated
> list of
> expressions."
> "expressions" should be <a href="...">AssignExpression</a>s.
* All non terminals in the grammar should be links to there definitions.
* There should be a page that is just the grammar rules (and it should NOT 
be maintained by hand)

One more thing:
AutoDeclaration:
 StorageClasses Identifier = AssignExpression ; // doesn't allow for multiple declarations
Currently you can write things like:
auto bla = 2, foo = "abc";
'bla' will be of type int and foo will be of type char[]. Maybe this needs to be changed because it's inconsistent with the syntax of non-auto declarations:
int bla = 2, foo = "abc"; // error because foo is of type int.
When we have:
auto id1 = init(), id2, id3; // id2 and id3 should be of type typeof(id1).
What do you think about this issue?

In http://www.digitalmars.com/d/expression.html#CharacterLiteral you write:
"Character literals are single characters and resolve to one of type char, wchar, or dchar. If the literal is a \u escape sequence, it resolves to type wchar. If the literal is a \U escape sequence, it resolves to type dchar. Otherwise, it resolves to the type with the smallest size it will fit into."
Which type does a character literal with an HTML entity have (e.g. '\&xyz;')?
Please clarify if this correct:
uint c;
// statements ...
if (c < 128)
 // c is char
else if(c <= 0xFFFF)
 // c is wchar
else
 // c is dchar

(In reply to comment #4)
> "[...]
> Otherwise, it resolves to the type with the smallest size it will fit into."
> 
> Which type does a character literal with an HTML entity have (e.g. '\&xyz;')?
The last sentence you've quoted makes it seem clear to me.
> Please clarify if this correct:
> 
> uint c;
> // statements ...
> if (c < 128)
> // c is char
If c is a uint, then c is a uint. But what you seem to mean by it seems right to me.

(In reply to comment #0)
> FunctionLiteral // missing colon
> function Typeopt ( ParameterList )opt FunctionBody // Allows for
> literals like "function int {}". Is this legal?
If it weren't meant to be, surely there wouldn't be the statement
"If omitted it defaults to the empty argument list ()."
in the paragraph immediately below that BNF.
But it does seem to be a mistake that that paragraph talks of ArgumentList instead of ParameterList.

(In reply to comment #5)
> (In reply to comment #4)
> > "[...]
> > Otherwise, it resolves to the type with the smallest size it will fit into."
> > 
> > Which type does a character literal with an HTML entity have (e.g. '\&xyz;')?
> 
> The last sentence you've quoted makes it seem clear to me.
It actually does, but I think HTML entities have to be explicitly mentioned as well. Because:
auto foo = '\&';
pragma(msg, typeof(foo).stringof); // prints dchar instead of char (which an ampersand should fit into)
> If c is a uint, then c is a uint. But what you seem to mean by it seems right
> to me.
Yes, what I mean is that c contains a decoded Unicode character and the if statements are there to determine the type of the character literal.

(In reply to comment #6)
> (In reply to comment #0)
> > FunctionLiteral // missing colon
> > function Typeopt ( ParameterList )opt FunctionBody // Allows for
> > literals like "function int {}". Is this legal?
> 
> If it weren't meant to be, surely there wouldn't be the statement
> 
> "If omitted it defaults to the empty argument list ()."
Ok, but DMD doesn't allow you to declare such delegate or function literals:
auto bla = delegate void {}; // Error: found '{' when expecting '(' (other errors omitted)
Seems to be a bug in the compiler or the specification.
> But it does seem to be a mistake that that paragraph talks of ArgumentList
> instead of ParameterList.
Yep, ArgumentList should be ParameterList in that paragraph.

Regarding http://www.digitalmars.com/d/statement.html#ForeachStatement :
You talk twice about NoScopeNonEmptyStatement but it should be ScopeStatement as defined in the BNF rule.

Regarding http://www.digitalmars.com/d/declaration.html :
D 2.0 supports type constructors, so a new rule ConstType should be added to BasicType:
BasicType:
 // other rules ...
 ConstType
ConstType:
 const ( Type )
 invariant ( Type )

Created attachment 661 [details] 
adds links, fixes productions, adjusts some formatting
No claims to infallibility. In particular, someone had better check PowExpression, as I believe it was in the wrong place and I moved it, but I'm not so confident about it.
Aziz: for DeclaratorSuffixes, the [ exp .. exp ] syntax is not currently supported by dmd (v2 at least), and it probably never was, and I don't think it should be. (of course I don't think DeclaratorSuffixes should exist at all, except for the parameter part, since it's a kludge for c-style types)
I haven't touched NewExpression, Protection, or SwitchStatement (at least I don't think I did)
IsExpression: I hate D. How about we just pretend this one doesn't exist?
I think everything else either is already fixed or is fixed by this patch

http://www.dsource.org/projects/phobos/changeset/2140 

I'm pretty sure PowExpression is still wrong.
with 
PowExpression:
 UnaryExpression
 UnaryExpression ^^ PowExpression
UnaryExpression:
 etc
the code -2 ^^ 2 should have the precedence (-2) ^^ 2,
but this is not the case in dmd
assert( -2 ^^ 2 == -(2 ^^ 2)); //passes
assert( -2 ^^ 2 == (-2) ^^ 2); //fails
more evidence, parse.c, parseUnaryExp, line 5823 or thereabouts:
// ^^ is right associative and has higher precedence than the unary operators

and some of the keywords in lex.html seem to have gotten misaligned

The keywords all look aligned to me.

(In reply to comment #15)
> The keywords all look aligned to me.
Curious. immutable, nothrow, pure, and shared are misaligned in the generated html - at least when I build the docs

http://www.dsource.org/projects/phobos/changeset/2144
You were right about the PowExpression.