Re: [PATCH, Fortran] PING: Internal documentation for gfc_expr

[Daniel Kraft <d@domob.eu>]

[-- Attachment #1: Type: text/plain, Size: 1290 bytes --]

Daniel Kraft wrote:
> Hi,
> 
> attached is a patch and changelog that creates a new section "gfc_expr" 
> in the "Front-end data structures" chapter of gfc-internals.texi 
> describing how expressions are structured.

Hi all,

what's about this one?

Thanks,
Daniel

> As usual there are some XXX comments in that I'll remove in any case 
> before check-in and where I'd like to get special comments / special 
> care in review.
> 
> During my work on the finalization-patch the two main points where I 
> missed documentation about gfc_expr were construction of intrinsic-calls 
> and how the ref-list of EXPR_VARIABLE expressions works exactly; while 
> I've not yet found out something really useful about the first one, I 
> tried to document the latter from what I found out detailed.  Most other 
> parts of the documentation are somewhat trivial but I included them for 
> completeness' sake (and maybe they are not that clear to every reader).
> 
> Once again, I'm not sure about some things myself, so I'd love to get 
> critical review from someone who knows more than I do.  I'll check the 
> (corrected) patch in when I get ok.
> 
> Daniel
> 


-- 
Done:     Bar-Sam-Val-Wiz, Dwa-Elf-Hum-Orc, Cha-Law, Fem-Mal
Underway: Ran-Gno-Neu-Fem
To go:    Arc-Cav-Hea-Kni-Mon-Pri-Rog-Tou

[-- Attachment #2: patch.changelog --]
[-- Type: text/plain, Size: 150 bytes --]

2008-06-29  Daniel Kraft  <d@domob.eu>

	* gfc-internals.texi (section gfc_expr):  Created documentation about
	the gfc_expr internal data structure.

[-- Attachment #3: patch.diff --]
[-- Type: text/plain, Size: 6837 bytes --]

Index: gcc/fortran/gfc-internals.texi
===================================================================
--- gcc/fortran/gfc-internals.texi	(revision 137251)
+++ gcc/fortran/gfc-internals.texi	(working copy)
@@ -285,8 +285,10 @@ structures.
 
 @menu
 * gfc_code:: Representation of Executable Statements.
+* gfc_expr:: Representation of Values and Expressions.
 @end menu
 
+
 @c gfc_code
 @c --------
 
@@ -403,6 +405,147 @@ case-block, and @code{extx.case_list} co
 corresponds to.  The @code{block} member links to the next case in the list.
 
 
+@c gfc_expr
+@c --------
+
+@node gfc_expr
+@section @code{gfc_expr}
+@c XXX: Other index keys?
+@tindex @code{gfc_expr}
+@tindex @code{struct gfc_expr}
+
+Expressions and ``values'', including constants, variable-, array- and
+component-references as well as complex expressions built of operators and
+function calls are internally represented as one or a whole tree of
+@code{gfc_expr} objects.  The member @code{expr_type} specifies the overall
+type of an expression (for instance, @code{EXPR_CONSTANT} for constants or
+@code{EXPR_VARIABLE} for variable references).  The members @code{ts} and
+@code{rank} as well as @code{shape}, which can be @code{NULL}, specify
+the type, rank and eventually shape of the whole expression or expression tree
+of which the current structure is the root.  @code{where} is the locus of this
+expression in the source code.
+
+Depending on the flavour of the expression being described by the object
+(that is, the value of its @code{expr_type} member), the corresponding structure
+in the @code{value} union will usually contain additional data describing the
+expression's value in a type-specific manner.  The @code{ref} member is used to
+build chains of (array-, component- and substring-) references if the expression
+in question contains such references, see below for details.
+
+
+@c XXX: Make subsections nodes of their own and create a menu?
+@subsection Constants
+
+Scalar constants are represented by @code{gfc_expr} nodes with their
+@code{expr_type} set to @code{EXPR_CONSTANT}.  The constant's value should
+already be known at compile-time and is stored in the @code{logical},
+@code{integer}, @code{real}, @code{complex} or @code{character} struct inside
+@code{value}, depending on the constant's type specification.
+
+
+@subsection Operators
+
+Operator-expressions are expressions that are the result of the execution of
+some operator on one or two operands.  These have an @code{expr_type} of
+@code{EXPR_OP}.  Their @code{value.op} structure contains additional data.
+
+@code{op1} and optionally @code{op2} if the operator is binary point to the
+two operands, and @code{operator} or @code{uop} describe the operator that
+should be evaluated on these operands, where @code{uop} describes a user-defined
+overloaded operator.
+
+
+@subsection Function Calls
+
+If the expression is the return value of a function-call, its @code{expr_type}
+is set to @code{EXPR_FUNCTION}, and @code{symtree} must point to the symtree
+identifying the function to be called.  @code{value.function.actual} holds the
+actual arguments given to the function as a linked list of
+@code{gfc_actual_arglist} nodes.
+
+The other members of @code{value.function} describe the function being called
+in more detail, containing a link to the intrinsic symbol or user-defined
+function symbol if the call is to an intrinsic or user-defined function,
+respectively.  These values are determined during resolution-phase from the
+structure's @code{symtree} member.
+
+@c XXX: Some more details about intrinsic function calls once I know myself
+@c about them?
+
+
+@subsection Array- and Structure-Constructors
+
+Array- and structure-constructors (one could probably call them ``array-'' and
+``derived-type constants'') are @code{gfc_expr} structures with their
+@code{expr_type} member set to @code{EXPR_ARRAY} or @code{EXPR_STRUCTURE},
+respectively.  For structure constructors, @code{symtree} points to the
+derived-type symbol for the type being constructed.
+
+The values for initializing each array element or structure component are
+stored as linked-list of @code{gfc_constructor} nodes in the
+@code{value.constructor} member.
+
+
+@subsection Null
+
+@code{NULL} is a special value for pointers; it can be of different base types.
+Such a @code{NULL} value is represented in the internal tree by a
+@code{gfc_expr} node with @code{expr_type} @code{EXPR_NULL}.  If the base type
+of the @code{NULL} expression is known, it is stored in @code{ts} (that's for
+instance the case for default-initializers of @code{ALLOCATABLE} components),
+but this member can also be set to @code{BT_UNKNOWN} if the information is not
+available (for instance, when the expression is a pointer-initializer
+@code{NULL()}).
+
+
+@subsection Variables and Reference Expressions
+
+Variable references are @code{gfc_expr} structures with their @code{expr_type}
+set to @code{EXPR_VARIABLE}; their @code{symtree} should point to the variable
+that is referenced.
+
+For this type of expression, it's also possible to chain array-, component-
+or substring-references to the original expression to get something like
+@samp{struct%component(2:5)}, where @code{component} is either an array or
+a @code{CHARACTER} member of @code{struct} that is of some derived-type.  Such a
+chain of references is achieved by a linked list headed by @code{ref} of the
+@code{gfc_expr} node.  For the example above it would be (@samp{==|} is the
+last @code{NULL} pointer):
+
+@smallexample
+EXPR_VARIABLE(struct) ==> REF_COMPONENT(component) ==> REF_ARRAY(2:5) ==|
+@end smallexample
+
+If @code{component} is a string rather than an array, the last element would be
+a @code{REF_SUBSTRING} reference, of course.  If the variable itself or some
+component referenced is an array and the expression should reference the whole
+array rather than being followed by an array-element or -section reference, a
+@code{REF_ARRAY} reference must be built as the last element in the chain with
+an array-reference type of @code{AR_FULL}. Consider this example code:
+
+@smallexample
+TYPE :: mytype
+  INTEGER :: array(42)
+END TYPE mytype
+
+TYPE(mytype) :: variable
+INTEGER :: local_array(5)
+
+CALL do_something (variable%array, local_array)
+@end smallexample
+
+The @code{gfc_expr} nodes representing the arguments to the @samp{do_something}
+call will have a reference-chain like this:
+
+@smallexample
+EXPR_VARIABLE(variable) ==> REF_COMPONENT(array) ==> REF_ARRAY(FULL) ==|
+EXPR_VARIABLE(local_array) ==> REF_ARRAY(FULL) ==|
+@end smallexample
+
+@c XXX
+@c What good is EXPR_SUBSTRING?  When is it used?
+
+
 @c ---------------------------------------------------------------------
 @c LibGFortran
 @c ---------------------------------------------------------------------