diff --git a/libsolidity/AST.h b/libsolidity/AST.h index a55f58c16..db6637aea 100644 --- a/libsolidity/AST.h +++ b/libsolidity/AST.h @@ -40,6 +40,10 @@ namespace solidity class ASTVisitor; + +/// The root (abstract) class of the AST inheritance tree. +/// It is possible to traverse all direct and indirect children of an AST node by calling +/// accept, providing an ASTVisitor. class ASTNode: private boost::noncopyable { public: @@ -55,6 +59,7 @@ public: element->accept(_visitor); } + /// Returns the source code location of this node. Location const& getLocation() const { return m_location; } /// Creates a @ref TypeError exception and decorates it with the location of the node and @@ -62,6 +67,7 @@ public: TypeError createTypeError(std::string const& _description); ///@{ + ///@name equality operators /// Equality relies on the fact that nodes cannot be copied. bool operator==(ASTNode const& _other) const { return this == &_other; } bool operator!=(ASTNode const& _other) const { return !operator==(_other); } @@ -71,18 +77,23 @@ private: Location m_location; }; +/// Abstract AST class for a declaration (contract, function, struct, variable). class Declaration: public ASTNode { public: Declaration(Location const& _location, ASTPointer const& _name): ASTNode(_location), m_name(_name) {} + /// Returns the declared name. const ASTString& getName() const { return *m_name; } private: ASTPointer m_name; }; +/// Definition of a contract. This is the only AST nodes where child nodes are not visited in +/// document order. It first visits all struct declarations, then all variable declarations and +/// finally all function declarations. class ContractDefinition: public Declaration { public: @@ -122,9 +133,9 @@ private: std::vector> m_members; }; -/// Used as function parameter list and return list +/// Parameter list, used as function parameter list and return list. /// None of the parameters is allowed to contain mappings (not even recursively -/// inside structs) +/// inside structs), but (@todo) this is not yet enforced. class ParameterList: public ASTNode { public: @@ -167,6 +178,8 @@ private: ASTPointer m_body; }; +/// Declaration of a variable. This can be used in various places, e.g. in function parameter +/// lists, struct definitions and even function bodys. class VariableDeclaration: public Declaration { public: @@ -186,22 +199,26 @@ public: private: ASTPointer m_typeName; ///< can be empty ("var") - std::shared_ptr m_type; + std::shared_ptr m_type; ///< derived type, initially empty }; -/// types +/// Types /// @{ +/// Abstract base class of a type name, can be any built-in or user-defined type. class TypeName: public ASTNode { public: explicit TypeName(Location const& _location): ASTNode(_location) {} virtual void accept(ASTVisitor& _visitor) override; + /// Retrieve the element of the type hierarchy this node refers to. Can return an empty shared + /// pointer until the types have been resolved using the @ref NameAndTypeResolver. virtual std::shared_ptr toType() = 0; }; -/// any pre-defined type that is not a mapping +/// Any pre-defined type name represented by a single keyword, i.e. it excludes mappings, +/// contracts, functions, etc. class ElementaryTypeName: public TypeName { public: @@ -210,12 +227,14 @@ public: virtual void accept(ASTVisitor& _visitor) override; virtual std::shared_ptr toType() override { return Type::fromElementaryTypeName(m_type); } - Token::Value getType() const { return m_type; } + Token::Value getTypeName() const { return m_type; } private: Token::Value m_type; }; +/// Name referring to a user-defined type (i.e. a struct). +/// @todo some changes are necessary if this is also used to refer to contract types later class UserDefinedTypeName: public TypeName { public: @@ -234,6 +253,7 @@ private: StructDefinition* m_referencedStruct; }; +/// A mapping type. Its source form is "mapping('keyType' => 'valueType')" class Mapping: public TypeName { public: @@ -253,6 +273,8 @@ private: /// Statements /// @{ + +/// Abstract base class for statements. class Statement: public ASTNode { public: @@ -260,16 +282,17 @@ public: virtual void accept(ASTVisitor& _visitor) override; //! Check all type requirements, throws exception if some requirement is not met. - //! For expressions, this also returns the inferred type of the expression. For other - //! statements, returns the empty pointer. + //! This includes checking that operators are applicable to their arguments but also that + //! the number of function call arguments matches the number of formal parameters and so forth. virtual void checkTypeRequirements() = 0; protected: - //! Check that the inferred type for _expression is _expectedType or at least implicitly - //! convertible to _expectedType. If not, throw exception. + //! Helper function, check that the inferred type for @a _expression is @a _expectedType or at + //! least implicitly convertible to @a _expectedType. If not, throw exception. void expectType(Expression& _expression, Type const& _expectedType); }; +/// Brace-enclosed block containing zero or more statements. class Block: public Statement { public: @@ -283,6 +306,8 @@ private: std::vector> m_statements; }; +/// If-statement with an optional "else" part. Note that "else if" is modeled by having a new +/// if-statement as the false (else) body. class IfStatement: public Statement { public: @@ -299,6 +324,8 @@ private: ASTPointer m_falseBody; //< "else" part, optional }; +/// Statement in which a break statement is legal. +/// @todo actually check this requirement. class BreakableStatement: public Statement { public: @@ -349,9 +376,13 @@ public: private: ASTPointer m_expression; //< value to return, optional - ParameterList* m_returnParameters; //< extracted from the function declaration + /// Pointer to the parameter list of the function, filled by the @ref NameAndTypeResolver. + ParameterList* m_returnParameters; }; +/// Definition of a variable as a statement inside a function. It requires a type name (which can +/// also be "var") but the actual assignment can be missing. +/// Examples: var a = 2; uint256 a; class VariableDefinition: public Statement { public: @@ -363,13 +394,16 @@ public: private: ASTPointer m_variable; - ASTPointer m_value; ///< can be missing + ASTPointer m_value; ///< the assigned value, can be missing }; +/// An expression, i.e. something that has a value (which can also be of type "void" in case +/// of function calls). class Expression: public Statement { public: Expression(Location const& _location): Statement(_location) {} + std::shared_ptr const& getType() const { return m_type; } protected: @@ -382,6 +416,8 @@ protected: /// Expressions /// @{ +/// Assignment, can also be a compound assignment. +/// Examples: (a = 7 + 8) or (a *= 2) class Assignment: public Expression { public: @@ -402,6 +438,8 @@ private: ASTPointer m_rightHandSide; }; +/// Operation involving a unary operator, pre- or postfix. +/// Examples: ++i, delete x or !true class UnaryOperation: public Expression { public: @@ -421,6 +459,8 @@ private: bool m_isPrefix; }; +/// Operation involving a binary operator. +/// Examples: 1 + 2, true && false or 1 <= 4 class BinaryOperation: public Expression { public: @@ -451,6 +491,7 @@ public: Expression(_location), m_expression(_expression), m_arguments(_arguments) {} virtual void accept(ASTVisitor& _visitor) override; virtual void checkTypeRequirements() override; + /// Returns true if this is not an actual function call, but an explicit type conversion /// or constructor call. bool isTypeConversion() const; @@ -460,6 +501,7 @@ private: std::vector> m_arguments; }; +/// Access to a member of an object. Example: x.name class MemberAccess: public Expression { public: @@ -475,6 +517,7 @@ private: ASTPointer m_memberName; }; +/// Index access to an array. Example: a[2] class IndexAccess: public Expression { public: @@ -489,12 +532,15 @@ private: ASTPointer m_index; }; +/// Primary expression, i.e. an expression that do not be divided any further like a literal or +/// a variable reference. class PrimaryExpression: public Expression { public: PrimaryExpression(Location const& _location): Expression(_location) {} }; +/// An identifier, i.e. a reference to a declaration by name like a variable or function. class Identifier: public PrimaryExpression { public: @@ -504,6 +550,7 @@ public: virtual void checkTypeRequirements() override; ASTString const& getName() const { return *m_name; } + void setReferencedDeclaration(Declaration& _referencedDeclaration) { m_referencedDeclaration = &_referencedDeclaration; } Declaration* getReferencedDeclaration() { return m_referencedDeclaration; } @@ -514,6 +561,9 @@ private: Declaration* m_referencedDeclaration; }; +/// An elementary type name expression is used in expressions like "a = uint32(2)" to change the +/// type of an expression explicitly. Here, "uint32" is the elementary type name expression and +/// "uint32(2)" is a @ref FunctionCall. class ElementaryTypeNameExpression: public PrimaryExpression { public: @@ -528,6 +578,7 @@ private: Token::Value m_typeToken; }; +/// A literal string or number. @see Type::literalToBigEndian is used to actually parse its value. class Literal: public PrimaryExpression { public: @@ -537,6 +588,7 @@ public: virtual void checkTypeRequirements() override; Token::Value getToken() const { return m_token; } + /// @returns the non-parsed value of the literal ASTString const& getValue() const { return *m_value; } private: diff --git a/libsolidity/ASTPrinter.cpp b/libsolidity/ASTPrinter.cpp index 44245ed46..b933e7caa 100644 --- a/libsolidity/ASTPrinter.cpp +++ b/libsolidity/ASTPrinter.cpp @@ -87,7 +87,7 @@ bool ASTPrinter::visit(TypeName& _node) bool ASTPrinter::visit(ElementaryTypeName& _node) { - writeLine(std::string("ElementaryTypeName ") + Token::toString(_node.getType())); + writeLine(std::string("ElementaryTypeName ") + Token::toString(_node.getTypeName())); printSourcePart(_node); return goDeeper(); } diff --git a/libsolidity/Compiler.h b/libsolidity/Compiler.h index bddc4bef3..ac5e10ec9 100644 --- a/libsolidity/Compiler.h +++ b/libsolidity/Compiler.h @@ -110,8 +110,8 @@ private: /// Appends code to remove dirty higher order bits in case of an implicit promotion to a wider type. void cleanHigherOrderBitsIfNeeded(Type const& _typeOnStack, Type const& _targetType); - /// Append code for various operator types - /// @{ + ///@{ + ///@name Append code for various operator types void appendAndOrOperatorCode(BinaryOperation& _binaryOperation); void appendCompareOperatorCode(Token::Value _operator, Type const& _type); void appendOrdinaryBinaryOperatorCode(Token::Value _operator, Type const& _type); diff --git a/libsolidity/Parser.h b/libsolidity/Parser.h index 14338dc28..eabc22746 100644 --- a/libsolidity/Parser.h +++ b/libsolidity/Parser.h @@ -44,8 +44,8 @@ private: /// End position of the current token int getEndPosition() const; - /// Parsing functions for the AST nodes - /// @{ + ///@{ + ///@name Parsing functions for the AST nodes ASTPointer parseContractDefinition(); ASTPointer parseFunctionDefinition(bool _isPublic); ASTPointer parseStructDefinition(); @@ -64,16 +64,17 @@ private: ASTPointer parseLeftHandSideExpression(); ASTPointer parsePrimaryExpression(); std::vector> parseFunctionCallArguments(); - /// @} + ///@} + + ///@{ + ///@name Helper functions - /// Helper functions - /// @{ /// If current token value is not _value, throw exception otherwise advance token. void expectToken(Token::Value _value); Token::Value expectAssignmentOperator(); ASTPointer expectIdentifierToken(); ASTPointer getLiteralAndAdvance(); - /// @} + ///@} /// Creates a @ref ParserError exception and annotates it with the current position and the /// given @a _description. diff --git a/libsolidity/Scanner.h b/libsolidity/Scanner.h index adae10dca..0cf87f6ad 100644 --- a/libsolidity/Scanner.h +++ b/libsolidity/Scanner.h @@ -81,12 +81,13 @@ public: char advanceAndGet(); char rollback(size_t _amount); + ///@{ + ///@name Error printing helper functions /// Functions that help pretty-printing parse errors /// Do only use in error cases, they are quite expensive. - /// @{ std::string getLineAtPosition(int _position) const; std::tuple translatePositionToLineColumn(int _position) const; - /// @} + ///@} private: std::string m_source; @@ -119,29 +120,31 @@ public: /// Returns the next token and advances input. Token::Value next(); - /// Information about the current token - /// @{ + ///@{ + ///@name Information about the current token /// Returns the current token Token::Value getCurrentToken() { return m_current_token.token; } Location getCurrentLocation() const { return m_current_token.location; } const std::string& getCurrentLiteral() const { return m_current_token.literal; } - /// @} + ///@} + + ///@{ + ///@name Information about the next token - /// Information about the next token - /// @{ /// Returns the next token without advancing input. Token::Value peekNextToken() const { return m_next_token.token; } Location peekLocation() const { return m_next_token.location; } const std::string& peekLiteral() const { return m_next_token.literal; } - /// @} + ///@} - /// Functions that help pretty-printing parse errors. + ///@{ + ///@name Error printing helper functions + /// Functions that help pretty-printing parse errors /// Do only use in error cases, they are quite expensive. - /// @{ std::string getLineAtPosition(int _position) const { return m_source.getLineAtPosition(_position); } std::tuple translatePositionToLineColumn(int _position) const { return m_source.translatePositionToLineColumn(_position); } - /// @} + ///@} private: // Used for the current and look-ahead token. @@ -152,13 +155,13 @@ private: std::string literal; }; - /// Literal buffer support - /// @{ + ///@{ + ///@name Literal buffer support inline void startNewLiteral() { m_next_token.literal.clear(); } inline void addLiteralChar(char c) { m_next_token.literal.push_back(c); } inline void dropLiteral() { m_next_token.literal.clear(); } inline void addLiteralCharAndAdvance() { addLiteralChar(m_char); advance(); } - /// @} + ///@} bool advance() { m_char = m_source.advanceAndGet(); return !m_source.isPastEndOfInput(); } void rollback(int _amount) { m_char = m_source.rollback(_amount); } @@ -169,9 +172,10 @@ private: bool scanHexNumber(char& o_scannedNumber, int _expectedLength); - // Scans a single JavaScript token. + /// Scans a single JavaScript token. void scanToken(); + /// Skips all whitespace and @returns true if something was skipped. bool skipWhitespace(); Token::Value skipSingleLineComment(); Token::Value skipMultiLineComment();