solang_parser/
pt.rs

1// SPDX-License-Identifier: Apache-2.0
2
3//! Solidity parse tree data structures.
4//!
5//! See also the [Solidity documentation][sol].
6//!
7//! [sol]: https://docs.soliditylang.org/en/latest/grammar.html
8
9// backwards compatibility re-export
10#[doc(hidden)]
11pub use crate::helpers::{CodeLocation, OptionalCodeLocation};
12
13#[cfg(feature = "pt-serde")]
14use serde::{Deserialize, Serialize};
15
16/// A code location.
17#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
18#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
19pub enum Loc {
20    /// Builtin
21    Builtin,
22    /// Command line
23    CommandLine,
24    /// Implicit
25    Implicit,
26    /// Codegen
27    Codegen,
28    /// The file number, start offset and end offset in bytes of the source file.
29    File(usize, usize, usize),
30}
31
32impl Default for Loc {
33    fn default() -> Self {
34        Self::File(0, 0, 0)
35    }
36}
37
38#[inline(never)]
39#[cold]
40#[track_caller]
41fn not_a_file() -> ! {
42    panic!("location is not a file")
43}
44
45impl Loc {
46    /// Returns this location's beginning range.
47    #[inline]
48    pub fn begin_range(&self) -> Self {
49        match self {
50            Loc::File(file_no, start, _) => Loc::File(*file_no, *start, *start),
51            loc => *loc,
52        }
53    }
54
55    /// Returns this location's end range.
56    #[inline]
57    pub fn end_range(&self) -> Self {
58        match self {
59            Loc::File(file_no, _, end) => Loc::File(*file_no, *end, *end),
60            loc => *loc,
61        }
62    }
63
64    /// Returns this location's file number.
65    ///
66    /// # Panics
67    ///
68    /// If this location is not a file.
69    #[track_caller]
70    #[inline]
71    pub fn file_no(&self) -> usize {
72        match self {
73            Loc::File(file_no, _, _) => *file_no,
74            _ => not_a_file(),
75        }
76    }
77
78    /// Returns this location's file number if it is a file, otherwise `None`.
79    #[inline]
80    pub fn try_file_no(&self) -> Option<usize> {
81        match self {
82            Loc::File(file_no, _, _) => Some(*file_no),
83            _ => None,
84        }
85    }
86
87    /// Returns this location's start.
88    ///
89    /// # Panics
90    ///
91    /// If this location is not a file.
92    #[track_caller]
93    #[inline]
94    pub fn start(&self) -> usize {
95        match self {
96            Loc::File(_, start, _) => *start,
97            _ => not_a_file(),
98        }
99    }
100
101    /// Returns this location's end.
102    ///
103    /// # Panics
104    ///
105    /// If this location is not a file.
106    #[track_caller]
107    #[inline]
108    pub fn end(&self) -> usize {
109        match self {
110            Loc::File(_, _, end) => *end,
111            _ => not_a_file(),
112        }
113    }
114
115    /// Returns this location's end.
116    /// The returned endpoint is not part of the range.
117    /// This is used when a half-open range is needed.
118    ///
119    /// # Panics
120    ///
121    /// If this location is not a file.
122    #[track_caller]
123    #[inline]
124    pub fn exclusive_end(&self) -> usize {
125        self.end() + 1
126    }
127
128    /// Replaces this location's start with `other`'s.
129    ///
130    /// # Panics
131    ///
132    /// If this location is not a file.
133    #[track_caller]
134    #[inline]
135    pub fn use_start_from(&mut self, other: &Loc) {
136        match (self, other) {
137            (Loc::File(_, start, _), Loc::File(_, other_start, _)) => {
138                *start = *other_start;
139            }
140            _ => not_a_file(),
141        }
142    }
143
144    /// Replaces this location's end with `other`'s.
145    ///
146    /// # Panics
147    ///
148    /// If this location is not a file.
149    #[track_caller]
150    #[inline]
151    pub fn use_end_from(&mut self, other: &Loc) {
152        match (self, other) {
153            (Loc::File(_, _, end), Loc::File(_, _, other_end)) => {
154                *end = *other_end;
155            }
156            _ => not_a_file(),
157        }
158    }
159
160    /// See [`Loc::use_start_from`].
161    ///
162    /// # Panics
163    ///
164    /// If this location is not a file.
165    #[track_caller]
166    #[inline]
167    pub fn with_start_from(mut self, other: &Self) -> Self {
168        self.use_start_from(other);
169        self
170    }
171
172    /// See [`Loc::use_end_from`].
173    ///
174    /// # Panics
175    ///
176    /// If this location is not a file.
177    #[track_caller]
178    #[inline]
179    pub fn with_end_from(mut self, other: &Self) -> Self {
180        self.use_end_from(other);
181        self
182    }
183
184    /// Creates a new `Loc::File` by replacing `start`.
185    ///
186    /// # Panics
187    ///
188    /// If this location is not a file.
189    #[track_caller]
190    #[inline]
191    pub fn with_start(self, start: usize) -> Self {
192        match self {
193            Self::File(no, _, end) => Self::File(no, start, end),
194            _ => not_a_file(),
195        }
196    }
197
198    /// Creates a new `Loc::File` by replacing `end`.
199    ///
200    /// # Panics
201    ///
202    /// If this location is not a file.
203    #[track_caller]
204    #[inline]
205    pub fn with_end(self, end: usize) -> Self {
206        match self {
207            Self::File(no, start, _) => Self::File(no, start, end),
208            _ => not_a_file(),
209        }
210    }
211
212    /// Returns this location's range.
213    ///
214    /// # Panics
215    ///
216    /// If this location is not a file.
217    #[track_caller]
218    #[inline]
219    pub fn range(self) -> std::ops::Range<usize> {
220        match self {
221            Self::File(_, start, end) => start..end,
222            _ => not_a_file(),
223        }
224    }
225
226    /// Performs the union of two locations
227    pub fn union(&mut self, other: &Self) {
228        match (self, other) {
229            (Self::File(r_file, r_start, r_end), Self::File(l_file, l_start, l_end)) => {
230                assert_eq!(r_file, l_file, "cannot perform union in different files");
231                *r_start = std::cmp::min(*r_start, *l_start);
232                *r_end = std::cmp::max(*r_end, *l_end);
233            }
234
235            _ => unimplemented!("cannot perform union in non File Loc"),
236        }
237    }
238}
239
240/// An identifier.
241///
242/// `<name>`
243#[derive(Debug, PartialEq, Eq, Clone)]
244#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
245pub struct Identifier {
246    /// The code location.
247    pub loc: Loc,
248    /// The identifier string.
249    pub name: String,
250}
251
252impl Identifier {
253    /// Creates a new identifier.
254    pub fn new(s: impl Into<String>) -> Self {
255        Self {
256            loc: Loc::default(),
257            name: s.into(),
258        }
259    }
260}
261
262/// A qualified identifier.
263///
264/// `<identifiers>.*`
265#[derive(Debug, PartialEq, Eq, Clone)]
266#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
267pub struct IdentifierPath {
268    /// The code location.
269    pub loc: Loc,
270    /// The list of identifiers.
271    pub identifiers: Vec<Identifier>,
272}
273
274/// A comment or [doc comment][natspec].
275///
276/// [natspec]: https://docs.soliditylang.org/en/latest/natspec-format.html
277#[derive(Debug, PartialEq, Eq, Clone)]
278#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
279pub enum Comment {
280    /// A line comment.
281    ///
282    /// `// line comment`
283    Line(Loc, String),
284
285    /// A block doc comment.
286    ///
287    /// ` /* block comment */ `
288    Block(Loc, String),
289
290    /// A line doc comment.
291    ///
292    /// `/// line doc comment`
293    DocLine(Loc, String),
294
295    /// A block doc comment.
296    ///
297    /// ```text
298    /// /**
299    ///  * block doc comment
300    ///  */
301    /// ```
302    DocBlock(Loc, String),
303}
304
305impl Comment {
306    /// Returns the comment's value.
307    #[inline]
308    pub const fn value(&self) -> &String {
309        match self {
310            Self::Line(_, s) | Self::Block(_, s) | Self::DocLine(_, s) | Self::DocBlock(_, s) => s,
311        }
312    }
313
314    /// Returns whether this is a doc comment.
315    #[inline]
316    pub const fn is_doc(&self) -> bool {
317        matches!(self, Self::DocLine(..) | Self::DocBlock(..))
318    }
319
320    /// Returns whether this is a line comment.
321    #[inline]
322    pub const fn is_line(&self) -> bool {
323        matches!(self, Self::Line(..) | Self::DocLine(..))
324    }
325
326    /// Returns whether this is a block comment.
327    #[inline]
328    pub const fn is_block(&self) -> bool {
329        !self.is_line()
330    }
331}
332
333/// The source unit of the parse tree.
334///
335/// Contains all of the parse tree's parts in a vector.
336#[derive(Debug, PartialEq, Eq, Clone)]
337#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
338pub struct SourceUnit(pub Vec<SourceUnitPart>);
339
340/// A parse tree part.
341#[derive(Debug, PartialEq, Eq, Clone)]
342#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
343pub enum SourceUnitPart {
344    /// A pragma directive.
345    ///
346    /// `pragma <1> <2>;`
347    ///
348    /// `1` and `2` are `None` only if an error occurred during parsing.
349    PragmaDirective(Box<PragmaDirective>),
350
351    /// An import directive.
352    ImportDirective(Import),
353
354    /// A contract definition.
355    ContractDefinition(Box<ContractDefinition>),
356
357    /// An enum definition.
358    EnumDefinition(Box<EnumDefinition>),
359
360    /// A struct definition.
361    StructDefinition(Box<StructDefinition>),
362
363    /// An event definition.
364    EventDefinition(Box<EventDefinition>),
365
366    /// An error definition.
367    ErrorDefinition(Box<ErrorDefinition>),
368
369    /// A function definition.
370    FunctionDefinition(Box<FunctionDefinition>),
371
372    /// A variable definition.
373    VariableDefinition(Box<VariableDefinition>),
374
375    /// A type definition.
376    TypeDefinition(Box<TypeDefinition>),
377
378    /// An annotation.
379    Annotation(Box<Annotation>),
380
381    /// A `using` directive.
382    Using(Box<Using>),
383
384    /// A stray semicolon.
385    StraySemicolon(Loc),
386}
387
388/// An import statement.
389#[derive(Debug, PartialEq, Eq, Clone)]
390#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
391pub enum Import {
392    /// `import <0>;`
393    Plain(ImportPath, Loc),
394
395    /// `import * as <1> from <0>;`
396    ///
397    /// or
398    ///
399    /// `import <0> as <1>;`
400    GlobalSymbol(ImportPath, Identifier, Loc),
401
402    /// `import { <<1.0> [as <1.1>]>,* } from <0>;`
403    Rename(ImportPath, Vec<(Identifier, Option<Identifier>)>, Loc),
404}
405
406/// An import statement.
407#[derive(Debug, PartialEq, Eq, Clone)]
408#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
409pub enum ImportPath {
410    /// "foo.sol"
411    Filename(StringLiteral),
412    /// std.stub (experimental Solidity feature)
413    Path(IdentifierPath),
414}
415
416impl Import {
417    /// Returns the import string.
418    #[inline]
419    pub const fn literal(&self) -> Option<&StringLiteral> {
420        match self {
421            Self::Plain(ImportPath::Filename(literal), _)
422            | Self::GlobalSymbol(ImportPath::Filename(literal), _, _)
423            | Self::Rename(ImportPath::Filename(literal), _, _) => Some(literal),
424            _ => None,
425        }
426    }
427}
428
429/// Type alias for a list of function parameters.
430pub type ParameterList = Vec<(Loc, Option<Parameter>)>;
431
432/// A type.
433#[derive(Debug, PartialEq, Eq, Clone)]
434#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
435pub enum Type {
436    /// `address`
437    Address,
438
439    /// `address payable`
440    AddressPayable,
441
442    /// `payable`
443    ///
444    /// Only used as a cast.
445    Payable,
446
447    /// `bool`
448    Bool,
449
450    /// `string`
451    String,
452
453    /// `int<n>`
454    Int(u16),
455
456    /// `uint<n>`
457    Uint(u16),
458
459    /// `bytes<n>`
460    Bytes(u8),
461
462    /// `fixed`
463    Rational,
464
465    /// `bytes`
466    DynamicBytes,
467
468    /// `mapping(<key> [key_name] => <value> [value_name])`
469    Mapping {
470        /// The code location.
471        loc: Loc,
472        /// The key expression.
473        ///
474        /// This is only allowed to be an elementary type or a user defined type.
475        key: Box<Expression>,
476        /// The optional key identifier.
477        key_name: Option<Identifier>,
478        /// The value expression.
479        value: Box<Expression>,
480        /// The optional value identifier.
481        value_name: Option<Identifier>,
482    },
483
484    /// `function (<params>) <attributes> [returns]`
485    Function {
486        /// The list of parameters.
487        params: ParameterList,
488        /// The list of attributes.
489        attributes: Vec<FunctionAttribute>,
490        /// The optional list of return parameters.
491        returns: Option<(ParameterList, Vec<FunctionAttribute>)>,
492    },
493}
494
495/// Dynamic type location.
496#[derive(Debug, PartialEq, Eq, Clone)]
497#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
498pub enum StorageLocation {
499    /// `memory`
500    Memory(Loc),
501
502    /// `storage`
503    Storage(Loc),
504
505    /// `calldata`
506    Calldata(Loc),
507}
508
509/// A variable declaration.
510///
511/// `<ty> [storage] <name>`
512#[derive(Debug, PartialEq, Eq, Clone)]
513#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
514pub struct VariableDeclaration {
515    /// The code location.
516    pub loc: Loc,
517    /// The type.
518    pub ty: Expression,
519    /// The optional memory location.
520    pub storage: Option<StorageLocation>,
521    /// The identifier.
522    ///
523    /// This field is `None` only if an error occurred during parsing.
524    pub name: Option<Identifier>,
525}
526
527/// A struct definition.
528///
529/// `struct <name> { <fields>;* }`
530#[derive(Debug, PartialEq, Eq, Clone)]
531#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
532pub struct StructDefinition {
533    /// The code location.
534    pub loc: Loc,
535    /// The identifier.
536    ///
537    /// This field is `None` only if an error occurred during parsing.
538    pub name: Option<Identifier>,
539    /// The list of fields.
540    pub fields: Vec<VariableDeclaration>,
541}
542
543/// A contract part.
544#[derive(Debug, PartialEq, Eq, Clone)]
545#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
546pub enum ContractPart {
547    /// A struct definition.
548    StructDefinition(Box<StructDefinition>),
549
550    /// An event definition.
551    EventDefinition(Box<EventDefinition>),
552
553    /// An enum definition.
554    EnumDefinition(Box<EnumDefinition>),
555
556    /// An error definition.
557    ErrorDefinition(Box<ErrorDefinition>),
558
559    /// A variable definition.
560    VariableDefinition(Box<VariableDefinition>),
561
562    /// A function definition.
563    FunctionDefinition(Box<FunctionDefinition>),
564
565    /// A type definition.
566    TypeDefinition(Box<TypeDefinition>),
567
568    /// A definition.
569    Annotation(Box<Annotation>),
570
571    /// A `using` directive.
572    Using(Box<Using>),
573
574    /// A stray semicolon.
575    StraySemicolon(Loc),
576}
577
578/// A pragma directive
579#[derive(Debug, PartialEq, Eq, Clone)]
580#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
581pub enum PragmaDirective {
582    /// pragma a b;
583    Identifier(Loc, Option<Identifier>, Option<Identifier>),
584    /// pragma a "b";
585    StringLiteral(Loc, Identifier, StringLiteral),
586    /// pragma version =0.5.16;
587    Version(Loc, Identifier, Vec<VersionComparator>),
588}
589
590/// A `version` list
591#[derive(Debug, PartialEq, Eq, Clone)]
592#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
593pub enum VersionComparator {
594    /// 0.8.22
595    Plain {
596        /// The code location.
597        loc: Loc,
598        /// List of versions: major, minor, patch. minor and patch are optional
599        version: Vec<String>,
600    },
601    /// =0.5.16
602    Operator {
603        /// The code location.
604        loc: Loc,
605        /// Semver comparison operator
606        op: VersionOp,
607        /// version number
608        version: Vec<String>,
609    },
610    /// foo || bar
611    Or {
612        /// The code location.
613        loc: Loc,
614        /// left part
615        left: Box<VersionComparator>,
616        /// right part
617        right: Box<VersionComparator>,
618    },
619    /// 0.7.0 - 0.8.22
620    Range {
621        /// The code location.
622        loc: Loc,
623        /// start of range
624        from: Vec<String>,
625        /// end of range
626        to: Vec<String>,
627    },
628}
629
630/// Comparison operator
631#[derive(Debug, PartialEq, Eq, Copy, Clone)]
632#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
633pub enum VersionOp {
634    /// `=`
635    Exact,
636    /// `>`
637    Greater,
638    /// `>=`
639    GreaterEq,
640    /// `<`
641    Less,
642    /// `<=`
643    LessEq,
644    /// `~`
645    Tilde,
646    /// `^`
647    Caret,
648    /// `*`
649    Wildcard,
650}
651
652/// A `using` list. See [Using].
653#[derive(Debug, PartialEq, Eq, Clone)]
654#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
655pub enum UsingList {
656    /// A single identifier path.
657    Library(IdentifierPath),
658
659    /// List of using functions.
660    ///
661    /// `{ <<identifier path> [ as <operator> ]>,* }`
662    Functions(Vec<UsingFunction>),
663
664    /// An error occurred during parsing.
665    Error,
666}
667
668/// A `using` function. See [UsingList].
669///
670/// `<path> [ as <oper> ]`
671#[derive(Debug, PartialEq, Eq, Clone)]
672#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
673pub struct UsingFunction {
674    /// The code location.
675    pub loc: Loc,
676    /// The identifier path.
677    pub path: IdentifierPath,
678    /// The optional user-defined operator.
679    pub oper: Option<UserDefinedOperator>,
680}
681
682/// A user-defined operator.
683///
684/// See also the [Solidity blog post][ref] on user-defined operators.
685///
686/// [ref]: https://blog.soliditylang.org/2023/02/22/user-defined-operators/
687#[derive(Clone, Copy, Debug, PartialEq, Eq)]
688#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
689pub enum UserDefinedOperator {
690    /// `&`
691    BitwiseAnd,
692    /// `~`
693    ///
694    BitwiseNot,
695    /// `-`
696    ///
697    /// Note that this is the same as `Subtract`, and that it is currently not being parsed.
698    Negate,
699    /// `|`
700    BitwiseOr,
701    /// `^`
702    BitwiseXor,
703    /// `+`
704    Add,
705    /// `/`
706    Divide,
707    /// `%`
708    Modulo,
709    /// `*`
710    Multiply,
711    /// `-`
712    Subtract,
713    /// `==`
714    Equal,
715    /// `>`
716    More,
717    /// `>=`
718    MoreEqual,
719    /// `<`
720    Less,
721    /// `<=`
722    LessEqual,
723    /// `!=`
724    NotEqual,
725}
726
727impl UserDefinedOperator {
728    /// Returns the number of arguments needed for this operator's operation.
729    #[inline]
730    pub const fn args(&self) -> usize {
731        match self {
732            UserDefinedOperator::BitwiseNot | UserDefinedOperator::Negate => 1,
733            _ => 2,
734        }
735    }
736
737    /// Returns whether `self` is a unary operator.
738    #[inline]
739    pub const fn is_unary(&self) -> bool {
740        matches!(self, Self::BitwiseNot | Self::Negate)
741    }
742
743    /// Returns whether `self` is a binary operator.
744    #[inline]
745    pub const fn is_binary(&self) -> bool {
746        !self.is_unary()
747    }
748
749    /// Returns whether `self` is a bitwise operator.
750    #[inline]
751    pub const fn is_bitwise(&self) -> bool {
752        matches!(
753            self,
754            Self::BitwiseAnd | Self::BitwiseOr | Self::BitwiseXor | Self::BitwiseNot
755        )
756    }
757
758    /// Returns whether `self` is an arithmetic operator.
759    #[inline]
760    pub const fn is_arithmetic(&self) -> bool {
761        matches!(
762            self,
763            Self::Add | Self::Subtract | Self::Multiply | Self::Divide | Self::Modulo
764        )
765    }
766
767    /// Returns whether this is a comparison operator.
768    #[inline]
769    pub const fn is_comparison(&self) -> bool {
770        matches!(
771            self,
772            Self::Equal
773                | Self::NotEqual
774                | Self::Less
775                | Self::LessEqual
776                | Self::More
777                | Self::MoreEqual
778        )
779    }
780}
781
782/// A `using` directive.
783///
784/// Can occur within contracts and libraries and at the file level.
785///
786/// `using <list> for <type | '*'> [global];`
787#[derive(Debug, PartialEq, Eq, Clone)]
788#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
789pub struct Using {
790    /// The code location.
791    pub loc: Loc,
792    /// The list of `using` functions or a single identifier path.
793    pub list: UsingList,
794    /// The type.
795    ///
796    /// This field is `None` if an error occurred or the specified type is `*`.
797    pub ty: Option<Expression>,
798    /// The optional `global` identifier.
799    pub global: Option<Identifier>,
800}
801
802/// The contract type.
803#[derive(Debug, PartialEq, Eq, Clone)]
804#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
805pub enum ContractTy {
806    /// `abstract contract`
807    Abstract(Loc),
808
809    /// `contract`
810    Contract(Loc),
811
812    /// `interface`
813    Interface(Loc),
814
815    /// `library`
816    Library(Loc),
817}
818
819/// A function modifier invocation (see [FunctionAttribute])
820/// or a contract inheritance specifier (see [ContractDefinition]).
821///
822/// Both have the same semantics:
823///
824/// `<name>[(<args>,*)]`
825#[derive(Debug, PartialEq, Eq, Clone)]
826#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
827pub struct Base {
828    /// The code location.
829    pub loc: Loc,
830    /// The identifier path.
831    pub name: IdentifierPath,
832    /// The optional arguments.
833    pub args: Option<Vec<Expression>>,
834}
835
836/// A contract definition.
837///
838/// `<ty> <name> [<base>,*] { <parts>,* }`
839#[derive(Debug, PartialEq, Eq, Clone)]
840#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
841pub struct ContractDefinition {
842    /// The code location.
843    pub loc: Loc,
844    /// The contract type.
845    pub ty: ContractTy,
846    /// The identifier.
847    ///
848    /// This field is `None` only if an error occurred during parsing.
849    pub name: Option<Identifier>,
850    /// The list of inheritance specifiers.
851    pub base: Vec<Base>,
852    /// The list of contract parts.
853    pub parts: Vec<ContractPart>,
854}
855
856/// An event parameter.
857///
858/// `<ty> [indexed] [name]`
859#[derive(Debug, PartialEq, Eq, Clone)]
860#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
861pub struct EventParameter {
862    /// The code location.
863    pub loc: Loc,
864    /// The type.
865    pub ty: Expression,
866    /// Whether this parameter is indexed.
867    pub indexed: bool,
868    /// The optional identifier.
869    pub name: Option<Identifier>,
870}
871
872/// An event definition.
873///
874/// `event <name>(<fields>,*) [anonymous];`
875#[derive(Debug, PartialEq, Eq, Clone)]
876#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
877pub struct EventDefinition {
878    /// The code location.
879    pub loc: Loc,
880    /// The identifier.
881    ///
882    /// This field is `None` only if an error occurred during parsing.
883    pub name: Option<Identifier>,
884    /// The list of event parameters.
885    pub fields: Vec<EventParameter>,
886    /// Whether this event is anonymous.
887    pub anonymous: bool,
888}
889
890/// An error parameter.
891///
892/// `<ty> [name]`
893#[derive(Debug, PartialEq, Eq, Clone)]
894#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
895pub struct ErrorParameter {
896    /// The code location.
897    pub loc: Loc,
898    /// The type.
899    pub ty: Expression,
900    /// The optional identifier.
901    pub name: Option<Identifier>,
902}
903
904/// An error definition.
905///
906/// `error <name> (<fields>,*);`
907#[derive(Debug, PartialEq, Eq, Clone)]
908#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
909pub struct ErrorDefinition {
910    /// The code location.
911    pub loc: Loc,
912    /// The `error` keyword.
913    pub keyword: Expression,
914    /// The identifier.
915    ///
916    /// This field is `None` only if an error occurred during parsing.
917    pub name: Option<Identifier>,
918    /// The list of error parameters.
919    pub fields: Vec<ErrorParameter>,
920}
921
922/// An enum definition.
923///
924/// `enum <name> { <values>,* }`
925#[derive(Debug, PartialEq, Eq, Clone)]
926#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
927pub struct EnumDefinition {
928    /// The code location.
929    pub loc: Loc,
930    /// The identifier.
931    ///
932    /// This field is `None` only if an error occurred during parsing.
933    pub name: Option<Identifier>,
934    /// The list of values.
935    ///
936    /// This field contains `None` only if an error occurred during parsing.
937    pub values: Vec<Option<Identifier>>,
938}
939
940/// A variable attribute.
941#[derive(Debug, PartialEq, Eq, Clone)]
942#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
943#[repr(u8)] // for cmp; order of variants is important
944pub enum VariableAttribute {
945    /// The visibility.
946    ///
947    /// Only used for storage variables.
948    Visibility(Visibility),
949
950    /// `constant`
951    Constant(Loc),
952
953    /// `immutable`
954    Immutable(Loc),
955
956    /// `ovveride(<1>,*)`
957    Override(Loc, Vec<IdentifierPath>),
958}
959
960/// A variable definition.
961///
962/// `<ty> <attrs>* <name> [= <initializer>]`
963#[derive(Debug, PartialEq, Eq, Clone)]
964#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
965pub struct VariableDefinition {
966    /// The code location.
967    pub loc: Loc,
968    /// The type.
969    pub ty: Expression,
970    /// The list of variable attributes.
971    pub attrs: Vec<VariableAttribute>,
972    /// The identifier.
973    ///
974    /// This field is `None` only if an error occurred during parsing.
975    pub name: Option<Identifier>,
976    /// The optional initializer.
977    pub initializer: Option<Expression>,
978}
979
980/// A user type definition.
981///
982/// `type <name> is <ty>;`
983#[derive(Debug, PartialEq, Eq, Clone)]
984#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
985pub struct TypeDefinition {
986    /// The code location.
987    pub loc: Loc,
988    /// The user-defined type name.
989    pub name: Identifier,
990    /// The type expression.
991    pub ty: Expression,
992}
993
994/// An annotation.
995///
996/// `@<id>(<value>)`
997#[derive(Debug, PartialEq, Eq, Clone)]
998#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
999pub struct Annotation {
1000    /// The code location.
1001    pub loc: Loc,
1002    /// The identifier.
1003    pub id: Identifier,
1004    /// The value.
1005    pub value: Option<Expression>,
1006}
1007
1008/// A string literal.
1009///
1010/// `[unicode]"<string>"`
1011#[derive(Debug, PartialEq, Eq, Clone)]
1012#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
1013pub struct StringLiteral {
1014    /// The code location.
1015    pub loc: Loc,
1016    /// Whether this is a unicode string.
1017    pub unicode: bool,
1018    /// The string literal.
1019    ///
1020    /// Does not contain the quotes or the `unicode` prefix.
1021    pub string: String,
1022}
1023
1024/// A hex literal.
1025///
1026/// `hex"<literal>"`
1027#[derive(Debug, PartialEq, Eq, Clone)]
1028#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
1029pub struct HexLiteral {
1030    /// The code location.
1031    pub loc: Loc,
1032    /// The hex literal.
1033    ///
1034    /// Contains the `hex` prefix.
1035    pub hex: String,
1036}
1037
1038/// A named argument.
1039///
1040/// `<name>: <expr>`
1041#[derive(Debug, PartialEq, Eq, Clone)]
1042#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
1043pub struct NamedArgument {
1044    /// The code location.
1045    pub loc: Loc,
1046    /// The identifier.
1047    pub name: Identifier,
1048    /// The value.
1049    pub expr: Expression,
1050}
1051
1052/// An expression.
1053#[derive(Debug, PartialEq, Eq, Clone)]
1054#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
1055pub enum Expression {
1056    /// `<1>++`
1057    PostIncrement(Loc, Box<Expression>),
1058    /// `<1>--`
1059    PostDecrement(Loc, Box<Expression>),
1060    /// `new <1>`
1061    New(Loc, Box<Expression>),
1062    /// `<1>\[ [2] \]`
1063    ArraySubscript(Loc, Box<Expression>, Option<Box<Expression>>),
1064    /// `<1>\[ [2] : [3] \]`
1065    ArraySlice(
1066        Loc,
1067        Box<Expression>,
1068        Option<Box<Expression>>,
1069        Option<Box<Expression>>,
1070    ),
1071    /// `(<1>)`
1072    Parenthesis(Loc, Box<Expression>),
1073    /// `<1>.<2>`
1074    MemberAccess(Loc, Box<Expression>, Identifier),
1075    /// `<1>(<2>,*)`
1076    FunctionCall(Loc, Box<Expression>, Vec<Expression>),
1077    /// `<1><2>` where <2> is a block.
1078    FunctionCallBlock(Loc, Box<Expression>, Box<Statement>),
1079    /// `<1>({ <2>,* })`
1080    NamedFunctionCall(Loc, Box<Expression>, Vec<NamedArgument>),
1081    /// `!<1>`
1082    Not(Loc, Box<Expression>),
1083    /// `~<1>`
1084    BitwiseNot(Loc, Box<Expression>),
1085    /// `delete <1>`
1086    Delete(Loc, Box<Expression>),
1087    /// `++<1>`
1088    PreIncrement(Loc, Box<Expression>),
1089    /// `--<1>`
1090    PreDecrement(Loc, Box<Expression>),
1091    /// `+<1>`
1092    ///
1093    /// Note that this isn't actually supported by Solidity.
1094    UnaryPlus(Loc, Box<Expression>),
1095    /// `-<1>`
1096    Negate(Loc, Box<Expression>),
1097
1098    /// `<1> ** <2>`
1099    Power(Loc, Box<Expression>, Box<Expression>),
1100    /// `<1> * <2>`
1101    Multiply(Loc, Box<Expression>, Box<Expression>),
1102    /// `<1> / <2>`
1103    Divide(Loc, Box<Expression>, Box<Expression>),
1104    /// `<1> % <2>`
1105    Modulo(Loc, Box<Expression>, Box<Expression>),
1106    /// `<1> + <2>`
1107    Add(Loc, Box<Expression>, Box<Expression>),
1108    /// `<1> - <2>`
1109    Subtract(Loc, Box<Expression>, Box<Expression>),
1110    /// `<1> << <2>`
1111    ShiftLeft(Loc, Box<Expression>, Box<Expression>),
1112    /// `<1> >> <2>`
1113    ShiftRight(Loc, Box<Expression>, Box<Expression>),
1114    /// `<1> & <2>`
1115    BitwiseAnd(Loc, Box<Expression>, Box<Expression>),
1116    /// `<1> ^ <2>`
1117    BitwiseXor(Loc, Box<Expression>, Box<Expression>),
1118    /// `<1> | <2>`
1119    BitwiseOr(Loc, Box<Expression>, Box<Expression>),
1120    /// `<1> < <2>`
1121    Less(Loc, Box<Expression>, Box<Expression>),
1122    /// `<1> > <2>`
1123    More(Loc, Box<Expression>, Box<Expression>),
1124    /// `<1> <= <2>`
1125    LessEqual(Loc, Box<Expression>, Box<Expression>),
1126    /// `<1> >= <2>`
1127    MoreEqual(Loc, Box<Expression>, Box<Expression>),
1128    /// `<1> == <2>`
1129    Equal(Loc, Box<Expression>, Box<Expression>),
1130    /// `<1> != <2>`
1131    NotEqual(Loc, Box<Expression>, Box<Expression>),
1132    /// `<1> && <2>`
1133    And(Loc, Box<Expression>, Box<Expression>),
1134    /// `<1> || <2>`
1135    Or(Loc, Box<Expression>, Box<Expression>),
1136    /// `<1> ? <2> : <3>`
1137    ///
1138    /// AKA ternary operator.
1139    ConditionalOperator(Loc, Box<Expression>, Box<Expression>, Box<Expression>),
1140    /// `<1> = <2>`
1141    Assign(Loc, Box<Expression>, Box<Expression>),
1142    /// `<1> |= <2>`
1143    AssignOr(Loc, Box<Expression>, Box<Expression>),
1144    /// `<1> &= <2>`
1145    AssignAnd(Loc, Box<Expression>, Box<Expression>),
1146    /// `<1> ^= <2>`
1147    AssignXor(Loc, Box<Expression>, Box<Expression>),
1148    /// `<1> <<= <2>`
1149    AssignShiftLeft(Loc, Box<Expression>, Box<Expression>),
1150    /// `<1> >>= <2>`
1151    AssignShiftRight(Loc, Box<Expression>, Box<Expression>),
1152    /// `<1> += <2>`
1153    AssignAdd(Loc, Box<Expression>, Box<Expression>),
1154    /// `<1> -= <2>`
1155    AssignSubtract(Loc, Box<Expression>, Box<Expression>),
1156    /// `<1> *= <2>`
1157    AssignMultiply(Loc, Box<Expression>, Box<Expression>),
1158    /// `<1> /= <2>`
1159    AssignDivide(Loc, Box<Expression>, Box<Expression>),
1160    /// `<1> %= <2>`
1161    AssignModulo(Loc, Box<Expression>, Box<Expression>),
1162
1163    /// `true` or `false`
1164    BoolLiteral(Loc, bool),
1165    /// ``
1166    NumberLiteral(Loc, String, String, Option<Identifier>),
1167    /// ``
1168    RationalNumberLiteral(Loc, String, String, String, Option<Identifier>),
1169    /// ``
1170    HexNumberLiteral(Loc, String, Option<Identifier>),
1171    /// `<1>+`. See [StringLiteral].
1172    StringLiteral(Vec<StringLiteral>),
1173    /// See [Type].
1174    Type(Loc, Type),
1175    /// `<1>+`. See [HexLiteral].
1176    HexLiteral(Vec<HexLiteral>),
1177    /// `0x[a-fA-F0-9]{40}`
1178    ///
1179    /// This [should be correctly checksummed][ref], but it currently isn't being enforced in the parser.
1180    ///
1181    /// [ref]: https://docs.soliditylang.org/en/latest/types.html#address-literals
1182    AddressLiteral(Loc, String),
1183    /// Any valid [Identifier].
1184    Variable(Identifier),
1185    /// `(<1>,*)`
1186    List(Loc, ParameterList),
1187    /// `\[ <1>.* \]`
1188    ArrayLiteral(Loc, Vec<Expression>),
1189}
1190
1191/// See `Expression::components`.
1192macro_rules! expr_components {
1193    ($s:ident) => {
1194        match $s {
1195            // (Some, None)
1196            PostDecrement(_, expr) | PostIncrement(_, expr) => (Some(expr), None),
1197
1198            // (None, Some)
1199            Not(_, expr)
1200            | BitwiseNot(_, expr)
1201            | New(_, expr)
1202            | Delete(_, expr)
1203            | UnaryPlus(_, expr)
1204            | Negate(_, expr)
1205            | PreDecrement(_, expr)
1206            | Parenthesis(_, expr)
1207            | PreIncrement(_, expr) => (None, Some(expr)),
1208
1209            // (Some, Some)
1210            Power(_, left, right)
1211            | Multiply(_, left, right)
1212            | Divide(_, left, right)
1213            | Modulo(_, left, right)
1214            | Add(_, left, right)
1215            | Subtract(_, left, right)
1216            | ShiftLeft(_, left, right)
1217            | ShiftRight(_, left, right)
1218            | BitwiseAnd(_, left, right)
1219            | BitwiseXor(_, left, right)
1220            | BitwiseOr(_, left, right)
1221            | Less(_, left, right)
1222            | More(_, left, right)
1223            | LessEqual(_, left, right)
1224            | MoreEqual(_, left, right)
1225            | Equal(_, left, right)
1226            | NotEqual(_, left, right)
1227            | And(_, left, right)
1228            | Or(_, left, right)
1229            | Assign(_, left, right)
1230            | AssignOr(_, left, right)
1231            | AssignAnd(_, left, right)
1232            | AssignXor(_, left, right)
1233            | AssignShiftLeft(_, left, right)
1234            | AssignShiftRight(_, left, right)
1235            | AssignAdd(_, left, right)
1236            | AssignSubtract(_, left, right)
1237            | AssignMultiply(_, left, right)
1238            | AssignDivide(_, left, right)
1239            | AssignModulo(_, left, right) => (Some(left), Some(right)),
1240
1241            // (None, None)
1242            MemberAccess(..)
1243            | ConditionalOperator(..)
1244            | ArraySubscript(..)
1245            | ArraySlice(..)
1246            | FunctionCall(..)
1247            | FunctionCallBlock(..)
1248            | NamedFunctionCall(..)
1249            | BoolLiteral(..)
1250            | NumberLiteral(..)
1251            | RationalNumberLiteral(..)
1252            | HexNumberLiteral(..)
1253            | StringLiteral(..)
1254            | Type(..)
1255            | HexLiteral(..)
1256            | AddressLiteral(..)
1257            | Variable(..)
1258            | List(..)
1259            | ArrayLiteral(..) => (None, None),
1260        }
1261    };
1262}
1263
1264impl Expression {
1265    /// Removes one layer of parentheses.
1266    #[inline]
1267    pub fn remove_parenthesis(&self) -> &Expression {
1268        if let Expression::Parenthesis(_, expr) = self {
1269            expr
1270        } else {
1271            self
1272        }
1273    }
1274
1275    /// Strips all parentheses recursively.
1276    pub fn strip_parentheses(&self) -> &Expression {
1277        match self {
1278            Expression::Parenthesis(_, expr) => expr.strip_parentheses(),
1279            _ => self,
1280        }
1281    }
1282
1283    /// Returns shared references to the components of this expression.
1284    ///
1285    /// `(left_component, right_component)`
1286    ///
1287    /// # Examples
1288    ///
1289    /// ```
1290    /// use solang_parser::pt::{Expression, Identifier, Loc};
1291    ///
1292    /// // `a++`
1293    /// let var = Expression::Variable(Identifier::new("a"));
1294    /// let post_increment = Expression::PostIncrement(Loc::default(), Box::new(var.clone()));
1295    /// assert_eq!(post_increment.components(), (Some(&var), None));
1296    ///
1297    /// // `++a`
1298    /// let var = Expression::Variable(Identifier::new("a"));
1299    /// let pre_increment = Expression::PreIncrement(Loc::default(), Box::new(var.clone()));
1300    /// assert_eq!(pre_increment.components(), (None, Some(&var)));
1301    ///
1302    /// // `a + b`
1303    /// let var_a = Expression::Variable(Identifier::new("a"));
1304    /// let var_b = Expression::Variable(Identifier::new("b"));
1305    /// let pre_increment = Expression::Add(Loc::default(), Box::new(var_a.clone()), Box::new(var_b.clone()));
1306    /// assert_eq!(pre_increment.components(), (Some(&var_a), Some(&var_b)));
1307    /// ```
1308    #[inline]
1309    pub fn components(&self) -> (Option<&Self>, Option<&Self>) {
1310        use Expression::*;
1311        expr_components!(self)
1312    }
1313
1314    /// Returns mutable references to the components of this expression.
1315    ///
1316    /// See also [`Expression::components`].
1317    #[inline]
1318    pub fn components_mut(&mut self) -> (Option<&mut Self>, Option<&mut Self>) {
1319        use Expression::*;
1320        expr_components!(self)
1321    }
1322
1323    /// Returns whether this expression can be split across multiple lines.
1324    #[inline]
1325    pub const fn is_unsplittable(&self) -> bool {
1326        use Expression::*;
1327        matches!(
1328            self,
1329            BoolLiteral(..)
1330                | NumberLiteral(..)
1331                | RationalNumberLiteral(..)
1332                | HexNumberLiteral(..)
1333                | StringLiteral(..)
1334                | HexLiteral(..)
1335                | AddressLiteral(..)
1336                | Variable(..)
1337        )
1338    }
1339
1340    /// Returns whether this expression has spaces around it.
1341    #[inline]
1342    pub const fn has_space_around(&self) -> bool {
1343        use Expression::*;
1344        !matches!(
1345            self,
1346            PostIncrement(..)
1347                | PreIncrement(..)
1348                | PostDecrement(..)
1349                | PreDecrement(..)
1350                | Not(..)
1351                | BitwiseNot(..)
1352                | UnaryPlus(..)
1353                | Negate(..)
1354        )
1355    }
1356
1357    /// Returns if the expression is a literal
1358    pub fn is_literal(&self) -> bool {
1359        matches!(
1360            self,
1361            Expression::AddressLiteral(..)
1362                | Expression::HexLiteral(..)
1363                | Expression::BoolLiteral(..)
1364                | Expression::NumberLiteral(..)
1365                | Expression::ArrayLiteral(..)
1366                | Expression::HexNumberLiteral(..)
1367                | Expression::RationalNumberLiteral(..)
1368                | Expression::StringLiteral(..)
1369        )
1370    }
1371}
1372
1373/// A parameter.
1374///
1375/// `<ty> [storage] <name>`
1376#[derive(Debug, PartialEq, Eq, Clone)]
1377#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
1378pub struct Parameter {
1379    /// The code location.
1380    pub loc: Loc,
1381    /// An optional annotation '@annotation'.
1382    pub annotation: Option<Annotation>,
1383    /// The type.
1384    pub ty: Expression,
1385    /// The optional memory location.
1386    pub storage: Option<StorageLocation>,
1387    /// The optional identifier.
1388    pub name: Option<Identifier>,
1389}
1390
1391/// Function mutability.
1392#[derive(Debug, PartialEq, Eq, Clone)]
1393#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
1394pub enum Mutability {
1395    /// `pure`
1396    Pure(Loc),
1397
1398    /// `view`
1399    View(Loc),
1400
1401    /// `constant`
1402    Constant(Loc),
1403
1404    /// `payable`
1405    Payable(Loc),
1406}
1407
1408/// Function visibility.
1409///
1410/// Deprecated for [FunctionTy] other than `Function`.
1411#[derive(Debug, PartialEq, Eq, Clone)]
1412#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
1413#[repr(u8)] // for cmp; order of variants is important
1414pub enum Visibility {
1415    /// `external`
1416    External(Option<Loc>),
1417
1418    /// `public`
1419    Public(Option<Loc>),
1420
1421    /// `internal`
1422    Internal(Option<Loc>),
1423
1424    /// `private`
1425    Private(Option<Loc>),
1426}
1427
1428/// A function attribute.
1429#[derive(Debug, PartialEq, Eq, Clone)]
1430#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
1431#[repr(u8)] // for cmp; order of variants is important
1432pub enum FunctionAttribute {
1433    /// Visibility attribute.
1434    Visibility(Visibility),
1435
1436    /// Mutability attribute.
1437    Mutability(Mutability),
1438
1439    /// `virtual`
1440    Virtual(Loc),
1441
1442    /// `immutable`
1443    Immutable(Loc),
1444
1445    /// `override[(<identifier path>,*)]`
1446    Override(Loc, Vec<IdentifierPath>),
1447
1448    /// A modifier or constructor invocation.
1449    BaseOrModifier(Loc, Base),
1450
1451    /// An error occurred during parsing.
1452    Error(Loc),
1453}
1454
1455/// A function's type.
1456#[derive(Debug, PartialEq, Eq, Clone, Copy)]
1457#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
1458pub enum FunctionTy {
1459    /// `constructor`
1460    Constructor,
1461
1462    /// `function`
1463    Function,
1464
1465    /// `fallback`
1466    Fallback,
1467
1468    /// `receive`
1469    Receive,
1470
1471    /// `modifier`
1472    Modifier,
1473}
1474
1475/// A function definition.
1476///
1477/// `<ty> [name](<params>,*) [attributes] [returns] [body]`
1478#[derive(Debug, PartialEq, Eq, Clone)]
1479#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
1480pub struct FunctionDefinition {
1481    /// The function prototype location.
1482    pub loc_prototype: Loc,
1483    /// The code location.
1484    pub loc: Loc,
1485    /// The function type.
1486    pub ty: FunctionTy,
1487    /// The optional identifier.
1488    ///
1489    /// This can be `None` for old style fallback functions.
1490    pub name: Option<Identifier>,
1491    /// The identifier's code location.
1492    pub name_loc: Loc,
1493    /// The parameter list.
1494    pub params: ParameterList,
1495    /// The function attributes.
1496    pub attributes: Vec<FunctionAttribute>,
1497    /// The `returns` keyword's location. `Some` if this was `return`, not `returns`.
1498    pub return_not_returns: Option<Loc>,
1499    /// The return parameter list.
1500    pub returns: ParameterList,
1501    /// The function body.
1502    ///
1503    /// If `None`, the declaration ended with a semicolon.
1504    pub body: Option<Statement>,
1505}
1506
1507impl FunctionDefinition {
1508    /// Returns `true` if the function has no return parameters.
1509    #[inline]
1510    pub fn is_void(&self) -> bool {
1511        self.returns.is_empty()
1512    }
1513
1514    /// Returns `true` if the function body is empty.
1515    #[inline]
1516    pub fn is_empty(&self) -> bool {
1517        self.body.as_ref().map_or(true, Statement::is_empty)
1518    }
1519
1520    /// Sorts the function attributes.
1521    #[inline]
1522    pub fn sort_attributes(&mut self) {
1523        // we don't use unstable sort since there may be more that one `BaseOrModifier` attributes
1524        // which we want to preserve the order of
1525        self.attributes.sort();
1526    }
1527}
1528
1529/// A statement.
1530#[derive(Debug, PartialEq, Eq, Clone)]
1531#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
1532#[allow(clippy::large_enum_variant, clippy::type_complexity)]
1533pub enum Statement {
1534    /// `[unchecked] { <statements>* }`
1535    Block {
1536        /// The code location.
1537        loc: Loc,
1538        /// Whether this block is `unchecked`.
1539        unchecked: bool,
1540        /// The statements.
1541        statements: Vec<Statement>,
1542    },
1543    /// `assembly [dialect] [(<flags>,*)] <block>`
1544    Assembly {
1545        /// The code location.
1546        loc: Loc,
1547        /// The assembly dialect.
1548        dialect: Option<StringLiteral>,
1549        /// The assembly flags.
1550        flags: Option<Vec<StringLiteral>>,
1551        /// The assembly block.
1552        block: YulBlock,
1553    },
1554    /// `{ <1>,* }`
1555    Args(Loc, Vec<NamedArgument>),
1556    /// `if ({1}) <2> [else <3>]`
1557    ///
1558    /// Note that the `<1>` expression does not contain the parentheses.
1559    If(Loc, Expression, Box<Statement>, Option<Box<Statement>>),
1560    /// `while ({1}) <2>`
1561    ///
1562    /// Note that the `<1>` expression does not contain the parentheses.
1563    While(Loc, Expression, Box<Statement>),
1564    /// An [Expression].
1565    Expression(Loc, Expression),
1566    /// `<1> [= <2>];`
1567    VariableDefinition(Loc, VariableDeclaration, Option<Expression>),
1568    /// `for ([1]; [2]; [3]) [4]`
1569    ///
1570    /// The `[4]` block statement is `None` when the `for` statement ends with a semicolon.
1571    For(
1572        Loc,
1573        Option<Box<Statement>>,
1574        Option<Box<Expression>>,
1575        Option<Box<Expression>>,
1576        Option<Box<Statement>>,
1577    ),
1578    /// `do <1> while ({2});`
1579    ///
1580    /// Note that the `<2>` expression does not contain the parentheses.
1581    DoWhile(Loc, Box<Statement>, Expression),
1582    /// `continue;`
1583    Continue(Loc),
1584    /// `break;`
1585    Break(Loc),
1586    /// `return [1];`
1587    Return(Loc, Option<Expression>),
1588    /// `revert [1] (<2>,*);`
1589    Revert(Loc, Option<IdentifierPath>, Vec<Expression>),
1590    /// `revert [1] ({ <2>,* });`
1591    RevertNamedArgs(Loc, Option<IdentifierPath>, Vec<NamedArgument>),
1592    /// `emit <1>;`
1593    ///
1594    /// `<1>` is `FunctionCall`.
1595    Emit(Loc, Expression),
1596    /// `try <1> [returns (<2.1>,*) <2.2>] <3>*`
1597    ///
1598    /// `<1>` is either `New(FunctionCall)` or `FunctionCall`.
1599    Try(
1600        Loc,
1601        Expression,
1602        Option<(ParameterList, Box<Statement>)>,
1603        Vec<CatchClause>,
1604    ),
1605    /// An error occurred during parsing.
1606    Error(Loc),
1607}
1608
1609impl Statement {
1610    /// Returns `true` if the block statement contains no elements.
1611    #[inline]
1612    pub fn is_empty(&self) -> bool {
1613        match self {
1614            Self::Block { statements, .. } => statements.is_empty(),
1615            Self::Assembly { block, .. } => block.is_empty(),
1616            Self::Args(_, args) => args.is_empty(),
1617            _ => false,
1618        }
1619    }
1620}
1621
1622/// A catch clause. See [Statement].
1623#[derive(Debug, PartialEq, Eq, Clone)]
1624#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
1625pub enum CatchClause {
1626    /// `catch [(<1>)] <2>`
1627    Simple(Loc, Option<Parameter>, Statement),
1628
1629    /// `catch <1> (<2>) <3>`
1630    Named(Loc, Identifier, Parameter, Statement),
1631}
1632
1633/// A Yul statement.
1634#[derive(Debug, PartialEq, Eq, Clone)]
1635#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
1636pub enum YulStatement {
1637    /// `<1>,+ = <2>`
1638    Assign(Loc, Vec<YulExpression>, YulExpression),
1639    /// `let <1>,+ [:= <2>]`
1640    VariableDeclaration(Loc, Vec<YulTypedIdentifier>, Option<YulExpression>),
1641    /// `if <1> <2>`
1642    If(Loc, YulExpression, YulBlock),
1643    /// A [YulFor] statement.
1644    For(YulFor),
1645    /// A [YulSwitch] statement.
1646    Switch(YulSwitch),
1647    /// `leave`
1648    Leave(Loc),
1649    /// `break`
1650    Break(Loc),
1651    /// `continue`
1652    Continue(Loc),
1653    /// A [YulBlock] statement.
1654    Block(YulBlock),
1655    /// A [YulFunctionDefinition] statement.
1656    FunctionDefinition(Box<YulFunctionDefinition>),
1657    /// A [YulFunctionCall] statement.
1658    FunctionCall(Box<YulFunctionCall>),
1659    /// An error occurred during parsing.
1660    Error(Loc),
1661}
1662
1663/// A Yul switch statement.
1664///
1665/// `switch <condition> <cases>* [default <default>]`
1666///
1667/// Enforced by the parser:
1668///
1669/// - `cases` is guaranteed to be a `Vec` of `YulSwitchOptions::Case`.
1670/// - `default` is guaranteed to be `YulSwitchOptions::Default`.
1671/// - At least one of `cases` or `default` must be non-empty/`Some` respectively.
1672#[derive(Debug, PartialEq, Eq, Clone)]
1673#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
1674pub struct YulSwitch {
1675    /// The code location.
1676    pub loc: Loc,
1677    /// The switch condition.
1678    pub condition: YulExpression,
1679    /// The switch cases.
1680    pub cases: Vec<YulSwitchOptions>,
1681    /// The optional default case.
1682    pub default: Option<YulSwitchOptions>,
1683}
1684
1685/// A Yul for statement.
1686///
1687/// `for <init_block> <condition> <post_block> <execution_block>`
1688#[derive(Debug, PartialEq, Eq, Clone)]
1689#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
1690pub struct YulFor {
1691    /// The code location.
1692    pub loc: Loc,
1693    /// The for statement init block.
1694    pub init_block: YulBlock,
1695    /// The for statement condition.
1696    pub condition: YulExpression,
1697    /// The for statement post block.
1698    pub post_block: YulBlock,
1699    /// The for statement execution block.
1700    pub execution_block: YulBlock,
1701}
1702
1703/// A Yul block statement.
1704///
1705/// `{ <statements>* }`
1706#[derive(Debug, PartialEq, Eq, Clone)]
1707#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
1708pub struct YulBlock {
1709    /// The code location.
1710    pub loc: Loc,
1711    /// The block statements.
1712    pub statements: Vec<YulStatement>,
1713}
1714
1715impl YulBlock {
1716    /// Returns `true` if the block contains no elements.
1717    #[inline]
1718    pub fn is_empty(&self) -> bool {
1719        self.statements.is_empty()
1720    }
1721}
1722
1723/// A Yul expression.
1724#[derive(Debug, PartialEq, Eq, Clone)]
1725#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
1726pub enum YulExpression {
1727    /// `<1> [: <2>]`
1728    BoolLiteral(Loc, bool, Option<Identifier>),
1729    /// `<1>[e<2>] [: <2>]`
1730    NumberLiteral(Loc, String, String, Option<Identifier>),
1731    /// `<1> [: <2>]`
1732    HexNumberLiteral(Loc, String, Option<Identifier>),
1733    /// `<0> [: <1>]`
1734    HexStringLiteral(HexLiteral, Option<Identifier>),
1735    /// `<0> [: <1>]`
1736    StringLiteral(StringLiteral, Option<Identifier>),
1737    /// Any valid [Identifier].
1738    Variable(Identifier),
1739    /// [YulFunctionCall].
1740    FunctionCall(Box<YulFunctionCall>),
1741    /// `<1>.<2>`
1742    SuffixAccess(Loc, Box<YulExpression>, Identifier),
1743}
1744
1745/// A Yul typed identifier.
1746///
1747/// `<id> [: <ty>]`
1748#[derive(Debug, PartialEq, Eq, Clone)]
1749#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
1750pub struct YulTypedIdentifier {
1751    /// The code location.
1752    pub loc: Loc,
1753    /// The identifier.
1754    pub id: Identifier,
1755    /// The optional type.
1756    pub ty: Option<Identifier>,
1757}
1758
1759/// A Yul function definition.
1760///
1761/// `function <name> (<params>,*) [-> (<returns>,*)] <body>`
1762#[derive(Debug, PartialEq, Eq, Clone)]
1763#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
1764pub struct YulFunctionDefinition {
1765    /// The code location.
1766    pub loc: Loc,
1767    /// The identifier.
1768    pub id: Identifier,
1769    /// The parameters.
1770    pub params: Vec<YulTypedIdentifier>,
1771    /// The return parameters.
1772    pub returns: Vec<YulTypedIdentifier>,
1773    /// The function body.
1774    pub body: YulBlock,
1775}
1776
1777impl YulFunctionDefinition {
1778    /// Returns `true` if the function has no return parameters.
1779    #[inline]
1780    pub fn is_void(&self) -> bool {
1781        self.returns.is_empty()
1782    }
1783
1784    /// Returns `true` if the function body is empty.
1785    #[inline]
1786    pub fn is_empty(&self) -> bool {
1787        self.body.is_empty()
1788    }
1789}
1790
1791/// A Yul function call.
1792///
1793/// `<id>(<arguments>,*)`
1794#[derive(Debug, PartialEq, Eq, Clone)]
1795#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
1796pub struct YulFunctionCall {
1797    /// The code location.
1798    pub loc: Loc,
1799    /// The identifier.
1800    pub id: Identifier,
1801    /// The function call arguments.
1802    pub arguments: Vec<YulExpression>,
1803}
1804
1805/// A Yul switch case or default statement. See [YulSwitch].
1806#[derive(Debug, PartialEq, Eq, Clone)]
1807#[cfg_attr(feature = "pt-serde", derive(Serialize, Deserialize))]
1808pub enum YulSwitchOptions {
1809    /// `case <1> <2>`
1810    Case(Loc, YulExpression, YulBlock),
1811    /// `default <1>`
1812    Default(Loc, YulBlock),
1813}
solang_parser/pt.rs

solang_parser/
pt.rs
