Crate syn_solidity

syn-solidity

syn-powered parser for Solidity-like TokenStreams.

The parsed root element is the File, which contains a list of Items. Items also support outer attributes, as shown below.

Design

This parser is specifically designed for Rust procedural macros. It aims to mimic the behavior of the official Solidity compiler (Solc) when it comes to parsing valid Solidity code. This means that all valid Solidity code, as recognized by Solc v0.5.*¹ and above, will also be recognized and parsed correctly by syn-solidity.

However, syn-solidity is more permissive and lenient compared to the official Solidity compiler and grammar specifications. Some examples of code patterns that are valid in syn-solidity but not in the official compiler include:

• identifiers are Rust identifiers (syn::Ident), and as such cannot contain the dollar sign ($), but can contain unicode characters
• trailing punctuation, like commas (,) in function arguments or enums definitions
• certain variable and function attributes in certain contexts, like internal functions or functions with implementations ({ ... }) in interfaces
• parameter storage locations in item definitions, like uint256[] memory in a struct or error definition
• the tuple type (T, U, ..) is allowed wherever a type is expected, and can optionally be preceded by the tuple keyword. This is the same as ethers.js’s Human-Readable ABI

This lenient behavior is intentionally designed to facilitate usage within procedural macros, and to reduce general code complexity in the parser and AST.

Known limitations

This parser is limited to only valid Rust tokens, meaning that certain Solidity constructs are not supported. Some examples include, but are not limited to:

• dollar signs ($) inside of identifiers
• single quote strings
• hex and unicode string literal prefixes. Literal prefixes are reserved in Rust edition 2021 and above.
• "\uXXXX" unicode escapes. Rust uses "\u{XXXX}" for unicode codepoints
• invalid nested block comments. For example, /*/*/ does not parse.

For the most part, you can copy-paste Solidity code and expect it to parse correctly most of the time. You can see a few examples of Solidity code that parses correctly (after some very light patching) in the tests directory.

Examples

Basic usage:

use quote::quote;
use syn_solidity::{Expr, File, Item, Lit, Stmt};

// Create a Solidity `TokenStream`
let tokens = quote! {
    /// @name HelloWorld
    /// @notice A hello world example in Solidity.
    contract HelloWorld {
        /// @notice Returns the string "Hello, World!".
        function helloWorld() external pure returns (string memory) {
            return "Hello, World!";
        }
    }
};

// Parse the tokens into a `File`
let ast: File = syn_solidity::parse2(tokens)?;

let items: &[Item] = &ast.items;
let Some(Item::Contract(contract)) = items.first() else {
    unreachable!()
};
assert_eq!(contract.name, "HelloWorld");
assert_eq!(contract.attrs.len(), 2); // doc comments

let body: &[Item] = &contract.body;
let Some(Item::Function(function)) = body.first() else {
    unreachable!()
};
assert_eq!(function.attrs.len(), 1); // doc comment
assert_eq!(function.name.as_ref().unwrap(), "helloWorld");
assert!(function.parameters.is_empty()); // ()
assert_eq!(function.attributes.len(), 2); // external pure
assert!(function.returns.is_some());

let Some([Stmt::Return(ret)]) = function.body() else {
    unreachable!()
};
let Some(Expr::Lit(Lit::Str(s))) = &ret.expr else {
    unreachable!()
};
assert_eq!(s.value(), "Hello, World!");

---

1. Older versions may still parse successfully, but this is not guaranteed. ↩

Re-exports

• pub use spanned::Spanned;
• pub use visit::Visit;
  visit
• pub use visit_mut::VisitMut;
  visit-mut

Modules

• kw
  Solidity keywords.
• spanned
  Helper trait and methods to manipulate syntax tree nodes’ spans.
• visitvisit
  Syntax tree traversal to walk a shared borrow of a syntax tree.
• visit_mutvisit-mut
  Syntax tree traversal to mutate an exclusive borrow of a syntax tree in place.

