projects/dil: trunk/src/dil/parser/Parser.d comparison

comparison trunk/src/dil/parser/Parser.d @ 798:c24be8d4f6ab

Added documentation comments.

author	Aziz K?ksal <aziz.koeksal@gmail.com>
date	Sat, 01 Mar 2008 02:53:06 +0100
parents	c1d5cfd7aa44
children	cb8040538772

comparison

equal deleted inserted replaced

-:cf2ad5df025c
+:c24be8d4f6ab
 InfoManager infoMan;
 ParserError[] errors;
 ImportDeclaration[] imports; /// ImportDeclarations in the source text.
-// Attributes are evaluated in the parsing phase.
+/// Attributes are evaluated in the parsing phase.
-// Will probably be moved to class SemanticPass1.
+/// TODO: will be removed. SemanticPass1 takes care of attributes.
 LinkageType linkageType;
-Protection protection;
+Protection protection; /// ditto
-StorageClass storageClass;
+StorageClass storageClass; /// ditto
-uint alignSize = DEFAULT_ALIGN_SIZE;
+uint alignSize = DEFAULT_ALIGN_SIZE; /// ditto
-private alias TOK T;
+private alias TOK T; /// Used often in this class.
 private alias TypeNode Type;
-/++
+/// Constructs a Parser object.
-Construct a Parser object.
+/// Params:
-Params:
+///   text     = the UTF-8 source code.
-text     = the UTF-8 source code.
+///   infoMan  = used for collecting error messages.
-infoMan  = used for collecting error messages.
-+/
 this(SourceText srcText, InfoManager infoMan = null)
 {
 this.infoMan = infoMan;
 lexer = new Lexer(srcText, infoMan);
 }
 // Members related to the method try_().
 uint trying; /// Greater than 0 if Parser is in try_().
 uint errorCount; /// Used to track nr. of errors while being in try_().
-/++
+/// This method executes the delegate parseMethod and when an error occurred
-This method executes the delegate parseMethod and when an error occurred
+/// the state of the lexer and parser are restored.
-the state of the lexer and parser are restored.
+/// Returns: the return value of parseMethod().
-+/
 ReturnType try_(ReturnType)(ReturnType delegate() parseMethod, out bool success)
 {
 // Save members.
 auto oldToken     = this.token;
 auto oldPrevToken = this.prevToken;
 lexer.peek(next);
 while (next.isWhitespace) // Skip whitespace
 return next.kind;
 }
-/// Returns the token kind of the token after 'next'.
+/// Returns the token kind of the token that comes after t.
-TOK peekAfter(ref Token* next)
+TOK peekAfter(ref Token* t)
 {
-assert(next !is null);
+assert(t !is null);
 do
-lexer.peek(next);
+lexer.peek(t);
-while (next.isWhitespace) // Skip whitespace
+while (t.isWhitespace) // Skip whitespace
-return next.kind;
+return t.kind;
 }
 /// Consumes the current token if its kind matches k and returns true.
 bool consumed()(TOK k) // Templatized, so it's inlined.
 {
 while (consumed(T.Dot))
 require(T.Semicolon);
 return set(new ModuleDeclaration(moduleFQN), begin);
 }
-/++
+/// Parses DeclarationDefinitions until the end of file is hit.
-Parse DeclarationDefinitions until the end of file is hit.
+/// $(PRE
-DeclDefs:
+/// DeclDefs :=
-DeclDef
+///     DeclDef
-DeclDefs
+///     DeclDefs
-+/
+/// )
 Declaration[] parseDeclarationDefinitions()
 {
 Declaration[] decls;
 while (token.kind != T.EOF)
 decls ~= parseDeclarationDefinition();
 return decls;
 }
-/++
+/// Parse the body of a template, class, interface, struct or union.
-Parse the body of a template, class, interface, struct or union.
+/// $(PRE
-DeclDefsBlock:
+/// DeclDefsBlock :=
-{ }
+///     { }
-{ DeclDefs }
+///     { DeclDefs }
-+/
+/// )
 CompoundDeclaration parseDeclarationDefinitionsBody()
 {
 // Save attributes.
 auto linkageType  = this.linkageType;
 auto protection   = this.protection;
 this.storageClass = storageClass;
 return decls;
 }
