Add utility methods to AST API (#1511)

Add some additional utility methods to AST nodes and the `Definition`
type:
- `ast::*::node_id()` and `Definition::node_id()` to retrieve the
underlying `NodeId` associated to the CST node
- `Definition::identifier()` to retrieve the identifier acting as the
name of a definition
- `Definition::text_offset()` to get the text offset of the start of the
definition

Also collect text offsets of identifier terminals, since this is now
needed to be able to return it for `Identifier` AST types.

Author: ggiraldez

crates/solidity/outputs/cargo/crate/src/backend/ir/ast/node_extensions/contracts.rs

@@ -50,7 +50,8 @@ impl ContractDefinitionStruct {
         base_node_ids
             .iter()
             .map(|node_id| {
-                let base_definition = Rc::new(Definition::create(*node_id, &self.semantic));
+                let base_definition =
+                    Definition::try_create(*node_id, &self.semantic).expect("node is a definition");
                 ContractBase::from_definition(&base_definition)
                     .expect("Linearised base is either a contract or interface")
             })
@@ -138,7 +139,7 @@ impl ContractDefinitionStruct {
             (None, None) => Ordering::Equal,
             (None, Some(_)) => Ordering::Less,
             (Some(_), None) => Ordering::Greater,
-            (Some(a), Some(b)) => a.unparse().cmp(&b.unparse()),
+            (Some(a), Some(b)) => a.name().cmp(&b.name()),
         });
         functions
     }

crates/solidity/outputs/cargo/crate/src/backend/ir/ast/node_extensions/definitions.rs

@@ -24,9 +24,10 @@ use crate::backend::ir::ast::{
     create_variable_declaration_statement, create_yul_function_definition, create_yul_label,
 };
 use crate::backend::{binder, SemanticAnalysis};
-use crate::cst::NodeId;
+use crate::cst::{NodeId, TextIndex};
 
 // __SLANG_DEFINITION_TYPES__ keep in sync with binder
