6.2. Unit providers

6.2.1. Libadalang.Project_Provider

This package provides an Unit_Provider implementation that relies on a project file.

Trace : constant GNATCOLL.Traces.Trace_Handle

Object type:: GNATCOLL.Traces.Trace_Handle
Default value:: GNATCOLL.Traces.Create ("LIBADALANG.PROJECT_PROVIDER", GNATCOLL.Traces.From_Config)

Partition_Trace : constant GNATCOLL.Traces.Trace_Handle

Object type:: GNATCOLL.Traces.Trace_Handle
Default value:: GNATCOLL.Traces.Create ("LIBADALANG.PROJECT_PROVIDER.PARTITION", GNATCOLL.Traces.From_Config)

Resolution_Trace : constant GNATCOLL.Traces.Trace_Handle

Object type:: GNATCOLL.Traces.Trace_Handle
Default value:: GNATCOLL.Traces.Create ("LIBADALANG.PROJECT_PROVIDER.RESOLUTION", GNATCOLL.Traces.From_Config)

Unsupported_View_Error: exception: See the Create_Project_Unit_Provider functions below

type Provider_And_Projects

Components:

Provider (Unit_Provider_Reference) –
Projects (GNATCOLL.Projects.Project_Array_Access) –

type Provider_And_Projects_Array

type Provider_And_Projects_Array_Access

procedure Free (PAP_Array : Provider_And_Projects_Array_Access)

function Create_Project_Unit_Providers (Tree : GNATCOLL.Projects.Project_Tree_Access) → Provider_And_Projects_Array_Access 

Create unit providers for consistent sets of projects in Tree.

As unit providers must guarantee that there exists at most one source file for each couple (unit name, unit kind), this creates more than one unit providers when Project is an aggregate project that contains multiple definitions for the same unit.

The project pointed to by Tree must outlive the returned unit file providers, and it is up to callers to deallocate Tree itself.

function Create_Project_Unit_Provider (Tree : GNATCOLL.Projects.Project_Tree_Access; Project : GNATCOLL.Projects.Project_Type; Env : GNATCOLL.Projects.Project_Environment_Access; Is_Project_Owner : Standard.Boolean) → Unit_Provider_Reference 

Likewise, but create only one unit provider.

If a non-null Project is given, use it to provide units. Raise an Unsupported_View_Error exception if that project aggregates more than one project in its closure.

If Project is not provided, run Create_Project_Unit_Providers: if it returns only one provider, return it, otherwise raise an Unsupported_View_Error exception.

If Is_Project_Owner is true, the result owns Tree, thus the caller must not deallocate it itself. Otherwise, the project pointed to by Project must outlive the returned unit file provider.

function Convert (Kind : Analysis_Unit_Kind) → GNATCOLL.Projects.Unit_Parts: Convert our kind for analysis unit into the corresponding GNATCOLL.Projects value.

package Filename_Vectors is new Ada.Containers.Vectors

package Filename_Vectors is new Ada.Containers.Vectors
     (Index_Type   => Positive,
      Element_Type => Ada.Strings.Unbounded.Unbounded_String,
      "="          => Ada.Strings.Unbounded."=");

Instantiated generic package:: Filename_Vectors

type Source_Files_Mode