+/// Parses a DeclarationDefinition.
 Declaration parseDeclarationDefinition()
 out(decl)
 { assert(isNodeSet(decl)); }
 body
 {
 assert(!isNodeSet(decl));
 set(decl, begin);
 return decl;
 }
-/++
+/// Parses a DeclarationsBlock.
-DeclarationsBlock:
+/// $(PRE
-: DeclDefs
+/// DeclarationsBlock :=
-{ }
+///     : DeclDefs
-{ DeclDefs }
+///     { }
-DeclDef
+///     { DeclDefs }
-+/
+///     DeclDef
+/// )
 Declaration parseDeclarationsBlock(/+bool noColon = false+/)
 {
 Declaration d;
 switch (token.kind)
 {
 // Declaration parseDeclarationsBlockNoColon()
 // {
 //   return parseDeclarationsBlock(true);
 // }
-/++
+/// Parses either a VariableDeclaration or a FunctionDeclaration.
-Parses either a VariableDeclaration or a FunctionDeclaration.
+/// Params:
-Params:
+///   stc = previously parsed storage classes
-stc = previously parsed storage classes
+///   protection = previously parsed protection attribute
-protection = previously parsed protection attribute
+///   linkType = previously parsed linkage type
-linkType = previously parsed linkage type
+///   testAutoDeclaration = whether to check for an AutoDeclaration
-testAutoDeclaration = whether to check for an AutoDeclaration
+///   optionalParameterList = a hint for how to parse C-style function pointers
-optionalParameterList = a hint for how to parse C-style function pointers
-+/
 Declaration parseVariableOrFunction(StorageClass stc = StorageClass.None,
 Protection protection = Protection.None,
 LinkageType linkType = LinkageType.None,
 bool testAutoDeclaration = false,
 bool optionalParameterList = true)
 d.setLinkageType(linkType);
 d.setProtection(protection);
 return set(d, begin);
 }
+/// Parses a variable initializer.
 Expression parseInitializer()
 {
 if (token.kind == T.Void)
 {
 auto begin = token;
 require(T.RParen);
 set(type, begin);
 return type;
 }
-/++
+/// Parses a MixinDeclaration or MixinStatement.
-TemplateMixin:
+/// $(PRE
-mixin ( AssignExpression ) ;
+/// TemplateMixin :=
-mixin TemplateIdentifier ;
+///         mixin ( AssignExpression ) ;
-mixin TemplateIdentifier MixinIdentifier ;
+///         mixin TemplateIdentifier ;
-mixin TemplateIdentifier !( TemplateArguments ) ;
+///         mixin TemplateIdentifier MixinIdentifier ;
-mixin TemplateIdentifier !( TemplateArguments ) MixinIdentifier ;
+///         mixin TemplateIdentifier !( TemplateArguments ) ;
-+/
+///         mixin TemplateIdentifier !( TemplateArguments ) MixinIdentifier ;
+/// )
 Class parseMixin(Class)()
 {
 static assert(is(Class == MixinDeclaration) || is(Class == MixinStatement));
 skip(T.Mixin);
 statements ~= parseStatement();
 require(T.RBrace);
 return set(statements, begin);
 }
+/// Parses a Statement.
 Statement parseStatement()
 {
 auto begin = token;
 Statement s;
 Declaration d;
 assert(s !is null);
 set(s, begin);
 return s;
 }
-/++
+/// $(PRE
-ScopeStatement:
+/// Parses a ScopeStatement.
-NoScopeStatement
+/// ScopeStatement :=
-+/
+///     NoScopeStatement
+/// )
 Statement parseScopeStatement()
 {
 return new ScopeStatement(parseNoScopeStatement());
 }
-/++
+/// $(PRE
-NoScopeStatement:
+/// NoScopeStatement :=
-NonEmptyStatement
+///     NonEmptyStatement
-BlockStatement
+///     BlockStatement
-BlockStatement:
+/// BlockStatement :=
-{ }
+///     { }
-{ StatementList }
+///     { StatementList }
-+/
+/// )
 Statement parseNoScopeStatement()
 {
 auto begin = token;
 Statement s;
 if (consumed(T.LBrace))
 else
 s = parseStatement();
 return s;
 }
-/++
+/// $(PRE
-NoScopeOrEmptyStatement:
+/// NoScopeOrEmptyStatement :=
-;
+///     ;
-NoScopeStatement
+///     NoScopeStatement
-+/
+/// )
 Statement parseNoScopeOrEmptyStatement()
 {
 if (consumed(T.Semicolon))
 return set(new EmptyStatement(), this.prevToken);
 else
 /+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 |                         Assembler parsing methods                         |
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+/
+/// Parses an AsmBlockStatement.
 Statement parseAsmBlockStatement()
 {
 skip(T.Asm);
 require(T.LBrace);
 auto ss = new CompoundStatement;
 /+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 |                        Expression parsing methods                         |
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+/
+/// Parses an Expression.
 Expression parseExpression()
 {
 alias parseAssignExpression parseNext;
 auto begin = token;
 auto e = parseNext();
 assert(e !is null);
 set(e, begin);
 return e;
 }
-/++
+/// $(PRE
-IdentifierExpression:
+/// IdentifierExpression :=
-Identifier
+///         Identifier
-TemplateInstance
+///         TemplateInstance
-TemplateInstance:
+/// TemplateInstance :=
-Identifier !( TemplateArguments )
+///         Identifier !( TemplateArguments )
-+/
+/// )
 Expression parseIdentifierExpression()
 {
 auto begin = token;
 auto ident = requireIdentifier(MSG.ExpectedAnIdentifier);
 Expression e;
 ctorArguments = parseArguments();
 return set(new NewExpression(/*e, */newArguments, type, ctorArguments), begin);
 }
+/// Parses a Type.
 Type parseType()
 {
 return parseBasicType2(parseBasicType());
 }
 set(t, begin);
 }
 assert(0);
 }
+/// Returns true if the token after the closing parenthesis
+/// is of kind tok.
 bool tokenAfterParenIs(TOK tok)
 {
 // We count nested parentheses tokens because template types
 // may appear inside parameter lists. E.g.: (int x, Foo!(int) y)
 assert(token.kind == T.LParen);
 }
 }
 return next.kind == tok;
 }