+#[derive(Clone)]
 pub enum Definition {
     Constant(ConstantDefinition),
     Contract(ContractDefinition),
@@ -54,13 +55,13 @@ pub enum Definition {
 }
 
 impl Definition {
-    pub(crate) fn create(definition_id: NodeId, semantic: &Rc<SemanticAnalysis>) -> Self {
-        let definition = semantic
-            .binder()
-            .find_definition_by_id(definition_id)
-            .expect("definition_id references a definition node");
+    pub(crate) fn try_create(
+        definition_id: NodeId,
+        semantic: &Rc<SemanticAnalysis>,
+    ) -> Option<Self> {
+        let definition = semantic.binder().find_definition_by_id(definition_id)?;
 
-        match definition {
+        let definition = match definition {
             binder::Definition::Constant(constant_definition) => Self::Constant(
                 create_constant_definition(&constant_definition.ir_node, semantic),
             ),
@@ -133,6 +134,140 @@ impl Definition {
             binder::Definition::YulVariable(yul_variable_definition) => Self::YulVariable(
                 create_yul_identifier(&yul_variable_definition.ir_node, semantic),
             ),
+        };
+        Some(definition)
+    }
+
+    pub fn node_id(&self) -> NodeId {
+        match self {
+            Definition::Constant(constant_definition) => constant_definition.node_id(),
+            Definition::Contract(contract_definition) => contract_definition.node_id(),
+            Definition::Enum(enum_definition) => enum_definition.node_id(),
+            Definition::EnumMember(identifier) => identifier.node_id(),
+            Definition::Error(error_definition) => error_definition.node_id(),
+            Definition::Event(event_definition) => event_definition.node_id(),
+            Definition::Function(function_definition) => function_definition.node_id(),
+            Definition::Import(path_import) => path_import.node_id(),
+            Definition::ImportedSymbol(import_deconstruction_symbol) => {
+                import_deconstruction_symbol.node_id()
+            }
+            Definition::Interface(interface_definition) => interface_definition.node_id(),
+            Definition::Library(library_definition) => library_definition.node_id(),
+            Definition::Modifier(function_definition) => function_definition.node_id(),
+            Definition::Parameter(parameter) => parameter.node_id(),
+            Definition::StateVariable(state_variable_definition) => {
+                state_variable_definition.node_id()
+            }
+            Definition::Struct(struct_definition) => struct_definition.node_id(),
+            Definition::StructMember(struct_member) => struct_member.node_id(),
+            Definition::TypeParameter(parameter) => parameter.node_id(),
+            Definition::UserDefinedValueType(user_defined_value_type_definition) => {
+                user_defined_value_type_definition.node_id()
+            }
+            Definition::Variable(variable_declaration_statement) => {
+                variable_declaration_statement.node_id()
+            }
+            Definition::YulFunction(yul_function_definition) => yul_function_definition.node_id(),
+            Definition::YulLabel(yul_label) => yul_label.node_id(),
+            Definition::YulParameter(identifier) => identifier.node_id(),
+            Definition::YulVariable(identifier) => identifier.node_id(),
+        }
+    }
+
+    pub fn identifier(&self) -> Identifier {
+        match self {
+            Definition::Constant(constant_definition) => constant_definition.name(),
+            Definition::Contract(contract_definition) => contract_definition.name(),
+            Definition::Enum(enum_definition) => enum_definition.name(),
+            Definition::EnumMember(identifier) => Rc::clone(identifier),
+            Definition::Error(error_definition) => error_definition.name(),
+            Definition::Event(event_definition) => event_definition.name(),
+            Definition::Function(function_definition) => {
+                // functions that are definitions always have a name
+                function_definition
+                    .name()
+                    .expect("function definitions have a name")
+            }
+            Definition::Import(path_import) => {
+                // imports that are definition always have a name
+                path_import
+                    .alias()
+                    .expect("path import definitions have a name")
+            }
+            Definition::ImportedSymbol(import_deconstruction_symbol) => {
+                import_deconstruction_symbol
+                    .alias()
+                    .unwrap_or_else(|| import_deconstruction_symbol.name())
+            }
+            Definition::Interface(interface_definition) => interface_definition.name(),
+            Definition::Library(library_definition) => library_definition.name(),
+            Definition::Modifier(function_definition) => {
+                // modifiers always have a name
+                function_definition.name().expect("modifiers have a name")
+            }
+            Definition::Parameter(parameter) => {
+                // parameters that are definitions always have a name
+                parameter.name().expect("parameter definitions have a name")
+            }
+            Definition::StateVariable(state_variable_definition) => {
+                state_variable_definition.name()
+            }
+            Definition::Struct(struct_definition) => struct_definition.name(),
+            Definition::StructMember(struct_member) => struct_member.name(),
+            Definition::TypeParameter(parameter) => {
+                // parameters that are definitions always have a name
+                parameter
+                    .name()
+                    .expect("type parameter definitions have a name")
+            }
+            Definition::UserDefinedValueType(user_defined_value_type_definition) => {
+                user_defined_value_type_definition.name()
+            }
+            Definition::Variable(variable_declaration_statement) => {
+                variable_declaration_statement.name()
+            }
+            Definition::YulFunction(yul_function_definition) => yul_function_definition.name(),
+            Definition::YulLabel(yul_label) => yul_label.label(),
+            Definition::YulParameter(identifier) => Rc::clone(identifier),
+            Definition::YulVariable(identifier) => Rc::clone(identifier),
+        }
+    }
+
+    pub fn text_offset(&self) -> TextIndex {
+        match self {
+            Definition::Constant(constant_definition) => constant_definition.text_offset(),
+            Definition::Contract(contract_definition) => contract_definition.text_offset(),
+            Definition::Enum(enum_definition) => enum_definition.text_offset(),
+            Definition::EnumMember(identifier) => identifier.text_offset(),
+            Definition::Error(error_definition) => error_definition.text_offset(),
+            Definition::Event(event_definition) => event_definition.text_offset(),
+            Definition::Function(function_definition) => function_definition.text_offset(),
+            Definition::Import(path_import) => path_import.text_offset(),
+            Definition::ImportedSymbol(import_deconstruction_symbol) => {
+                import_deconstruction_symbol.text_offset()
+            }
+            Definition::Interface(interface_definition) => interface_definition.text_offset(),
+            Definition::Library(library_definition) => library_definition.text_offset(),
+            Definition::Modifier(function_definition) => function_definition.text_offset(),
+            Definition::Parameter(parameter) => parameter.text_offset(),
+            Definition::StateVariable(state_variable_definition) => {
+                state_variable_definition.text_offset()
+            }
+            Definition::Struct(struct_definition) => struct_definition.text_offset(),
+            Definition::StructMember(struct_member) => struct_member.text_offset(),
+            Definition::TypeParameter(parameter) => parameter.text_offset(),
+            Definition::UserDefinedValueType(user_defined_value_type_definition) => {
+                user_defined_value_type_definition.text_offset()
+            }
+            Definition::Variable(variable_declaration_statement) => {
+                variable_declaration_statement.text_offset()
+            }
+            Definition::YulFunction(yul_function_definition) => {
+                yul_function_definition.text_offset()
+            }
+            Definition::YulLabel(yul_label) => yul_label.text_offset(),
+            Definition::YulParameter(identifier) => identifier.text_offset(),
+            Definition::YulVariable(identifier) => identifier.text_offset(),
         }
     }
 
@@ -182,6 +317,9 @@ macro_rules! define_references_method {
                 pub fn references(&self) -> Vec<Reference> {
                     self.semantic.references_binding_to(self.ir_node.node_id)
                 }
+                pub fn as_definition(&self) -> Option<Definition> {
+                    Definition::try_create(self.ir_node.node_id, &self.semantic)
+                }
             }
         }
     };

crates/solidity/outputs/cargo/crate/src/backend/ir/ast/node_extensions/identifiers.rs

@@ -3,7 +3,7 @@ use std::rc::Rc;
 use super::super::IdentifierPathStruct;
 use super::Definition;
 use crate::backend::SemanticAnalysis;
-use crate::cst::{NodeId, TerminalKind, TerminalNode};
+use crate::cst::{NodeId, TerminalKind, TerminalNode, TextIndex};
 
 pub type Identifier = Rc<IdentifierStruct>;
 
@@ -24,7 +24,11 @@ pub struct IdentifierStruct {
 }
 
 impl IdentifierStruct {
-    pub fn unparse(&self) -> String {
+    pub fn node_id(&self) -> NodeId {
+        self.ir_node.id()
+    }
+
+    pub fn name(&self) -> String {
         self.ir_node.unparse()
     }
 
@@ -42,10 +46,24 @@ impl IdentifierStruct {
             .binder()
             .find_reference_by_identifier_node_id(self.ir_node.id())?;
         let definition_id = reference.resolution.as_definition_id()?;
-        Some(Definition::create(definition_id, &self.semantic))
+        Definition::try_create(definition_id, &self.semantic)
     }
 
+    /// Returns `true` if the identifier itself is a definition (eg. an enum member)
     pub fn is_definition(&self) -> bool {
+        self.as_definition().is_some()
+    }
+
+    /// Returns the `Definition` corresponding to this identifier. Panics if the
+    /// identifier is not a definition by itself, ie. this can only be called
+    /// safely if `is_definition()` returns `true`.
+    pub fn as_definition(&self) -> Option<Definition> {
+        Definition::try_create(self.ir_node.id(), &self.semantic)
+    }
+
+    /// Returns `true` if the identifier is a definition itself, or is the name
+    /// identifier of a definition
+    pub fn is_name_of_definition(&self) -> bool {
         self.semantic
             .binder()
             .find_definition_by_identifier_node_id(self.ir_node.id())
@@ -56,6 +74,12 @@ impl IdentifierStruct {
     pub fn references(&self) -> Vec<Reference> {
         self.semantic.references_binding_to(self.ir_node.id())
     }
+
+    pub fn text_offset(&self) -> TextIndex {
+        self.semantic
+            .get_text_offset_by_node_id(self.ir_node.id())
+            .unwrap()
+    }
 }
 
 pub type YulIdentifierStruct = IdentifierStruct;
@@ -98,10 +122,10 @@ impl Reference {
         }
     }
 
-    pub fn unparse(&self) -> String {
+    pub fn name(&self) -> String {
         match self {
             Reference::Identifier(identifier) | Reference::YulIdentifier(identifier) => {
-                identifier.unparse()
+                identifier.name()
             }
         }
     }
@@ -131,7 +155,7 @@ impl SemanticAnalysis {
 }
 
 impl IdentifierPathStruct {
-    pub fn unparse(&self) -> String {
+    pub fn name(&self) -> String {
         self.ir_nodes
             .iter()
             .map(|ir_node| ir_node.unparse())
@@ -146,6 +170,6 @@ impl IdentifierPathStruct {
             .binder()
             .find_reference_by_identifier_node_id(ir_node.id())?;
         let definition_id = reference.resolution.as_definition_id()?;
-        Some(Definition::create(definition_id, &self.semantic))
+        Definition::try_create(definition_id, &self.semantic)
     }
 }