Macros

• sol_path
  Create a SolPath from a list of identifiers.

Structs

• ArgList
  A list of named or unnamed arguments: { foo: 42, bar: 64 } or (42, 64).
• AssemblyFlags
  A list of flags of an assembly statement.
• Block
  A curly-braced block of statements: { ... }.
• CatchClause
  A catch clause of a StmtTry: catch { ... }.
• EventParameter
  An event parameter.
• ExprArray
  An array literal expression: [a, b, c, d].
• ExprBinary
  A binary operation: a + b, a += b.
• ExprCall
  A function call expression: foo(42) or foo({ bar: 42 }).
• ExprCallOptions
  Function call options: foo.bar{ value: 1, gas: 2 }.
• ExprDelete
  A unary delete expression: delete vector.
• ExprIndex
  A square bracketed indexing expression: vector[2].
• ExprMember
  Access of a named member: obj.k.
• ExprNew
  A new expression: new Contract.
• ExprPayable
  A payable expression: payable(address(0x...)).
• ExprPostfix
  A postfix unary expression: foo++.
• ExprTernary
  A ternary (AKA conditional) expression: foo ? bar : baz.
• ExprTuple
  A tuple expression: (a, b, c, d).
• ExprTypeCall
  A type() expression: type(uint256)
• ExprUnary
  A unary operation: !x, -x.
• File
  A Solidity file. The root of the AST.
• FunctionAttributes
  A list of unique function attributes. Used in ItemFunction.
• HexStr
  A hex string.
• ImportAlias
  An import alias.
• ImportAliases
  A list of import aliases: { Foo as Bar, Baz } from "foo.sol".
• ImportDirective
  An import directive: import "foo.sol";.
• ImportGlob
  A glob import directive: * as Foo from "foo.sol".
• ImportPlain
  A plain import directive: import "foo.sol" as Foo;.
• Inheritance
  A list of inheritance specifiers of an ItemContract: is ERC20("Token", "TKN"), Ownable.
• ItemContract
  A contract, abstract contract, interface, or library definition: contract Foo is Bar("foo"), Baz { ... }.
• ItemEnum
  An enum definition: enum Foo { A, B, C }.
• ItemError
  An error definition: error Foo(uint256 a, uint256 b);.
• ItemEvent
• ItemFunction
  A function, constructor, fallback, receive, or modifier definition: function helloWorld() external pure returns(string memory);.
• ItemStruct
  A struct definition: struct Foo { uint256 bar; }.
• ItemUdt
  A user-defined value type definition: type Foo is uint256;.
• LitDenominated
• LitHexStr
• LitStr
• LitUnicodeStr
• Modifier
  A modifier invocation, or an inheritance specifier.
• NamedArg
  A named argument in an argument list: foo: uint256(42).
• NamedArgList
  A named argument list: { foo: uint256(42), bar: true }.
• Override
  The override attribute.
• Parameters
  A list of VariableDeclarations, separated by P.
• PragmaDirective
  A pragma directive: pragma solidity ^0.8.0;
• Returns
  The returns attribute of a function.
• SolIdent
  A Solidity identifier.
• SolPath
  A list of identifiers, separated by dots.
• StmtAssembly
  An assembly block, with optional flags: assembly "evmasm" { ... }.
• StmtBreak
  A break statement: break;.
• StmtContinue
  A continue statement: continue;.
• StmtDoWhile
  A do-while statement: do { ... } while (condition);.
• StmtEmit
  An emit statement: emit FooBar(42);.
• StmtExpr
  An expression with a trailing semicolon.
• StmtFor
  A for statement: for (uint256 i; i < 42; ++i) { ... }.
• StmtIf
  An if statement with an optional else block: if (expr) { ... } else { ... }.
• StmtReturn
  A return statement: return 42;.
• StmtRevert
  A revert statement: revert("error");.
