7.4. Miscellanous

7.4.3. Libadalang.Introspection

This package provides primitives to inspect the structure of parse trees. It answers questions such as: what is the index of a syntax field in a node? or conversely, to what syntax field does a couple (index, node kind) correspond?

For instance, the following code snippet prints the name of the first syntax field in Node:

declare
   Field_Ref : constant Field_Reference :=
      Field_Reference_From_Index (Node.Kind, 1);
begin
   Ada.Text_IO.Put_Line (Field_Name (Field_Ref));
end;
function DSL_Name (Id : Node_Type_Id) return String

Return the name corresponding to Id in the Langkit DSL

function Lookup_DSL_Name (Name : String) return Any_Node_Type_Id

Look for the node type for which Name is in the Lankgit DSL. Return it if found, otherwise return None.

function Is_Abstract (Id : Node_Type_Id) return Boolean

Return whether Id designates an abstract node

function Is_Concrete (Id : Node_Type_Id) return Boolean
function Kind_For (Id : Node_Type_Id) return Ada_Node_Kind_Type

Return the node kind corresponding to Id. This raises a Constraint_Error if Id designates an abstract node.

function Id_For_Kind (Kind : Ada_Node_Kind_Type) return Node_Type_Id

Return the node type corresponding to the given node Kind

function Is_Root_Node (Id : Node_Type_Id) return Boolean

Return whether Id is a reference for the root node type

function Base_Type (Id : Node_Type_Id) return Node_Type_Id

If Id is the root node type, raise a Constaint_Error. Otherwise, return a reference to Id’s base type.

function Derived_Types (Id : Node_Type_Id) return Node_Type_Id_Array

Return type references for all direct derivations for Id

function Is_Derived_From (Id, Parent : Node_Type_Id) return Boolean

Return whether the type that Id represents is derives (directly or indirectly) from the type that Parent represents.

type Any_Value_Type

Polymorphic value to contain Kind values. This type has by-reference semantics, so copying it is cheap.

No_Value : constant Any_Value_Type

Special Any_Value_Type to mean: no reference to a value

function Kind (Self : Value_Type) return Value_Kind

Return the kind of values that Value holds

