File : prj-ext.ads
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT COMPILER COMPONENTS --
4 -- --
5 -- P R J . E X T --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 2000-2013, Free Software Foundation, Inc. --
10 -- --
11 -- GNAT is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 3, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
17 -- for more details. You should have received a copy of the GNU General --
18 -- Public License distributed with GNAT; see file COPYING3. If not, go to --
19 -- http://www.gnu.org/licenses for a complete copy of the license. --
20 -- --
21 -- GNAT was originally developed by the GNAT team at New York University. --
22 -- Extensive contributions were provided by Ada Core Technologies Inc. --
23 -- --
24 ------------------------------------------------------------------------------
25
26 -- Subprograms to set, get and cache external references, to be used as
27 -- External functions in project files.
28
29 with GNAT.Dynamic_HTables;
30
31 package Prj.Ext is
32
33 -------------------------
34 -- External References --
35 -------------------------
36
37 -- External references influence the way a project tree is processed (in
38 -- particular they provide the values for the typed string variables that
39 -- are then used in case constructions).
40
41 -- External references are project-tree specific, so that when multiple
42 -- trees are loaded in parallel we can have different scenarios (or even
43 -- load the same tree twice and see different views of it).
44
45 type External_References is private;
46 No_External_Refs : constant External_References;
47
48 procedure Initialize
49 (Self : out External_References;
50 Copy_From : External_References := No_External_Refs);
51 -- Initialize Self, and copy all values from Copy_From if needed.
52 -- This has no effect if Self was already initialized.
53
54 procedure Free (Self : in out External_References);
55 -- Free memory used by Self
56
57 type External_Source is
58 (From_Command_Line,
59 From_Environment,
60 From_External_Attribute);
61 -- Indicates where was the value of an external reference defined. They are
62 -- prioritized in that order, so that a user can always use the command
63 -- line to override a value coming from his environment, or an environment
64 -- variable to override a value defined in an aggregate project through the
65 -- "for External()..." attribute.
66
67 procedure Add
68 (Self : External_References;
69 External_Name : String;
70 Value : String;
71 Source : External_Source := External_Source'First;
72 Silent : Boolean := False);
73 -- Add an external reference (or modify an existing one). No overriding is
74 -- done if the Source's priority is less than the one used to previously
75 -- set the value of the variable. The default for Source is such that
76 -- overriding always occurs. When Silent is True, nothing is output even
77 -- with non default verbosity.
78
79 function Value_Of
80 (Self : External_References;
81 External_Name : Name_Id;
82 With_Default : Name_Id := No_Name)
83 return Name_Id;
84 -- Get the value of an external reference, and cache it for future uses
85
86 function Check
87 (Self : External_References;
88 Declaration : String) return Boolean;
89 -- Check that an external declaration <external>=<value> is correct.
90 -- If it is correct, the external reference is Added.
91
92 procedure Reset (Self : External_References);
93 -- Clear the internal data structure that stores the external references
94 -- and free any allocated memory.
95
96 private
97 -- Use a Static_HTable, rather than a Simple_HTable
98
99 -- The issue is that we need to be able to copy the contents of the table
100 -- (in Initialize), but this isn't doable for Simple_HTable for which
101 -- iterators do not return the key.
102
103 type Name_To_Name;
104 type Name_To_Name_Ptr is access all Name_To_Name;
105 type Name_To_Name is record
106 Key : Name_Id;
107 Value : Name_Id;
108 Source : External_Source;
109 Next : Name_To_Name_Ptr;
110 end record;
111
112 procedure Set_Next (E : Name_To_Name_Ptr; Next : Name_To_Name_Ptr);
113 function Next (E : Name_To_Name_Ptr) return Name_To_Name_Ptr;
114 function Get_Key (E : Name_To_Name_Ptr) return Name_Id;
115
116 package Name_To_Name_HTable is new GNAT.Dynamic_HTables.Static_HTable
117 (Header_Num => Header_Num,
118 Element => Name_To_Name,
119 Elmt_Ptr => Name_To_Name_Ptr,
120 Null_Ptr => null,
121 Set_Next => Set_Next,
122 Next => Next,
123 Key => Name_Id,
124 Get_Key => Get_Key,
125 Hash => Hash,
126 Equal => "=");
127 -- General type for htables associating name_id to name_id. This is in
128 -- particular used to store the values of external references.
129
130 type Instance_Access is access all Name_To_Name_HTable.Instance;
131
132 type External_References is record
133 Refs : Instance_Access;
134 -- External references are stored in this hash table (and manipulated
135 -- through subprogrames in prj-ext.ads). External references are
136 -- project-tree specific so that one can load the same tree twice but
137 -- have two views of it, for instance.
138 end record;
139
140 No_External_Refs : constant External_References := (Refs => null);
141
142 end Prj.Ext;