• StmtTry
  A try statement: try fooBar(42) catch { ... }.
• StmtVarDecl
  A variable declaration statement: uint256 foo = 42;.
• StmtWhile
  A while statement: while (i < 42) { ... }.
• TypeArray
  An array type.
• TypeFunction
  A function type: function() returns (string memory).
• TypeMapping
  A mapping type: mapping(uint key => string value)
• TypeTuple
  A tuple type.
• UncheckedBlock
  An unchecked block: unchecked { ... }.
• UnicodeStr
  A unicode string.
• UsingDirective
  A using directive: using { A, B.mul as * } for uint256 global;.
• UsingListItem
• VarDeclTuple
  A declaration of variables in a tuple: (,,uint256 foo,string memory bar).
• VariableAttributes
  A list of unique variable attributes.
• VariableDeclaration
  A variable declaration: string memory hello.
• VariableDefinition
• Variant
  An enum variant.
• WalrusToken
  Represents the walrus operator :=.
• YulBlock
  A Yul block contains YulStmt between curly braces.
• YulCaseBranch
  Represents a non-default case of a Yul switch statement.
• YulFnCall
  Yul function call.
• YulFor
  Yul for loop e.g for {let i := 0} lt(i,10) {i := add(i,1)} {mstore(i,7)}.
• YulFunctionDef
  Yul function definition: function f() -> a, b { ... }.
• YulIdent
  A Yul identifier.
• YulIf
  A Yul if statement: if lt(a, b) { sstore(0, 1) }.
• YulPath
  In inline assembly, only dot-less identifiers can be declared, but dotted paths can reference declarations made outside the assembly block.
• YulReturns
  The return attribute of a Yul function definition.
• YulSwitch
  A Yul switch statement can consist of only a default-case or one or more non-default cases optionally followed by a default-case.
• YulSwitchDefault
  Represents the default case of a Yul switch statement.
• YulVarAssign
  Yul variable assignment. x := 0 or x, y := foo(). Assigning values to multiple variables requires a function call.
• YulVarDecl
  Declares Yul variables, which may or may not have initial values. E.x. let x := 0 let x let x, y := foo() let x, y, z

Enums

• ArgListImpl
  A list of either unnamed or named arguments.
• BinOp
  A binary operator: +, +=, &.
• ContractKind
  The kind of contract.
• Expr
  An expression.
• ForInitStmt
  A for statement initializer.
• FunctionAttribute
  A function attribute.
• FunctionBody
  The body of a function.
• FunctionKind
  The kind of function.
• ImportPath
  The path of an import directive.
• Item
  An AST item. A more expanded version of a Solidity source unit.
• Lit
  A Solidity literal such as a string or integer or boolean.
• LitNumber
  An integer or fixed-point number literal: 1 or 1.0.
• Mutability
  A mutability attribute.
• PostUnOp
  Postfix unary operators.
• PragmaTokens
• Stmt
  A statement, usually ending in a semicolon.
• Storage
  A storage location.
• SubDenomination
  A sub-denomination suffix for a number literal.
• Type
  A type name.
• UnOp
  Unary operators.
• UserDefinableOperator
  A user-definable operator: +, *, |, etc.
• UsingList
• UsingType
• VarDeclDecl
  The declaration of the variable(s) in a variable declaration statement.
• VariableAttribute
  A variable attribute.
• Visibility
  A visibility attribute.
• YulEVMBuiltIn
  Representation of an EVM builtin opcode.
• YulExpr
  A Yul expression.
• YulFnType
  What type of function is called.
• YulStmt
  A Yul statement.

Functions

• parse
  Parse a Solidity proc_macro::TokenStream into a File.
• parse2
  Parse a Solidity proc_macro2::TokenStream into a File.

Type Aliases

• FieldList
  A list of semicolon-separated VariableDeclarations.
• ParameterList
  A list of comma-separated VariableDeclarations.