function As_Boolean (Self : Value_Type) return Boolean
function Create_Boolean (Value : Boolean) return Value_Type
function As_Integer (Self : Value_Type) return Integer
function Create_Integer (Value : Integer) return Value_Type
function As_Big_Integer (Self : Value_Type) return Big_Integer
function Create_Big_Integer (Value : Big_Integer) return Value_Type
function As_Character (Self : Value_Type) return Character_Type
function Create_Character (Value : Character_Type) return Value_Type
function As_Token (Self : Value_Type) return Token_Reference
function Create_Token (Value : Token_Reference) return Value_Type
function As_Unbounded_Text (Self : Value_Type) return Unbounded_Text_Type
function Create_Unbounded_Text (Value : Unbounded_Text_Type) return Value_Type
function As_Analysis_Unit (Self : Value_Type) return Analysis_Unit
function Create_Analysis_Unit (Value : Analysis_Unit) return Value_Type
function As_Node (Self : Value_Type) return Ada_Node
function Create_Node (Value : Ada_Node'Class) return Value_Type
function As_Analysis_Unit_Kind (Self : Value_Type) return Analysis_Unit_Kind
function Create_Analysis_Unit_Kind (Value : Analysis_Unit_Kind) return Value_Type
function As_Lookup_Kind (Self : Value_Type) return Lookup_Kind
function Create_Lookup_Kind (Value : Lookup_Kind) return Value_Type
function As_Find_All_Mode (Self : Value_Type) return Find_All_Mode
function Create_Find_All_Mode (Value : Find_All_Mode) return Value_Type
function As_Ref_Result_Kind (Self : Value_Type) return Ref_Result_Kind
function Create_Ref_Result_Kind (Value : Ref_Result_Kind) return Value_Type
function As_Grammar_Rule (Self : Value_Type) return Grammar_Rule
function Create_Grammar_Rule (Value : Grammar_Rule) return Value_Type
function As_Text_Type (Self : Value_Type) return Text_Type
function Create_Text_Type (Value : Text_Type) return Value_Type
function As_Aspect (Self : Value_Type) return Aspect
function Create_Aspect (Value : Aspect) return Value_Type
function As_Completion_Item (Self : Value_Type) return Completion_Item
function Create_Completion_Item (Value : Completion_Item) return Value_Type
function As_Completion_Item_Array (Self : Value_Type) return Completion_Item_Array
function Create_Completion_Item_Array (Value : Completion_Item_Array) return Value_Type
function As_Discrete_Range (Self : Value_Type) return Discrete_Range
function Create_Discrete_Range (Value : Discrete_Range) return Value_Type
function As_Discriminant_Values (Self : Value_Type) return Discriminant_Values
function Create_Discriminant_Values (Value : Discriminant_Values) return Value_Type
function As_Discriminant_Values_Array (Self : Value_Type) return Discriminant_Values_Array
function Create_Discriminant_Values_Array (Value : Discriminant_Values_Array) return Value_Type
function As_Doc_Annotation (Self : Value_Type) return Doc_Annotation
function Create_Doc_Annotation (Value : Doc_Annotation) return Value_Type
function As_Doc_Annotation_Array (Self : Value_Type) return Doc_Annotation_Array
function Create_Doc_Annotation_Array (Value : Doc_Annotation_Array) return Value_Type
function As_Ada_Node_Array (Self : Value_Type) return Ada_Node_Array
function Create_Ada_Node_Array (Value : Ada_Node_Array) return Value_Type
function As_Base_Formal_Param_Decl_Array (Self : Value_Type) return Base_Formal_Param_Decl_Array
function Create_Base_Formal_Param_Decl_Array (Value : Base_Formal_Param_Decl_Array) return Value_Type
function As_Base_Type_Decl_Array (Self : Value_Type) return Base_Type_Decl_Array
function Create_Base_Type_Decl_Array (Value : Base_Type_Decl_Array) return Value_Type
function As_Basic_Decl_Array (Self : Value_Type) return Basic_Decl_Array
function Create_Basic_Decl_Array (Value : Basic_Decl_Array) return Value_Type
function As_Compilation_Unit_Array (Self : Value_Type) return Compilation_Unit_Array
function Create_Compilation_Unit_Array (Value : Compilation_Unit_Array) return Value_Type
function As_Defining_Name_Array (Self : Value_Type) return Defining_Name_Array
function Create_Defining_Name_Array (Value : Defining_Name_Array) return Value_Type
function As_Generic_Instantiation_Array (Self : Value_Type) return Generic_Instantiation_Array
function Create_Generic_Instantiation_Array (Value : Generic_Instantiation_Array) return Value_Type
function As_Param_Spec_Array (Self : Value_Type) return Param_Spec_Array
function Create_Param_Spec_Array (Value : Param_Spec_Array) return Value_Type
function As_Type_Decl_Array (Self : Value_Type) return Type_Decl_Array
function Create_Type_Decl_Array (Value : Type_Decl_Array) return Value_Type
function As_Param_Actual (Self : Value_Type) return Param_Actual
function Create_Param_Actual (Value : Param_Actual) return Value_Type
function As_Param_Actual_Array (Self : Value_Type) return Param_Actual_Array
function Create_Param_Actual_Array (Value : Param_Actual_Array) return Value_Type
function As_Ref_Result (Self : Value_Type) return Ref_Result
function Create_Ref_Result (Value : Ref_Result) return Value_Type
function As_Ref_Result_Array (Self : Value_Type) return Ref_Result_Array
function Create_Ref_Result_Array (Value : Ref_Result_Array) return Value_Type
function As_Refd_Decl (Self : Value_Type) return Refd_Decl
function Create_Refd_Decl (Value : Refd_Decl) return Value_Type
function As_Refd_Def (Self : Value_Type) return Refd_Def
function Create_Refd_Def (Value : Refd_Def) return Value_Type
function As_Shape (Self : Value_Type) return Shape
function Create_Shape (Value : Shape) return Value_Type
function As_Shape_Array (Self : Value_Type) return Shape_Array
function Create_Shape_Array (Value : Shape_Array) return Value_Type
function As_Substitution (Self : Value_Type) return Substitution
function Create_Substitution (Value : Substitution) return Value_Type
function As_Substitution_Array (Self : Value_Type) return Substitution_Array
function Create_Substitution_Array (Value : Substitution_Array) return Value_Type
function As_Analysis_Unit_Array (Self : Value_Type) return Analysis_Unit_Array
function Create_Analysis_Unit_Array (Value : Analysis_Unit_Array) return Value_Type
function As_Unbounded_Text_Type_Array (Self : Value_Type) return Unbounded_Text_Type_Array
function Create_Unbounded_Text_Type_Array (Value : Unbounded_Text_Type_Array) return Value_Type
function Satisfies (Value : Value_Type; Constraint : Value_Constraint) return Boolean

Return whether the given Value satisfy the given Constraint

function Property_Argument_Default_Value (Property : Property_Reference; Argument_Number : Positive) return Any_Value_Type

If the argument corresponding to Argument_Number of the given Property has a default value, return it. Return No_Value otherwise. This raises a Property_Error if Property has no such argument.

type Value_Type
type Value_Array
function Eval_Node_Data (Node : Ada_Node'Class; Node_Data : Node_Data_Reference; Arguments : Value_Array) return Value_Type

Evaluate Node_Data on the given Node and the given arguments. If node data evaluation raises a Property_Error, forward it. Otherwise, return its result.

This raises a Node_Data_Evaluation_Error if Node has no such node data or if the provided arguments are invalid for it.

function Eval_Property (Node : Ada_Node'Class; Property : Property_Reference; Arguments : Value_Array) return Value_Type

Evaluate Property on the given Node and the given arguments. If the property raises a Property_Error, forward it, otherwise return its result.

This raises a Node_Data_Evaluation_Error if Node has no such property or if the provided arguments are invalid for this property.

type Any_Value_Array
function DSL_Name (Constraint : Value_Constraint) return String

Return the name corresponding to Constraint in the Langkit DSL

function Node_Data_Name (Node_Data : Node_Data_Reference) return String

Return a lower-case name for Node_Data

function Node_Data_Type (Node_Data : Node_Data_Reference) return Value_Constraint

Return the constraint associated with Node_Data’s type (or its return type).

function Lookup_Node_Data (Id : Node_Type_Id; Name : String) return Any_Node_Data_Reference

Look for the node data corresponding to the given Name (lower-case name) in the given node type reference (Id). Return it if found, otherwise return None.

function Field_Name (Field : Field_Reference) return String

Return a lower-case name for Field

function Field_Type (Field : Field_Reference) return Node_Type_Id

Return a reference to the node type that covers what Field can contain

function Eval_Field (Node : Ada_Node'Class; Field : Field_Reference) return Ada_Node

Evaluate Field on the given Node. Return the corresponding Node.

This raises a Node_Data_Evaluation_Error if Node has no such field.

function Index (Kind : Ada_Node_Kind_Type; Field : Field_Reference) return Positive

Return the index in nodes to access the given Field considering the given Kind of node.

function Field_Reference_From_Index (Kind : Ada_Node_Kind_Type; Index : Positive) return Field_Reference

Return the field reference corresponding to the given Index in nodes of the given Kind. Raise an Invalid_Field exception if there is no field corresponding to this index.

function Fields (Kind : Ada_Node_Kind_Type) return Field_Reference_Array

Return the list of fields that nodes of the given Kind have. This returns an empty array for list nodes.

function Fields (Id : Node_Type_Id) return Field_Reference_Array

Likewise, but taking a reference to a node type instead

function Property_Name (Property : Property_Reference) return String

Return a lower-case name for Property

function Property_Return_Type (Property : Property_Reference) return Value_Constraint

Return the type constraint for Property’s return type

function Property_Argument_Types (Property : Property_Reference) return Value_Constraint_Array

Return the type constraints for Property’s arguments

function Property_Argument_Name (Property : Property_Reference; Argument_Number : Positive) return String

Return the lower-cased name for Property’s argument whose index is Argument_Number. This raises a Property_Error if Property has no such argument.

function Properties (Kind : Ada_Node_Kind_Type) return Property_Reference_Array

Return the list of properties that nodes of the given Kind have

function Properties (Id : Node_Type_Id) return Property_Reference_Array

Likewise, but taking a reference to a node type instead

function Token_Node_Kind (Kind : Ada_Node_Kind_Type) return Token_Kind

Return the token kind corresponding to the given token node kind

7.4.3. Libadalang.Iterators

This package provides an interface to iterate on nodes in parse trees and to look for node patterns.

First, as an alternative to Libadalang.Analysis.Traverse, you can do:

declare
   It   : Traverse_Iterator'Class := Traverse (My_Unit.Root);
   Node : Ada_Node;
begin
   while It.Next (Node) loop
      --  Process Node
   end loop;
end;

Now, if you are exclusively looking for nodes whose text is either foo or bar, you can replace the call to Traverse with the following:

Find (My_Unit.Root, Text_Is ("foo") or Text_Is ("bar"));

The Find-like functions below take as a second argument a predicate, which is an object that can decide if a node should be processed or not. This package provides several built-in predicates (Kind_Is, Text_Is, etc.), then you can either define your own, derivating the Ada_Node_Predicate_Interface type, or compose them using Ada’s boolean operators.

package Ada_Node_Iterators is new Support.Iterators (Element_Type => Ada_Node, Element_Array => Ada_Node_Array)
type Traverse_Iterator

Iterator that yields nodes from a tree

function Traverse (Root : Ada_Node'Class) return Traverse_Iterator'Class

Return an iterator that yields all nodes under Root (included) in a prefix DFS (depth first search) fashion.

function Find (Root : Ada_Node'Class; Predicate : access function (N : Ada_Node) return Boolean) return Traverse_Iterator'Class

Return an iterator that yields all nodes under Root (included) that satisfy the Predicate predicate.

function Find (Root : Ada_Node'Class; Predicate : Ada_Node_Predicate'Class) return Traverse_Iterator'Class

Return an iterator that yields all nodes under Root (included) that satisfy the Predicate predicate.

type Ada_Node_Predicate_Interface

Predicate on nodes.

Useful predicates often rely on values from some context, so predicates that are mere accesses to a function are not powerful enough. Having a full interface for this makes it possible to package both the predicate code and some data it needs.

Note that predicates are not thread-safe: make sure you don’t use a predicate from multiple threads, as they can contain caches.

function Evaluate (P : Ada_Node_Predicate_Interface; N : Ada_Node) return Boolean is abstract

Return the value of the predicate for the N node

package Ada_Node_Predicate_References is new GNATCOLL.Refcount .Shared_Pointers (Ada_Node_Predicate_Interface'Class)
type Ada_Node_Predicate

Ref-counted reference to a predicate

function "not" (Predicate : Ada_Node_Predicate) return Ada_Node_Predicate

Return a predicate that accepts only nodes that are not accepted by Predicate.

function "and" (Left, Right : Ada_Node_Predicate) return Ada_Node_Predicate

Return a predicate that accepts only nodes that are accepted by both Left and Right.

function "or" (Left, Right : Ada_Node_Predicate) return Ada_Node_Predicate

Return a predicate that accepts only nodes that are accepted by Left or Right.

function For_All (Predicates : Ada_Node_Predicate_Array) return Ada_Node_Predicate

Return a predicate that accepts only nodes that are accepted by all given Predicates.

function For_Some (Predicates : Ada_Node_Predicate_Array) return Ada_Node_Predicate

Return a predicate that accepts only nodes that are accepted by at least one of the given Predicates.

function For_All_Children (Predicate : Ada_Node_Predicate; Skip_Null : Boolean) return Ada_Node_Predicate

Return a predicate that accepts only nodes for which Predicate accepts all children. Unless Skip_Null is false, this does not evaluate the predicate on null children.

function For_Some_Children (Predicate : Ada_Node_Predicate; Skip_Null : Boolean) return Ada_Node_Predicate

Return a predicate that accepts only nodes for which Predicate accepts at least one child. Unless Skip_Null is false, this does not evaluate the predicate on null children.

function Child_With (Field : Field_Reference; Predicate : Ada_Node_Predicate) return Ada_Node_Predicate

Return a predicate that accepts only nodes which have a child corresponding to the given field reference and for which this child is accepted by the given predicate.

function Kind_Is (Kind : Ada_Node_Kind_Type) return Ada_Node_Predicate

Return a predicate that accepts only nodes of the given Kind

function Kind_In (First, Last : Ada_Node_Kind_Type) return Ada_Node_Predicate

Return a predicate that accepts only nodes whose kind is in First .. Last.

function Text_Is (Text : Text_Type) return Ada_Node_Predicate

Return a predicate that accepts only nodes that match the given Text

function Node_Is_Null return Ada_Node_Predicate

Return a predicate that accepts only null nodes

function Decl_Defines (Name : Text_Type) return Ada_Node_Predicate

Return a predicate that accepts only Basic_Decl nodes that define the given Name.

function Xref_Is (Name : Defining_Name; Imprecise_Fallback : Boolean) return Ada_Node_Predicate

Return a predicate that accepts only nodes whose P_Gnat_Xref property returns Name.

type Ada_Node_Predicate_Array
function Find_First (Root : Ada_Node'Class; Predicate : access function (N : Ada_Node) return Boolean) return Ada_Node

Return the first node found under Root (included) that satisfies the given Predicate. Return a null node if there is no such node.

function Find_First (Root : Ada_Node'Class; Predicate : Ada_Node_Predicate'Class) return Ada_Node

Return the first node found under Root (included) that satisfies the given Predicate. Return a null node if there is no such node.

7.4.3. Libadalang.Lexer

This package provides types and primitives to split text streams into lists of tokens.

type Lexer_Input

Input from which the lexer will read tokens

procedure Extract_Tokens (Input : Lexer_Input; Tab_Stop : Positive; With_Trivia : Boolean; TDH : Token_Data_Handler; Diagnostics : Diagnostics_Vectors.Vector)

Extract tokens out of the given Input and store them into TDH.

Tab_Stop is a positive number to describe the effect of tabulation characters on the column number in source files.

Raise a Name_Error exception if this involves reading a file that can not be open. Raise an Unknown_Charset exception if the requested charset is unknown. Raise an Invalid_Input exception if the source cannot be decoded using the given Charset.

function Is_Keyword (TDH : Token_Data_Handler; Index : Token_Or_Trivia_Index; Version : Language_Version) return Boolean

Given an Ada language version, return whether a token is an Ada keyword.

Due to the way Libadalang works, every token added after Ada 83 is lexed as a regular identifier, and then treated specially by the parser in some circumstances (being akin to the notion of reserved word).

This function returns True for regular lexer keywords, as well as for those identifiers.