-/// Parse the C-style array types after the declarator.
+/// Parse the array types after the declarator (C-style.) E.g.: int a[]
 Type parseDeclaratorSuffix(Type lhsType)
 {
 // The Type chain should be as follows:
 // int[3]* Identifier [][32]
 //   <- <-             ->  -.
 error(token, MSG.ExpectedDeclaratorIdentifier, token.srcText);
 return t;
 }
-/++
+/// Parses a list of AssignExpressions.
-Parse a list of AssignExpressions.
+/// $(PRE
-ExpressionList:
+/// ExpressionList :=
-AssignExpression
+///   AssignExpression
-AssignExpression , ExpressionList
+///   AssignExpression , ExpressionList
-+/
+/// )
 Expression[] parseExpressionList()
 {
 Expression[] expressions;
 do
 expressions ~= parseAssignExpression();
 while(consumed(T.Comma))
 return expressions;
 }
-/++
+/// Parses a list of Arguments.
-Arguments:
+/// $(PRE
-( )
+/// Arguments :=
-( ExpressionList )
+///   ( )
-+/
+///   ( ExpressionList )
+/// )
 Expression[] parseArguments()
 {
 skip(T.LParen);
 Expression[] args;
 if (token.kind != T.RParen)
 args = parseExpressionList();
 require(T.RParen);
 return args;
 }
+/// Parses a ParameterList.
 Parameters parseParameterList()
 out(params)
 {
 if (params.length > 1)
 foreach (param; params.items[0..$-1])
 error(token, MSG.ExpectedTemplateParameters);
 return set(tparams, begin);
 }
 } // version(D2)
