gcc/fortran/doc/gfc-internals/gfcexpr.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. _gfc_expr:
   7
   8 gfc_expr
   9 ********
  10
  11 .. index:: gfc_expr, struct gfc_expr
  12
  13 Expressions and 'values', including constants, variable-, array- and
  14 component-references as well as complex expressions consisting of operators and
  15 function calls are internally represented as one or a whole tree of
  16 ``gfc_expr`` objects.  The member ``expr_type`` specifies the overall
  17 type of an expression (for instance, ``EXPR_CONSTANT`` for constants or
  18 ``EXPR_VARIABLE`` for variable references).  The members ``ts`` and
  19 ``rank`` as well as ``shape``, which can be ``NULL``, specify
  20 the type, rank and, if applicable, shape of the whole expression or expression
  21 tree of which the current structure is the root.  ``where`` is the locus of
  22 this expression in the source code.
  23
  24 Depending on the flavor of the expression being described by the object
  25 (that is, the value of its ``expr_type`` member), the corresponding structure
  26 in the ``value`` union will usually contain additional data describing the
  27 expression's value in a type-specific manner.  The ``ref`` member is used to
  28 build chains of (array-, component- and substring-) references if the expression
  29 in question contains such references, see below for details.
  30
  31 Constants
  32 ^^^^^^^^^
  33
  34 Scalar constants are represented by ``gfc_expr`` nodes with their
  35 ``expr_type`` set to ``EXPR_CONSTANT``.  The constant's value shall
  36 already be known at compile-time and is stored in the ``logical``,
  37 ``integer``, ``real``, ``complex`` or ``character`` struct inside
  38 ``value``, depending on the constant's type specification.
  39
  40 Operators
  41 ^^^^^^^^^
  42
  43 Operator-expressions are expressions that are the result of the execution of
  44 some operator on one or two operands.  The expressions have an ``expr_type``
  45 of ``EXPR_OP``.  Their ``value.op`` structure contains additional data.
  46
  47 ``op1`` and optionally ``op2`` if the operator is binary point to the
  48 two operands, and ``operator`` or ``uop`` describe the operator that
  49 should be evaluated on these operands, where ``uop`` describes a user-defined
  50 operator.
  51
  52 Function Calls
  53 ^^^^^^^^^^^^^^
  54
  55 If the expression is the return value of a function-call, its ``expr_type``
  56 is set to ``EXPR_FUNCTION``, and ``symtree`` must point to the symtree
  57 identifying the function to be called.  ``value.function.actual`` holds the
  58 actual arguments given to the function as a linked list of
  59 ``gfc_actual_arglist`` nodes.
  60
  61 The other members of ``value.function`` describe the function being called
  62 in more detail, containing a link to the intrinsic symbol or user-defined
  63 function symbol if the call is to an intrinsic or external function,
  64 respectively.  These values are determined during resolution-phase from the
  65 structure's ``symtree`` member.
  66
  67 A special case of function calls are 'component calls' to type-bound
  68 procedures; those have the ``expr_type`` ``EXPR_COMPCALL`` with
  69 ``value.compcall`` containing the argument list and the procedure called,
  70 while ``symtree`` and ``ref`` describe the object on which the procedure
  71 was called in the same way as a ``EXPR_VARIABLE`` expression would.
  72 See :ref:`type-bound-procedures`.
  73
  74 Array- and Structure-Constructors
  75 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  76
  77 Array- and structure-constructors (one could probably call them 'array-' and
  78 'derived-type constants') are ``gfc_expr`` structures with their
  79 ``expr_type`` member set to ``EXPR_ARRAY`` or ``EXPR_STRUCTURE``,
  80 respectively.  For structure constructors, ``symtree`` points to the
  81 derived-type symbol for the type being constructed.
  82
  83 The values for initializing each array element or structure component are
  84 stored as linked-list of ``gfc_constructor`` nodes in the
  85 ``value.constructor`` member.
  86
  87 Null
  88 ^^^^
  89
  90 ``NULL`` is a special value for pointers; it can be of different base types.
  91 Such a ``NULL`` value is represented in the internal tree by a
  92 ``gfc_expr`` node with ``expr_type`` ``EXPR_NULL``.  If the base type
  93 of the ``NULL`` expression is known, it is stored in ``ts`` (that's for
  94 instance the case for default-initializers of ``ALLOCATABLE`` components),
  95 but this member can also be set to ``BT_UNKNOWN`` if the information is not
  96 available (for instance, when the expression is a pointer-initializer
  97 ``NULL()``).
  98
  99 Variables and Reference Expressions
 100 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 101
 102 Variable references are ``gfc_expr`` structures with their ``expr_type``
 103 set to ``EXPR_VARIABLE`` ; their ``symtree`` should point to the variable
 104 that is referenced.
 105
 106 For this type of expression, it's also possible to chain array-, component-
 107 or substring-references to the original expression to get something like
 108 :samp:`struct%component(2:5)`, where ``component`` is either an array or
 109 a ``CHARACTER`` member of ``struct`` that is of some derived-type.  Such a
 110 chain of references is achieved by a linked list headed by ``ref`` of the
 111 ``gfc_expr`` node.  For the example above it would be (:samp:`==|` is the
 112 last ``NULL`` pointer):
 113
 114 .. code-block:: c++
 115
 116   EXPR_VARIABLE(struct) ==> REF_COMPONENT(component) ==> REF_ARRAY(2:5) ==|
 117
 118 If ``component`` is a string rather than an array, the last element would be
 119 a ``REF_SUBSTRING`` reference, of course.  If the variable itself or some
 120 component referenced is an array and the expression should reference the whole
 121 array rather than being followed by an array-element or -section reference, a
 122 ``REF_ARRAY`` reference must be built as the last element in the chain with
 123 an array-reference type of ``AR_FULL``. Consider this example code:
 124
 125 .. code-block:: fortran
 126
 127   TYPE :: mytype
 128     INTEGER :: array(42)
 129   END TYPE mytype
 130
 131   TYPE(mytype) :: variable
 132   INTEGER :: local_array(5)
 133
 134   CALL do_something (variable%array, local_array)
 135
 136 The ``gfc_expr`` nodes representing the arguments to the :samp:`do_something`
 137 call will have a reference-chain like this:
 138
 139 .. code-block:: c++
 140
 141   EXPR_VARIABLE(variable) ==> REF_COMPONENT(array) ==> REF_ARRAY(FULL) ==|
 142   EXPR_VARIABLE(local_array) ==> REF_ARRAY(FULL) ==|
 143
 144 Constant Substring References
 145 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 146
 147 ``EXPR_SUBSTRING`` is a special type of expression that encodes a substring
 148 reference of a constant string, as in the following code snippet:
 149
 150 .. code-block:: c++
 151
 152   x = "abcde"(1:2)
 153
 154 In this case, ``value.character`` contains the full string's data as if it
 155 was a string constant, but the ``ref`` member is also set and points to a
 156 substring reference as described in the subsection above.