File : asis-expressions.ads
------------------------------------------------------------------------------
-- --
-- ASIS-for-GNAT IMPLEMENTATION COMPONENTS --
-- --
-- --
-- A S I S . E X P R E S S I O N S --
-- --
-- S p e c --
-- --
-- --
-- This specification is adapted from the Ada Semantic Interface --
-- Specification (ASIS) definition, ISO/IEC 15291, Working Draft. In --
-- accordance with the (expected) copyright of the ASIS definition, you can --
-- freely copy and modify this specification, provided that if you --
-- redistribute a modified version, any changes that you have made are --
-- clearly indicated. --
-- --
------------------------------------------------------------------------------
-- The content of this specification is taken "as is" from ASIS 2.0.R.
-- The code is reformatted to follow the GNAT coding style rules
-- Currently Is_Dispatching_Operation function (section 17.40) is commented
-- out, because it looks like Asis.Expression is not the right location
-- for this function, and it should be moved into Asis.Declarations
------------------------------------------------------------------------------
-- 17 package Asis.Expressions
------------------------------------------------------------------------------
------------------------------------------------------------------------------
package Asis.Expressions is
------------------------------------------------------------------------------
------------------------------------------------------------------------------
-- Asis.Expressions encapsulates a set of queries that operate on
-- An_Expression and An_Association elements.
------------------------------------------------------------------------------
------------------------------------------------------------------------------
-- 17.1 function Corresponding_Expression_Type
------------------------------------------------------------------------------
function Corresponding_Expression_Type
(Expression : in Asis.Expression)
return Asis.Declaration;
------------------------------------------------------------------------------
-- Expression - Specifies the expression to query
--
-- Returns the type declaration for the type or subtype of the expression.
-- This query does not "unwind" subtypes or derived types to get to the
-- Corresponding_First_Subtype or Corresponding_Parent_Subtype declarations.
-- For example, for the following program text:
--
-- type Int is range -5_000 .. 5_000;
-- type My_Int is new Int;
-- type Good_Int is new My_Int;
-- Var: Good_Int;
--
-- The type declaration for Good_Int should be returned. The "unwinding"
-- should not occur. The type declaration for either My_Int or Int should not
-- be returned.
--
-- Returns a Nil_Element if the argument Expression does not represent an Ada
-- expression having an Ada type, including the following classes:
--
-- - Naming expressions that name packages, subprograms, tasks, etc. These
-- expressions do have a Corresponding_Name_Definition and a
-- Corresponding_Name_Declaration. Although task objects do have
-- a type, this query is limited, on purpose. Thus, when a naming
-- expression is given to this query (for packages, subprograms,
-- tasks, etc.), this query will return Nil_Element. As the
-- Application Note below indicates, if any further information
-- is needed, the element should be queried by
-- Corresponding_Name_Definition or Corresponding_Name_Declaration,
-- which should eventually return an A_Task_Type_Declaration element.
--
-- - When An_Identifier Element representing an attribute designator is
-- passed as the actual to this query.
--
-- - The Actual_Parameter Expression from A_Pragma_Argument_Association for a
-- Pragma may or may not have a Corresponding_Expression_Type.
--
-- - An_Attribute_Reference Element also may or may not have a
-- Corresponding_Expression_Type;
--
-- - An enumeration_aggregate which is a part of
-- enumeration_representation_clause.
--
-- Returns a Nil_Element, if statically determinable type of Expression is a
-- class-wide type.
--
-- --|AN Application Note:
-- --|AN
-- --|AN If the returned declaration is Nil, an application should make its
-- --|AN own analysis based on Corresponding_Name_Definition or
-- --|AN Corresponding_Name_Declaration to get more information about the
-- --|AN argument, including the static type resolution for class-wide
-- --|AN expressions, if needed. Use Enclosing_Element to determine if
-- --|AN Expression is from pragma argument association. If for such an
-- --|AN expression, Corresponding_Name_Definition raises ASIS_Failed (with a
-- --|AN Status of Value_Error), this An_Expression element does not represent
-- --|AN a normal Ada expression at all and does not follow normal Ada
-- --|AN semantic rules.
-- --|AN For example, "pragma Private_Part (Open => Yes);", the "Yes"
-- --|AN expression may simply be a "keyword" that is specially recognized by
-- --|AN the implementor's compilation system and may not refer to any
-- --|AN declared object.
--
-- Appropriate Element_Kinds:
-- An_Expression
--
-- Returns Element_Kinds:
-- Not_An_Element
-- A_Declaration
--
-- --|ER An_Integer_Literal - 2.4 - No child elements
-- --|ER A_Real_Literal - 2.4 - No child elements
-- --|ER A_String_Literal - 2.6 - No child elements
-- --|ER
-- --|ER A string image returned by:
-- --|ER function Value_Image
--
------------------------------------------------------------------------------
-- 17.2 function Value_Image
------------------------------------------------------------------------------
function Value_Image
(Expression : in Asis.Expression)
return Wide_String;
------------------------------------------------------------------------------
-- Expression - Specifies the expression to query
--
-- Returns the string image of the value of the string, integer, or real
-- literal.
--
-- For string literals, Value will return the quotes around the string
-- literal, these quotes are doubled, just as any quote appearing embedded in
-- the string literal in the program text.
--
-- The form of numbers returned by this query may vary between implementors.
-- Implementors are encouraged, but not required, to return numeric literals
-- using the same based or exponent form used in the original compilation
-- text.
--
-- Appropriate Expression_Kinds:
-- An_Integer_Literal
-- A_Real_Literal
-- A_String_Literal
--
------------------------------------------------------------------------------
-- --|ER An_Identifier - 4.1 - No child elements
-- --|ER An_Operator_Symbol - 4.1 - No child elements
-- --|ER A_Character_Literal - 4.1 - No child elements
-- --|ER An_Enumeration_Literal - 4.1 - No child elements
-- --|ER
-- --|ER A string image returned by:
-- --|ER function Name
-- --|ER
-- --|ER Semantic elements returned by:
-- --|ER function Corresponding_Name_Definition
-- --|ER function Corresponding_Name_Definition_List
-- --|ER function Corresponding_Name_Declaration
--
------------------------------------------------------------------------------
-- 17.3 function Name_Image
------------------------------------------------------------------------------
function Name_Image
(Expression : in Asis.Expression)
return Program_Text;
------------------------------------------------------------------------------
-- Name - Specifies the name to query
--
-- Returns the program text image of the name.
--
-- An_Operator_Symbol elements have names with embedded quotes """abs"""
-- (function "abs").
--
-- A_Character_Literal elements have names with embedded apostrophes "'x'"
-- (literal 'x').
--
-- An_Enumeration_Literal and An_Identifier elements have identifier names
-- "Blue" (literal Blue) "Abc" (identifier Abc).
--
-- Note: Implicit subtypes that can be encountered while traversing the
-- semantic information embedded in implicit inherited subprogram declarations
-- (Reference Manual 3.4 (17-22)) could have names that are unique in a
-- particular scope. This is because these subtypes are Is_Part_Of_Implicit
-- declarations that do not form part of the physical text of the original
-- compilation units. Some applications may wish to carefully separate the
-- names of declarations from the names of Is_Part_Of_Implicit declaration
-- when creating symbol tables and other name-specific lookup mechanisms.
--
-- The case of names returned by this query may vary between implementors.
-- Implementors are encouraged, but not required, to return names in the
-- same case as was used in the original compilation text.
--
-- Appropriate Expression_Kinds:
-- An_Identifier
-- An_Operator_Symbol
-- A_Character_Literal
-- An_Enumeration_Literal
--
------------------------------------------------------------------------------
-- 17.4 function References
------------------------------------------------------------------------------
function References
(Name : in Asis.Element;
Within_Element : in Asis.Element;
Implicitly : in Boolean := False)
return Asis.Name_List;
------------------------------------------------------------------------------
-- Name - Specifies the entity to query
-- Within_Element - Specifies the limits for the query which is limited
-- to the Element and its children.
--
-- If the Implicitly argument is True:
-- Returns all usage references of the given entity made by both explicit
-- and implicit elements within the given limits.
--
-- If the Implicitly argument is False:
-- Returns all usage references of the given entity made only by explicit
-- elements within the given limits.
--
-- Returned references are in their order of appearance.
--
-- Appropriate Element_Kinds:
-- A_Defining_Name
-- Returns Element_Kinds:
-- An_Expression
--
-- May raise ASIS_Failed with a Status of Obsolete_Reference_Error if the
-- argument is part of an inconsistent compilation unit.
--
------------------------------------------------------------------------------
-- 17.5 function Is_Referenced
------------------------------------------------------------------------------
function Is_Referenced
(Name : in Asis.Element;
Within_Element : in Asis.Element;
Implicitly : in Boolean := False)
return Boolean;
------------------------------------------------------------------------------
-- Name - Specifies the entity to query
-- Within_Element - Specifies the limits for the query which is limited
-- to the Element and its children.
--
-- If the Implicitly argument is True:
-- Returns True if the Name is referenced by either implicit or explicit
-- elements within the given limits.
--
-- If the Implicitly argument is False:
-- Returns True only if the Name is referenced by explicit elements.
--
-- Returns False for any unexpected Element.
--
-- Expected Element_Kinds:
-- A_Defining_Name
--
-- May raise ASIS_Failed with a Status of Obsolete_Reference_Error if the
-- argument is part of an inconsistent compilation unit.
--
------------------------------------------------------------------------------
-- 17.6 function Corresponding_Name_Definition
------------------------------------------------------------------------------
function Corresponding_Name_Definition
(Reference : in Asis.Expression)
return Asis.Defining_Name;
------------------------------------------------------------------------------
-- Reference - Specifies an expression to query
--
-- Returns the defining_identifier, defining_character_literal,
-- defining_operator_symbol, or defining_program_unit_name from the
-- declaration of the referenced entity.
--
-- - Record component references return the defining name of the
-- record discriminant or component_declaration. For references to
-- inherited declarations of derived types, the
-- Corresponding_Name_Definition returns
-- the defining name of the implicit inherited declaration.
--
-- - References to implicit operators and inherited subprograms will return
-- an Is_Part_Of_Implicit defining name for the operation. The
-- Enclosing_Element of the name is an implicit declaration for the
-- operation. The Enclosing_Element of the declaration is the associated
-- derived_type_definition.
--
-- - References to formal parameters given in calls to inherited subprograms
-- will return an Is_Part_Of_Implicit defining name for the
-- Parameter_Specification from the inherited subprogram specification.
--
-- - References to visible components of instantiated generic packages will
-- return a name from the expanded generic specification instance.
--
-- - References, within expanded generic instances, that refer to other
-- components of the same, or an enclosing, expanded generic instance,
-- return a name from the appropriate expanded specification or body
-- instance.
--
-- In case of renaming, the function returns the new name for the entity.
--
-- Returns a Nil_Element if the reference is to an implicitly declared
-- element for which the implementation does not provide declarations and
-- defining name elements.
--
-- Returns a Nil_Element if the argument is a dispatching call.
--
-- The Enclosing_Element of a non-Nil result is either a Declaration or a
-- Statement.
--
-- Appropriate Expression_Kinds:
-- An_Identifier
-- An_Operator_Symbol
-- A_Character_Literal
-- An_Enumeration_Literal
--
-- Returns Element_Kinds:
-- Not_An_Element
-- A_Defining_Name
--
-- --|IP Implementation Permissions:
-- --|IP
-- --|IP An implementation may choose to return any part of multi-part
-- --|IP declarations and definitions. Multi-part declaration/definitions
-- --|IP can occur for:
-- --|IP
-- --|IP - Subprogram specification in package specification, package body,
-- --|IP and subunits (is separate);
-- --|IP - Entries in package specification, package body, and subunits
-- --|IP (is separate);
-- --|IP - Private type and full type declarations;
-- --|IP - Incomplete type and full type declarations; and
-- --|IP - Deferred constant and full constant declarations.
-- --|IP
-- --|IP No guarantee is made that the element will be the first part or
-- --|IP that the determination will be made due to any visibility rules.
-- --|IP An application should make its own analysis for each case based
-- --|IP on which part is returned.
-- --|IP
-- --|IP Some implementations do not represent all forms of implicit
-- --|IP declarations such that elements representing them can be easily
-- --|IP provided. An implementation can choose whether or not to construct
-- --|IP and provide artificial declarations for implicitly declared elements.
-- --|IP
-- --|IR Implementation Requirements:
-- --|IR
-- Raises ASIS_Inappropriate_Element, with a Status of Value_Error, if passed
-- a reference that does not have a declaration:
--
-- - a reference to an attribute_designator. Attributes are defined, but
-- have no implicit or explicit declarations;
--
-- - an identifier which syntactically is placed before "=>" in a
-- pragma_argument_association which has the form of a named association;
-- such an identifier can never have a declaration;
--
-- - an identifier specific to a pragma (Reference Manual, 2.8(10));
--
-- pragma Should_I_Check ( Really => Yes );
--
-- In this example, both the names Really and Yes have no declaration.
--
-- Raises ASIS_Inappropriate_Element, with a Status of Value_Error, if passed
-- a portion of a pragma that was "ignored" by the compiler and which does
-- not have (sufficient) semantic information for a proper return result
-- to be computed. For example,
--
-- pragma I_Am_Ignored (Foof);
--
-- The "Foof" expression is An_Identifier but raises this exception
-- if passed to Corresponding_Name_Definition if the pragma was ignored
-- or unprocessed.
--
-- Raises ASIS_Inappropriate_Element, with a Status of Value_Error, if passed
-- a portion of a pragma that is an ambiguous reference to more than one
-- entity. For example,
--
-- pragma Inline ("+"); -- Inlines all "+" operators
--
-- The "+" expression is An_Operator_Symbol but raises this
-- exception if it referenced more than one "+" operator. In this
-- case, the Corresponding_Name_Definition_List query can be used to obtain a
-- list of referenced entities.
--
------------------------------------------------------------------------------
-- 17.7 function Corresponding_Name_Definition_List
------------------------------------------------------------------------------
function Corresponding_Name_Definition_List
(Reference : in Asis.Element)
return Asis.Defining_Name_List;
------------------------------------------------------------------------------
-- Reference - Specifies an entity reference to query
--
-- Exactly like Corresponding_Name_Definition except it returns a list.
-- The list will almost always have a length of one. The exception to this
-- is the case where an expression in a pragma is ambiguous and reference
-- more than one entity. For example,
--
-- pragma Inline ("+"); -- Inlines all "+" operators
--
-- The "+" expression is An_Operator_Symbol but could reference more
-- than one "+" operator. In this case, the resulting list includes all
-- referenced entities.
--
-- Appropriate Expression_Kinds:
-- An_Identifier
-- An_Operator_Symbol
-- A_Character_Literal
-- An_Enumeration_Literal
--
-- Returns Element_Kinds:
-- A_Defining_Name
--
------------------------------------------------------------------------------
-- 17.8 function Corresponding_Name_Declaration
------------------------------------------------------------------------------
function Corresponding_Name_Declaration
(Reference : in Asis.Expression)
return Asis.Element;
------------------------------------------------------------------------------
-- Reference - Specifies the entity reference to query
--
-- Returns the declaration that declared the entity named by the given
-- reference. The result is exactly the same as:
--
-- Result := Corresponding_Name_Definition (Reference);
-- if not Is_Nil (Result) then
-- Result := Enclosing_Element (Result);
-- end if;
-- return Result;
--
-- See the comments for Corresponding_Name_Definition for details.
-- The result is either a Declaration or a Statement. Statements result
-- from references to statement labels, loop identifiers, and block
-- identifiers.
--
-- Appropriate Element_Kinds:
-- An_Expression
--
-- Appropriate Expression_Kinds:
-- An_Identifier
-- An_Operator_Symbol
-- A_Character_Literal
-- An_Enumeration_Literal
--
-- Returns Element_Kinds:
-- A_Declaration
-- A_Statement
--
-- Predefined types, exceptions, operators in package Standard can be
-- checked by testing that the enclosing Compilation_Unit is standard.
-- --|ER---------------------------------------------------------------------
-- --|ER An_Explicit_Dereference - 4.1
-- --|CR
-- --|CR Child elements returned by:
-- --|CR function Prefix
-- --|CR
--
------------------------------------------------------------------------------
-- 17.9 function Prefix
------------------------------------------------------------------------------
function Prefix (Expression : in Asis.Expression) return Asis.Expression;
------------------------------------------------------------------------------
-- Expression - Specifies the name expression to query
--
-- Returns the prefix (the construct to the left of: the rightmost unnested
-- left parenthesis in function_call elements and indexed_component elements
-- or slice elements, the rightmost 'dot' for selected_component elements, or
-- the rightmost tick for attribute_reference elements).
--
-- Returns the operator_symbol for infix operator function calls. The infix
-- form A + B is equivalent to the prefix form "+"(A, B).
--
-- Appropriate Expression_Kinds:
-- An_Explicit_Dereference P.ALL
-- An_Attribute_Reference Priv'Base'First
-- A_Function_Call Abc(...) or Integer'Image(...)
-- An_Indexed_Component An_Array(3)
-- A_Selected_Component A.B.C
-- A_Slice An_Array(3 .. 5)
--
-- Returns Expression_Kinds:
-- An_Expression
--
-- --|ER---------------------------------------------------------------------
-- --|ER An_Indexed_Component - 4.1.1
-- --|ER
-- --|CR
-- --|CR Child elements returned by:
-- --|CR function Prefix
-- --|CR function Index_Expressions
-- --|CR
--
------------------------------------------------------------------------------
-- 17.10 function Index_Expressions
------------------------------------------------------------------------------
function Index_Expressions
(Expression : in Asis.Expression)
return Asis.Expression_List;
------------------------------------------------------------------------------
-- Expression - Specifies an indexed_component to query
--
-- Returns the list of expressions (possibly only one) within the parenthesis,
-- in their order of appearance.
--
-- Appropriate Expression_Kinds:
-- An_Indexed_Component
--
-- Returns Element_Kinds:
-- An_Expression
--
-- --|ER---------------------------------------------------------------------
-- --|ER A_Slice - 4.1.2
-- --|CR
-- --|CR Child elements returned by:
-- --|CR function Prefix
-- --|CR function Slice_Range
-- --|CR
--
------------------------------------------------------------------------------
-- 17.11 function Slice_Range
------------------------------------------------------------------------------
function Slice_Range
(Expression : in Asis.Expression)
return Asis.Discrete_Range;
------------------------------------------------------------------------------
-- Expression - Specifies the slice to query
--
-- Returns the discrete range of the slice.
--
-- Appropriate Expression_Kinds:
-- A_Slice
--
-- Returns Definition_Kinds:
-- A_Discrete_Range
--
------------------------------------------------------------------------------
-- 17.12 function Selector
------------------------------------------------------------------------------
function Selector (Expression : in Asis.Expression) return Asis.Expression;
------------------------------------------------------------------------------
-- Expression - Specifies the selected_component to query
--
-- Returns the selector (the construct to the right of the rightmost 'dot' in
-- the selected_component).
--
-- Appropriate Expression_Kinds:
-- A_Selected_Component
--
-- Returns Expression_Kinds:
-- An_Identifier
-- An_Operator_Symbol
-- A_Character_Literal
-- An_Enumeration_Literal
--
------------------------------------------------------------------------------
-- 17.13 function Attribute_Designator_Identifier
------------------------------------------------------------------------------
function Attribute_Designator_Identifier
(Expression : in Asis.Expression)
return Asis.Expression;
------------------------------------------------------------------------------
-- Expression - Specifies an attribute_reference expression to query
--
-- Returns the identifier of the attribute_designator (the construct to the
-- right of the rightmost tick of the attribute_reference). The Prefix of
-- the attribute_reference can itself be an attribute_reference as in
-- T'BASE'FIRST where the prefix is T'BASE and the attribute_designator name
-- is FIRST.
--
-- Attribute_designator reserved words "access", "delta", and "digits" are
-- treated as An_Identifier.
--
-- Appropriate Expression_Kinds:
-- An_Attribute_Reference
--
-- Returns Expression_Kinds:
-- An_Identifier
--
------------------------------------------------------------------------------
-- 17.14 function Attribute_Designator_Expressions
------------------------------------------------------------------------------
function Attribute_Designator_Expressions
(Expression : in Asis.Expression)
return Asis.Expression_List;
------------------------------------------------------------------------------
-- Expression - Specifies an attribute expression to query
--
-- Returns the static expressions associated with the optional argument of the
-- attribute_designator. Expected predefined attributes are A'First(N),
-- A'Last(N), A'Length(N), and A'Range(N).
--
-- Returns a Nil_Element_List if there are no arguments.
--
-- Appropriate Expression_Kinds:
-- An_Attribute_Reference
-- Appropriate Attribute_Kinds:
-- A_First_Attribute
-- A_Last_Attribute
-- A_Length_Attribute
-- A_Range_Attribute
-- An_Implementation_Defined_Attribute
-- An_Unknown_Attribute
--
-- Returns Element_Kinds:
-- An_Expression
--
-- --|IP Implementation Permissions:
-- --|IP
-- --|IP This query returns a list to support implementation-defined
-- --|IP attributes that may have more than one static_expression.
--
------------------------------------------------------------------------------
-- 17.15 function Record_Component_Associations
------------------------------------------------------------------------------
function Record_Component_Associations
(Expression : in Asis.Expression;
Normalized : in Boolean := False)
return Asis.Association_List;
------------------------------------------------------------------------------
-- Expression - Specifies an aggregate expression to query
-- Normalized - Specifies whether the normalized form is desired
--
-- Returns a list of the record_component_association elements of a
-- record_aggregate or an extension_aggregate.
--
-- Returns a Nil_Element_List if the aggregate is of the form (null record).
--
-- An unnormalized list contains all needed associations ordered as they
-- appear in the program text. Each unnormalized association has an optional
-- list of discriminant_selector_name elements, and an explicit expression.
--
-- A normalized list contains artificial associations representing all
-- needed components in an order matching the declaration order of the
-- needed components.
--
-- Each normalized association represents a one on one mapping of a
-- component to the explicit expression. A normalized association has one
-- A_Defining_Name component that denotes the discriminant_specification or
-- component_declaration, and one An_Expression component that is the
-- expression.
--
-- Appropriate Expression_Kinds:
-- A_Record_Aggregate
-- An_Extension_Aggregate
--
-- Returns Association_Kinds:
-- A_Record_Component_Association
--
-- --|IR Implementation Requirements:
-- --|IR
-- --|IR Normalized associations are Is_Normalized and Is_Part_Of_Implicit.
-- --|IR Normalized associations are never Is_Equal to unnormalized
-- --|IR associations.
-- --|IR
-- --|IP Implementation Permissions:
-- --|IP
-- --|IP An implementation may choose to normalize its internal representation
-- --|IP to use the defining_identifier element instead of the
-- --|IP component_selector_name element.
-- --|IP
-- --|IP If so, this query will return Is_Normalized associations even if
-- --|IP Normalized is False, and the query
-- --|IP Record_Component_Associations_Normalized will return True.
--
------------------------------------------------------------------------------
-- 17.16 function Extension_Aggregate_Expression
------------------------------------------------------------------------------
function Extension_Aggregate_Expression
(Expression : in Asis.Expression)
return Asis.Expression;
------------------------------------------------------------------------------
-- Expression - Specifies an extension_aggregate expression to query
--
-- Returns the ancestor_part expression preceding the reserved word with in
-- the extension_aggregate.
--
-- Appropriate Expression_Kinds:
-- An_Extension_Aggregate
--
-- Returns Element_Kinds:
-- An_Expression
--
------------------------------------------------------------------------------
-- 17.17 function Array_Component_Associations
------------------------------------------------------------------------------
function Array_Component_Associations
(Expression : in Asis.Expression)
return Asis.Association_List;
------------------------------------------------------------------------------
-- Expression - Specifies an array aggregate expression to query
--
-- Returns a list of the Array_Component_Associations in an array aggregate.
--
-- Appropriate Expression_Kinds:
-- A_Positional_Array_Aggregate
-- A_Named_Array_Aggregate
--
-- Returns Association_Kinds:
-- An_Array_Component_Association
--
-- --|AN Application Note:
-- --|AN
-- --|AN While positional_array_aggregate elements do not have
-- --|AN array_component_association elements defined by Ada syntax, ASIS
-- --|AN treats A_Positional_Array_Aggregate as if it were
-- --|AN A_Named_Array_Aggregate. The An_Array_Component_Association elements
-- --|AN returned will have Array_Component_Choices that are a
-- --|AN Nil_Element_List for all positional expressions except an others
-- --|AN choice.
--
------------------------------------------------------------------------------
-- 17.18 function Array_Component_Choices
------------------------------------------------------------------------------
function Array_Component_Choices
(Association : in Asis.Association)
return Asis.Expression_List;
------------------------------------------------------------------------------
-- Association - Specifies the component association to query
--
-- If the Association is from a named_array_aggregate:
--
-- Returns the discrete_choice_list order of appearance. The choices are
-- either An_Expression or A_Discrete_Range elements, or a single
-- An_Others_Choice element.
--
-- If the Association is from a positional_array_aggregate:
--
-- Returns a single An_Others_Choice if the association is an others
-- choice (others => expression).
--
-- Returns a Nil_Element_List otherwise.
--
-- Appropriate Association_Kinds:
-- An_Array_Component_Association
--
-- Returns Element_Kinds:
-- A_Definition
-- An_Expression
--
-- Returns Definition_Kinds:
-- A_Discrete_Range
-- An_Others_Choice
--
------------------------------------------------------------------------------
-- 17.19 function Record_Component_Choices
------------------------------------------------------------------------------
function Record_Component_Choices
(Association : in Asis.Association)
return Asis.Expression_List;
------------------------------------------------------------------------------
-- Association - Specifies the component association to query
--
-- If the Association argument is from an unnormalized list:
--
-- - If the Association is a named component association:
--
-- Returns the component_choice_list order of appearance. The choices are
-- either An_Identifier elements representing component_selector_name
-- elements, or a single An_Others_Choice element.
--
-- The Enclosing_Element of the choices is the Association argument.
--
-- - If the Association is a positional component association:
--
-- Returns a Nil_Element_List.
--
-- If the Association argument is from a Normalized list:
--
-- Returns a list containing a single choice:
--
-- - A_Defining_Name element representing the defining_identifier of
-- the component_declaration.
--
-- The Enclosing_Element of the A_Defining_Name is the
-- component_declaration.
--
-- Normalized lists contain artificial ASIS An_Association elements that
-- provide one formal A_Defining_Name => An_Expression pair per
-- association. These artificial associations are Is_Normalized. Their
-- component A_Defining_Name is not Is_Normalized.
--
-- Appropriate Association_Kinds:
-- A_Record_Component_Association
--
-- Returns Element_Kinds:
-- A_Defining_Name -- Is_Normalized(Association)
-- An_Expression -- not Is_Normalized(Association)
-- Returns Expression_Kinds:
-- An_Identifier
-- A_Definition
-- Returns Definition_Kinds:
-- An_Others_Choice
--
------------------------------------------------------------------------------
-- 17.20 function Component_Expression
------------------------------------------------------------------------------
function Component_Expression
(Association : in Asis.Association)
return Asis.Expression;
------------------------------------------------------------------------------
-- Association - Specifies the component association to query
--
-- Returns the expression of the record_component_association or
-- array_component_association.
--
-- The Enclosing_Element of the expression is the Association argument.
--
-- Normalized lists contain artificial ASIS An_Association elements that
-- provide one formal A_Defining_Name => An_Expression pair per
-- association. These artificial associations are Is_Normalized. Their
-- component An_Expression elements are not Is_Normalized.
--
-- Appropriate Association_Kinds:
-- A_Record_Component_Association
-- An_Array_Component_Association
--
-- Returns Element_Kinds:
-- An_Expression
--
------------------------------------------------------------------------------
-- 17.21 function Formal_Parameter
------------------------------------------------------------------------------
function Formal_Parameter
(Association : in Asis.Association)
return Asis.Element;
------------------------------------------------------------------------------
-- Association - Specifies the association to query
--
-- If the Association argument is from an unnormalized list:
--
-- - If the Association is given in named notation:
--
-- Returns An_Identifier representing the formal_parameter_selector_name,
-- generic_formal_parameter_selector_name, or pragma_argument_identifier.
--
-- The Enclosing_Element of the An_Identifier element is the Association
-- argument.
--
-- - If the Association is given in positional notation:
--
-- Returns a Nil_Element.
--
-- If the Association argument is from a Normalized list:
--
-- - Returns A_Defining_Name representing the defining_identifier of the
-- parameter_specification or generic_formal_parameter_declaration.
-- Pragma_argument_association elements are not available in normalized
-- form.
--
-- - The Enclosing_Element of the A_Defining_Name is the
-- parameter_specification or generic_formal_parameter_declaration element.
--
-- Normalized lists contain artificial ASIS An_Association elements that
-- provide one formal A_Defining_Name => An_Expression pair per
-- association. These artificial associations are Is_Normalized. Their
-- component A_Defining_Name elements are not Is_Normalized.
--
-- Appropriate Association_Kinds:
-- A_Parameter_Association
-- A_Generic_Association
-- A_Pragma_Argument_Association
--
-- Returns Element_Kinds:
-- Not_An_Element
-- An_Operator_Symbol
-- A_Defining_Name -- Is_Normalized(Association)
-- An_Expression -- not Is_Normalized(Association)
-- Returns Expression_Kinds:
-- An_Identifier
--
------------------------------------------------------------------------------
-- 17.22 function Actual_Parameter
------------------------------------------------------------------------------
function Actual_Parameter
(Association : in Asis.Association)
return Asis.Expression;
------------------------------------------------------------------------------
-- Association - Specifies the association to query
--
-- If the Association argument is from an unnormalized list:
--
-- Returns An_Expression representing:
--
-- - the explicit_actual_parameter of a parameter_association.
--
-- - the explicit_generic_actual_parameter of a generic_association.
--
-- - the name or expression of a pragma_argument_association.
--
-- The Enclosing_Element of An_Expression is the Association argument.
--
-- If the Association argument is from a Normalized list:
--
-- - If the Association is given explicitly:
--
-- Returns An_Expression representing:
--
-- - the explicit_actual_parameter of a parameter_association.
--
-- - the explicit_generic_actual_parameter of a generic_association.
--
-- The Enclosing_Element of An_Expression is the Association argument.
--
-- - If the Association is given by default:
--
-- Returns An_Expression representing:
--
-- - the corresponding default_expression of the Is_Normalized
-- A_Parameter_Association.
--
-- - the corresponding default_expression or default_name of the
-- Is_Normalized A_Generic_Association.
--
-- - The Enclosing_Element of the An_Expression element is the
-- parameter_specification or generic_formal_parameter_declaration that
-- contains the default_expression or default_name, except for the case
-- when this An_Expression element is an implicit naming expression
-- representing the actual subprogram selected at the place of the
-- instantiation for A_Box_Default. In the latter case, the
-- Enclosing_Element for such An_Expression is the instantiation.
--
-- Normalized lists contain artificial ASIS An_Association elements that
-- provide one formal A_Defining_Name => An_Expression pair per
-- association. These artificial associations are Is_Normalized.
-- Artificial associations of default associations are
-- Is_Defaulted_Association. Their component An_Expression elements are
-- not Is_Normalized and are not Is_Defaulted_Association.
--
-- If the argument is A_Pragma_Argument_Association, then this function may
-- return any expression to support implementation-defined pragmas.
--
-- Appropriate Association_Kinds:
-- A_Parameter_Association
-- A_Generic_Association
-- A_Pragma_Argument_Association
--
-- Returns Element_Kinds:
-- An_Expression
--
------------------------------------------------------------------------------
-- 17.23 function Discriminant_Selector_Names
------------------------------------------------------------------------------
function Discriminant_Selector_Names
(Association : in Asis.Discriminant_Association)
return Asis.Expression_List;
------------------------------------------------------------------------------
-- Association - Specifies the discriminant association to query
--
-- If the Association argument is from an unnormalized list:
--
-- - If the Association is a named discriminant_association:
--
-- Returns a list of the An_Identifier discriminant_selector_name elements
-- in order of appearance.
--
-- The Enclosing_Element of the names is the Association argument.
--
-- - If the Association is a positional discriminant_association:
--
-- Returns a Nil_Element_List.
--
-- If the Association argument is from a Normalized list:
--
-- Returns a list containing a single A_Defining_Name element representing
-- the defining_identifier of the discriminant_specification.
--
-- The Enclosing_Element of the A_Defining_Name is the
-- discriminant_specification.
--
-- Normalized lists contain artificial ASIS An_Association elements that
-- provide one formal A_Defining_Name => An_Expression pair per
-- association. These artificial associations are Is_Normalized. Their
-- component A_Defining_Name elements are not Is_Normalized.
--
-- Appropriate Association_Kinds:
-- A_Discriminant_Association
--
-- Returns Element_Kinds:
-- A_Defining_Name -- Is_Normalized(Association)
-- An_Expression -- not Is_Normalized(Association)
-- Returns Expression_Kinds:
-- An_Identifier
--
------------------------------------------------------------------------------
-- 17.24 function Discriminant_Expression
------------------------------------------------------------------------------
function Discriminant_Expression
(Association : in Asis.Discriminant_Association)
return Asis.Expression;
------------------------------------------------------------------------------
-- Association - Specifies the discriminant_association to query
--
-- If the Association argument is from an unnormalized list:
--
-- Returns An_Expression representing the expression of the
-- discriminant_association.
--
-- The Enclosing_Element of An_Expression is the Association argument.
--
-- If the Association argument is from a Normalized list:
--
-- - If the Association is given explicitly:
--
-- Returns An_Expression representing the expression of the
-- discriminant_association.
--
-- The Enclosing_Element of An_Expression is the Association argument.
--
-- - If the Association is given by default:
--
-- Returns An_Expression representing:
--
-- - the corresponding default_expression of the Is_Normalized
-- A_Discriminant_Association.
--
-- - The Enclosing_Element of the An_Expression element is the
-- discriminant_specification that contains the default_expression.
--
-- Normalized lists contain artificial ASIS An_Association elements that
-- provide one formal A_Defining_Name => An_Expression pair per
-- association. These artificial associations are Is_Normalized.
-- Artificial associations of default associations are
-- Is_Defaulted_Association. Their component An_Expression elements are
-- not Is_Normalized and are not Is_Defaulted_Association.
--
-- Appropriate Association_Kinds:
-- A_Discriminant_Association
--
-- Returns Element_Kinds:
-- An_Expression
--
------------------------------------------------------------------------------
-- 17.25 function Is_Normalized
------------------------------------------------------------------------------
function Is_Normalized (Association : in Asis.Association) return Boolean;
------------------------------------------------------------------------------
-- Association - Specifies the association to query
--
-- Returns True if the association is a normalized, artificially created
-- association returned by the queries Discriminant_Associations,
-- Generic_Actual_Part, Call_Statement_Parameters,
-- Record_Component_Associations, or Function_Call_Parameters where
-- Normalized => True (or the operation returns Is_Normalized associations
-- even if Normalized => False). See the Implementation Permissions for
-- these queries.
--
-- Returns False for any unexpected Element.
--
-- Expected Association_Kinds:
-- A_Discriminant_Association
-- A_Record_Component_Association
-- A_Parameter_Association
-- A_Generic_Association
--
------------------------------------------------------------------------------
-- 17.26 function Is_Defaulted_Association
------------------------------------------------------------------------------
function Is_Defaulted_Association
(Association : in Asis.Association)
return Boolean;
------------------------------------------------------------------------------
-- Association - Specifies the association to query
--
-- Returns True if the association is a normalized, artificially created
-- association returned by the queries Discriminant_Associations,
-- Generic_Actual_Part, Record_Component_Associations,
-- Call_Statement_Parameters, or Function_Call_Parameters where
-- Normalized => True (or the operation returns default associations even if
-- Normalized => False) and the association contains a default expression.
-- A default expression is one that is implicitly supplied by the language
-- semantics and that was not explicitly supplied (typed) by the user.
--
-- Returns False for any unexpected Element.
--
-- Expected Association_Kinds:
-- A_Parameter_Association
-- A_Generic_Association
--
-- --|AN Note: Always returns False for discriminant associations. Defaulted
-- --|AN discriminant associations occur only when the discriminant constraint
-- --|AN is completely missing from a subtype indication. Consequently, it is
-- --|AN not possible to obtain a (normalized) discriminant constraint list
-- --|AN for such subtype indications. Always returns False for component
-- --|AN associations. Aggregates cannot have defaulted components.
--
------------------------------------------------------------------------------
-- 17.27 function Expression_Parenthesized
------------------------------------------------------------------------------
function Expression_Parenthesized
(Expression : in Asis.Expression)
return Asis.Expression;
------------------------------------------------------------------------------
-- Expression - Specifies the parenthesized expression to query
--
-- Returns the expression within the parenthesis. This operation unwinds only
-- one set of parenthesis at a time, so the result may itself be
-- A_Parenthesized_Expression.
--
-- A_Parenthesized_Expression kind corresponds only to the (expression)
-- alternative in the syntax notion of primary in Reference Manual 4.4. For
-- example, an expression of a type_conversion is A_Parenthesized_Expression
-- only if it is similar to the form subtype_mark((expression)) where it has
-- at least one set of its own parenthesis.
--
-- Appropriate Expression_Kinds:
-- A_Parenthesized_Expression
--
-- Returns Element_Kinds:
-- An_Expression
--
------------------------------------------------------------------------------
-- 17.28 function Is_Prefix_Call
------------------------------------------------------------------------------
function Is_Prefix_Call (Expression : in Asis.Expression) return Boolean;
------------------------------------------------------------------------------
-- Expression - Specifies the function call expression to query
--
-- Returns True if the function call is in prefix form.
--
-- Returns False for any unexpected Element.
--
-- For example, - Foo (A, B); -- Returns TRUE
-- "<" (A, B); -- Returns TRUE
-- ... A < B ... -- Returns FALSE
--
-- Expected Expression_Kinds:
-- A_Function_Call
--
------------------------------------------------------------------------------
-- 17.29 function Corresponding_Called_Function
------------------------------------------------------------------------------
function Corresponding_Called_Function
(Expression : in Asis.Expression)
return Asis.Declaration;
------------------------------------------------------------------------------
-- Expression - Specifies the function_call to query
--
-- Returns the declaration of the called function.
--
-- Returns a Nil_Element if the:
--
-- - function_prefix denotes a predefined operator for which the
-- implementation does not provide an artificial function declaration,
--
-- - prefix of the call denotes an access to a function implicit or explicit
-- dereference,
--
-- - argument is a dispatching call.
--
-- If function_prefix denotes an attribute_reference, and if the corresponding
-- attribute is (re)defined by an attribute definition clause, an
-- implementation is encouraged, but not required, to return the definition
-- of the corresponding subprogram whose name is used after "use" in this
-- attribute definition clause. If an implementation cannot return such a
-- subprogram definition, a Nil_Element should be returned. For an attribute
-- reference which is not (re)defined by an attribute definition clause, a
-- Nil_Element should be returned.
--
-- Appropriate Expression_Kinds:
-- A_Function_Call
--
-- Returns Declaration_Kinds:
-- Not_A_Declaration
-- A_Function_Declaration
-- A_Function_Body_Declaration
-- A_Function_Body_Stub
-- A_Function_Renaming_Declaration
-- A_Function_Instantiation
-- A_Formal_Function_Declaration
-- A_Generic_Function_Declaration
--
-- --|IP Implementation Permissions:
-- --|IP
-- --|IP An implementation may choose to return any part of multi-part
-- --|IP declarations and definitions. Multi-part declaration/definitions
-- --|IP can occur for:
-- --|IP
-- --|IP - Subprogram specification in package specification, package body,
-- --|IP and subunits (is separate);
-- --|IP - Entries in package specification, package body, and subunits
-- --|IP (is separate);
-- --|IP - Private type and full type declarations;
-- --|IP - Incomplete type and full type declarations; and
-- --|IP - Deferred constant and full constant declarations.
-- --|IP
-- --|IP No guarantee is made that the element will be the first part or
-- --|IP that the determination will be made due to any visibility rules.
-- --|IP An application should make its own analysis for each case based
-- --|IP on which part is returned.
-- --|IP
-- --|IP An implementation can choose whether or not to construct and provide
-- --|IP artificial implicit declarations for predefined operators.
--
------------------------------------------------------------------------------
-- 17.30 function Function_Call_Parameters
------------------------------------------------------------------------------
function Function_Call_Parameters
(Expression : in Asis.Expression;
Normalized : in Boolean := False)
return Asis.Association_List;
------------------------------------------------------------------------------
-- Expression - Specifies the function call expression to query
-- Normalized - Specifies whether the normalized form is desired
--
-- Returns a list of parameter_association elements of the call.
--
-- Returns a Nil_Element_List if there are no parameter_association elements.
--
-- An unnormalized list contains only explicit associations ordered as they
-- appear in the program text. Each unnormalized association has an optional
-- formal_parameter_selector_name and an explicit_actual_parameter component.
--
-- A normalized list contains artificial associations representing all
-- explicit and default associations. It has a length equal to the number of
-- parameter_specification elements of the formal_part of the
-- parameter_and_result_profile. The order of normalized associations matches
-- the order of parameter_specification elements.
--
-- Each normalized association represents a one on one mapping of a
-- parameter_specification elements to the explicit or default expression.
-- A normalized association has one A_Defining_Name component that denotes the
-- parameter_specification, and one An_Expression component that is either the
-- explicit_actual_parameter or a default_expression.
--
-- If the prefix of the call denotes an access to a function implicit or
-- explicit deference, normalized associations are constructed on the basis
-- of the formal_part of the parameter_and_result_profile from the
-- corresponding access_to_subprogram definition.
-- Returns Nil_Element for normalized associations in the case where
-- the called function can be determined only dynamically (dispatching
-- calls). ASIS cannot produce any meaningful result in this case.
-- The exception ASIS_Inappropriate_Element is raised when the function
-- call is an attribute reference and Is_Normalized is True.
--
-- Appropriate Expression_Kinds:
-- A_Function_Call
--
-- Returns Element_Kinds:
-- A_Parameter_Association
--
-- --|IR Implementation Requirements:
-- --|IR
-- --|IR Normalized associations are Is_Normalized and Is_Part_Of_Implicit.
-- --|IR Normalized associations provided by default are
-- --|AN Is_Defaulted_Association. Normalized associations are never Is_Equal
-- --|AN to unnormalized associations.
-- --|IR
-- --|IP Implementation Permissions:
-- --|IP
-- --|IP An implementation may choose to always include default parameters in
-- --|IP its internal representation.
-- --|IP
-- --|IP An implementation may also choose to normalize its representation
-- --|IP to use defining_identifier elements rather than
-- --|IP formal_parameter_selector_name elements.
-- --|IP
-- --|IP In either case, this query will return Is_Normalized associations
-- --|IP even if Normalized is False, and the query
-- --|IP Function_Call_Parameters_Normalized will return True.
--
------------------------------------------------------------------------------
-- 17.31 function Short_Circuit_Operation_Left_Expression
------------------------------------------------------------------------------
function Short_Circuit_Operation_Left_Expression
(Expression : in Asis.Expression)
return Asis.Expression;
------------------------------------------------------------------------------
-- Expression - Specifies the short circuit operation to query
--
-- Returns the expression preceding the reserved words "and then" or "or else"
-- in the short circuit expression.
--
-- Appropriate Expression_Kinds:
-- An_And_Then_Short_Circuit
-- An_Or_Else_Short_Circuit
--
-- Returns Element_Kinds:
-- An_Expression
--
------------------------------------------------------------------------------
-- 17.32 function Short_Circuit_Operation_Right_Expression
------------------------------------------------------------------------------
function Short_Circuit_Operation_Right_Expression
(Expression : in Asis.Expression)
return Asis.Expression;
------------------------------------------------------------------------------
-- Expression - Specifies the short circuit operation to query
--
-- Returns the expression following the reserved words "or else" or "and then"
-- in the short circuit expression.
--
-- Appropriate Expression_Kinds:
-- An_And_Then_Short_Circuit
-- An_Or_Else_Short_Circuit
--
-- Returns Element_Kinds:
-- An_Expression
--
------------------------------------------------------------------------------
-- 17.33 function Membership_Test_Expression
------------------------------------------------------------------------------
function Membership_Test_Expression
(Expression : in Asis.Expression)
return Asis.Expression;
------------------------------------------------------------------------------
-- Expression - Specifies the membership test operation to query
--
-- Returns the expression on the left hand side of the membership test.
--
-- Appropriate Expression_Kinds:
-- An_In_Range_Membership_Test
-- A_Not_In_Range_Membership_Test
-- An_In_Type_Membership_Test
-- A_Not_In_Type_Membership_Test
--
-- Returns Element_Kinds:
-- An_Expression
--
------------------------------------------------------------------------------
-- 17.34 function Membership_Test_Range
------------------------------------------------------------------------------
function Membership_Test_Range
(Expression : in Asis.Expression)
return Asis.Range_Constraint;
------------------------------------------------------------------------------
-- Expression - Specifies the membership test operation to query
--
-- Returns the range following the reserved words "in" or "not in" from the
-- membership test.
--
-- Appropriate Expression_Kinds:
-- An_In_Range_Membership_Test
-- A_Not_In_Range_Membership_Test
--
-- Returns Constraint_Kinds:
-- A_Range_Attribute_Reference
-- A_Simple_Expression_Range
--
------------------------------------------------------------------------------
-- 17.35 function Membership_Test_Subtype_Mark
------------------------------------------------------------------------------
function Membership_Test_Subtype_Mark
(Expression : in Asis.Expression)
return Asis.Expression;
------------------------------------------------------------------------------
-- Expression - Specifies the membership test operation to query
--
-- Returns the subtype_mark expression following the reserved words "in" or
-- "not in" from the membership test.
--
-- Appropriate Expression_Kinds:
-- An_In_Type_Membership_Test
-- A_Not_In_Type_Membership_Test
--
-- Returns Expression_Kinds:
-- An_Identifier
-- A_Selected_Component
-- An_Attribute_Reference
--
------------------------------------------------------------------------------
-- 17.36 function Converted_Or_Qualified_Subtype_Mark
------------------------------------------------------------------------------
function Converted_Or_Qualified_Subtype_Mark
(Expression : in Asis.Expression)
return Asis.Expression;
------------------------------------------------------------------------------
-- Expression - Specifies the type conversion or qualified expression to
-- query.
--
-- Returns the subtype_mark expression that converts or qualifies the
-- expression.
--
-- Appropriate Expression_Kinds:
-- A_Type_Conversion
-- A_Qualified_Expression
--
-- Returns Expression_Kinds:
-- An_Identifier
-- A_Selected_Component
-- An_Attribute_Reference
--
------------------------------------------------------------------------------
-- 17.37 function Converted_Or_Qualified_Expression
------------------------------------------------------------------------------
function Converted_Or_Qualified_Expression
(Expression : in Asis.Expression)
return Asis.Expression;
------------------------------------------------------------------------------
-- Expression - Specifies the type conversion or qualified expression to
-- query
--
-- Returns the expression being converted or qualified.
--
-- Appropriate Expression_Kinds:
-- A_Type_Conversion
-- A_Qualified_Expression
--
-- Returns Element_Kinds:
-- An_Expression
--
------------------------------------------------------------------------------
-- 17.38 function Allocator_Subtype_Indication
------------------------------------------------------------------------------
function Allocator_Subtype_Indication
(Expression : in Asis.Expression)
return Asis.Subtype_Indication;
------------------------------------------------------------------------------
-- Expression - Specifies the allocator expression to query
--
-- Returns the subtype indication for the object being allocated.
--
-- Appropriate Expression_Kinds:
-- An_Allocation_From_Subtype
--
-- Returns Definition_Kinds:
-- A_Subtype_Indication
--
------------------------------------------------------------------------------
-- 17.39 function Allocator_Qualified_Expression
------------------------------------------------------------------------------
function Allocator_Qualified_Expression
(Expression : in Asis.Expression)
return Asis.Expression;
------------------------------------------------------------------------------
-- Expression - Specifies the allocator expression to query
--
-- Returns the qualified expression for the object being allocated.
--
-- Appropriate Expression_Kinds:
-- An_Allocation_From_Qualified_Expression
--
-- Returns Expression_Kinds:
-- A_Qualified_Expression
--
------------------------------------------------------------------------------
-- 17.40 function Is_Dispatching_Operation
------------------------------------------------------------------------------
-- function Is_Dispatching_Operation
-- (Declaration : in Asis.Element)
-- return Boolean;
------------------------------------------------------------------------------
-- Declaration - Specifies the declaration to query.
--
-- Returns True if the declaration is a primitive subprogram of a tagged type.
--
-- Returns False for any unexpected argument.
--
-- Expected Element_Kinds:
-- A_Procedure_Declaration
-- A_Function_Declaration
-- A_Procedure_Renaming_Declaration
-- A_Function_Renaming_Declaration
--
------------------------------------------------------------------------------
end Asis.Expressions