+/// Parses template parameters.
 void parseTemplateParameterList_(TemplateParameters tparams)
 {
 do
 {
 auto paramBegin = token;
 tparams ~= set(tp, paramBegin);
 } while (consumed(T.Comma))
 }
-void expected(TOK tok)
+alias require expected;
-{
-if (token.kind != tok)
+/// Requires a token of kind tok.
-error(MID.ExpectedButFound, Token.toString(tok), token.srcText);
-}
 void require(TOK tok)
 {
 if (token.kind == tok)
 nT();
 else
 error(MID.ExpectedButFound, Token.toString(tok), token.srcText);
 }
+/// Requires the next token to be of kind tok.
 void requireNext(TOK tok)
 {
 nT();
 require(tok);
 }
+/// Optionally parses an identifier.
+/// Returns: null or the identifier.
 Identifier* optionalIdentifier()
 {
 Identifier* id;
 if (token.kind == T.Identifier)
 (id = token.ident), skip(T.Identifier);
 else
 error(MID.ExpectedButFound, "Identifier", token.srcText);
 return id;
 }
+/// Reports an error if the current token is not an identifier.
 /// Params:
-///   errorMsg = an error that has no message ID yet.
+///   errorMsg = the error message to be used.
+/// Returns: null or the identifier.
 Identifier* requireIdentifier(char[] errorMsg)
 {
 Identifier* id;
 if (token.kind == T.Identifier)
 (id = token.ident), skip(T.Identifier);
 else
 error(token, errorMsg, token.srcText);
 return id;
 }
+/// Reports an error if the current token is not an identifier.
+/// Params:
+///   mid = the error message ID to be used.
+/// Returns: null or the identifier.
 Identifier* requireIdentifier(MID mid)
 {
 Identifier* id;
 if (token.kind == T.Identifier)
 (id = token.ident), skip(T.Identifier);
 else
 error(mid, token.srcText);
 return id;
 }
+/// Reports an error if the current token is not an identifier.
+/// Returns: null or the token.
 Token* requireId()
-{
-if (token.kind == T.Identifier)
-{
-auto id = token;
-nT();
-return id;
-}
-else
-error(MID.ExpectedButFound, "Identifier", token.srcText);
-return null;
-}
-Token* requireIdToken(char[] errorMsg)
 {
 Token* idtok;
 if (token.kind == T.Identifier)
 (idtok = token), skip(T.Identifier);
 else
+error(MID.ExpectedButFound, "Identifier", token.srcText);
+return idtok;
+}
+Token* requireIdToken(char[] errorMsg)
+{
+Token* idtok;
+if (token.kind == T.Identifier)
+(idtok = token), skip(T.Identifier);
+else
+{
 error(token, errorMsg, token.srcText);
+idtok = lexer.insertEmptyTokenBefore(token);
+this.prevToken = idtok;
+}
 return idtok;
 }
 /// Returns true if the string str has an invalid UTF-8 sequence.
 bool checkString(Token* begin, string str)
 if (utf8Seq.length)
 error(begin, MSG.InvalidUTF8SequenceInString, utf8Seq);
 return utf8Seq.length != 0;
 }
-/// Reports an error that has no message ID yet.
+/// Forwards error parameters.
 void error(Token* token, char[] formatMsg, ...)
 {
 error_(token, formatMsg, _arguments, _argptr);
 }
+/// ditto
 void error(MID mid, ...)
 {
 error_(this.token, GetMsg(mid), _arguments, _argptr);
 }
+/// Creates an error report and appends it to a list.
+/// Params:
+///   token = used to get the location of where the error is.
+///   formatMsg = the compiler error message.
 void error_(Token* token, char[] formatMsg, TypeInfo[] _arguments, Arg _argptr)
 {
 if (trying)
 {
 ++errorCount;

Mercurial > projects > dil

comparison trunk/src/dil/parser/Parser.d @ 798:c24be8d4f6ab