function Source_Files (Tree : GNATCOLL.Projects.Project_Tree'Class; Mode : Source_Files_Mode; Projects : GNATCOLL.Projects.Project_Array) → Libadalang.Project_Provider.Filename_Vectors.Vector

Return the list of source files in the given project Tree. Which sources are considered depends on Mode:

Default: sources in the root project and its non-externally built dependencies;
Root_Project: sources in the root project only;
Whole_Project: sources in the whole project tree (i.e. including externally built dependencies);
Whole_Project_With_Runtime: sources in the whole project tree plus runtime sources.

If Projects is not empty, return instead the list for the sources in all sub-projects in Projects, still applying the given mode to the search.

function Source_Files (Tree : GPR2.Project.Tree.Object; Mode : Source_Files_Mode; Projects : GPR2.Project.View.Set.Object) → Libadalang.Project_Provider.Filename_Vectors.Vector

Return the list of source files in the given project Tree. Which sources are considered depends on Mode:

Default: sources in the root project and its non-externally built dependencies;
Root_Project: sources in the root project only;
Whole_Project: sources in the whole project tree (i.e. including externally built dependencies);
Whole_Project_With_Runtime: sources in the whole project tree plus runtime sources.

If Projects is not empty, return instead the list for the sources in all sub-projects in Projects, still applying the given mode to the search.

function Default_Charset_From_Project (Tree : GNATCOLL.Projects.Project_Tree'Class; Project : GNATCOLL.Projects.Project_Type) → Standard.String

Try to detect the default charset to use for the given project.

Restrict the detection to the subproject Project, or to Tree’s root project if left to Prj.No_Project.

Note that, as of today, this detection only looks for the -gnatW8 compiler switch: other charsets are not supported.

Runtime_Missing_Error: exception

Exception raised by the Create_Project_Unit_Provider[s] functions when passed a project that does not have the runtime project loaded.

In order to load the runtime project, pass With_Runtime => True to the relevant project loading procedure (in GPR2.Project.Tree).

Source_Info_Missing_Error: exception

Exception raised by the Create_Project_Unit_Provider[s] functions when passed a project that does not contain the necessary source information.

In order to load the source infomation necessary for unit providers to work correctly, use GPR2.Projects.Tree.Update_Sources or the Update_Sources shortcut below.

procedure Check_Source_Info (Tree : GPR2.Project.Tree.Object): Raise Runtime_Missing_Error` if ``Tree does not have a runtime project loaded. Raise Source_Missing_Info_Error if it does not have source information loaded.

type GPR2_Provider_And_Projects

Components:

Provider (Unit_Provider_Reference) –
Projects (GPR2.Project.View.Vector.Object) –

type GPR2_Provider_And_Projects_Array

type GPR2_Provider_And_Projects_Array_Access

function Create_Project_Unit_Providers (Tree : GPR2.Project.Tree.Object) → GPR2_Provider_And_Projects_Array_Access 

Create unit providers for consistent sets of projects in Tree.

As unit providers must guarantee that there exists at most one source file for each couple (unit name, unit kind), this creates more than one unit providers when Project is an aggregate project that contains multiple definitions for the same unit.

The project pointed to by Tree must outlive the returned unit file providers, and it is up to callers to deallocate Tree itself.

function Create_Project_Unit_Provider (Tree : GPR2.Project.Tree.Object; Project : GPR2.Project.View.Object) → Unit_Provider_Reference 

Likewise, but create only one unit provider.

If a non-null Project is given, use it to provide units. Raise an Unsupported_View_Error exception if that project aggregates more than one project in its closure.

If Project is not provided, run Create_Project_Unit_Providers: if it returns only one provider, return it, otherwise raise an Unsupported_View_Error exception.

function Default_Charset_From_Project (Tree : GPR2.Project.Tree.Object; Project : GPR2.Project.View.Object) → Standard.String

Try to detect the default charset to use for the given project.

Restrict the detection to the subproject Project, or to Tree’s root project if left to Prj.No_Project.

Note that, as of today, this detection only looks for the -gnatW8 compiler switch: other charsets are not supported.

6.2.2. Libadalang.Auto_Provider

This package provides the capability to automatically discover the layout of source files in an Ada project, given a list of files, or a file name pattern and a list of directories.

It is useful in order to easily run Libadalang on a complex project that does not have its own GPR project file.

Default_Source_Filename_Pattern : constant GNAT.Regpat.Pattern_Matcher

Object type:: System.Regpat.Pattern_Matcher
Default value:: GNAT.Regpat.Compile ("\.(ad.|a|spc|bdy)$")

Default_Source_Filename_Regexp : constant GNAT.Regexp.Regexp

Object type:: System.Regexp.Regexp
Default value:: GNAT.Regexp.Compile (".*\.(ad.|a|spc|bdy)")

Default matchers for Ada source filenames. They match most usual file extensions used for Ada sources: .ads, .adb, .ada, .spc, .bdy, etc.

function Find_Files (Name_Pattern : System.Regpat.Pattern_Matcher; Directories : GNATCOLL.VFS.File_Array) → GNATCOLL.VFS.File_Array_Access: Return the list of absolute file names for all regular files in the given Directories whose name match the given regular expression Name_Pattern. The result is dynamically allocated, so the caller must free it when done with it.

function Find_Files_Regexp (Name_Pattern : System.Regexp.Regexp; Directories : GNATCOLL.VFS.File_Array) → GNATCOLL.VFS.File_Array_Access

Like Find_Files, but works on GNAT.Regexp patterns.

Note: this function is not an overload, so that calls such as Find_Files (Directories => D); are not ambiguous.

type Auto_Unit_Provider

Unit provider for a given list of files

function Create_Auto_Provider (Input_Files : GNATCOLL.VFS.File_Array; Charset : Standard.String) → Auto_Unit_Provider 

Return a unit provider that knows which compilation units are to be found in the given list of source files.

This knowledge is built trying to parse all given Input_Files as Ada source files and listing the compilation units found there. Files that cannot be parsed properly are discarded. If two compilation units are found for the same unit, the first that is found in Input_Files is taken and the other ones are discarded.

Source files are decoded using the given Charset.

function Create_Auto_Provider_Reference (Input_Files : GNATCOLL.VFS.File_Array; Charset : Standard.String) → Unit_Provider_Reference : Wrapper around Create_Auto_Provider as a shortcut to create a unit provider reference.