[PATCH, Fortran] Extend gfc_code internal documentation

[PATCH, Fortran] Extend gfc_code internal documentation

[Daniel Kraft]

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

Hi,

this patch extends the documentation of the gfc_code structure in the 
gfc-internals.texi documentation.  It adds an example about how the 
block-chaining for IF/SELECT works and has three detail subsections 
about DO, IF and SELECT blocks.

Please give it a close look as I'm myself rather unsure about the things 
I wrote about...  And there are two XXX marks in, please comment on 
those, too.  Otherwise I think it should be faily simple and if it's ok 
I'll check it in.  Then I can start writing a bit about gfc_expr in a 
new following section.

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: 275 bytes --]

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

	* gfc-internals.texi (section gfc_code):  Extended documentation about
	gfc_code in the internal datastructures chapter including details about
	how IF, DO and SELECT blocks look like and an example for how the
	block-chaining works.

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

Index: gcc/fortran/gfc-internals.texi
===================================================================
--- gcc/fortran/gfc-internals.texi	(revision 136954)
+++ gcc/fortran/gfc-internals.texi	(working copy)
@@ -284,9 +284,12 @@ should exhaust all possible valid combin
 structures.
 
 @menu
-* gfc_code:: Representation of Executable Statements
+* gfc_code:: Representation of Executable Statements.
 @end menu
 
+@c gfc_code
+@c --------
+
 @node gfc_code
 @section @code{gfc_code}
 @cindex statement chaining
@@ -309,13 +312,94 @@ current statement.
 If the current statement is one of @code{IF}, @code{DO}, @code{SELECT}
 it starts a block, i.e.@: a nested level in the program.  In order to
 represent this, the @code{block} member is set to point to a
-@code{gfc_code} structure whose @code{block} member points to the
-block in question.  The @code{SELECT} and @code{IF} statements may
-contain various blocks (the chain of @code{ELSE IF} and @code{ELSE}
-blocks or the various @code{CASE}s, respectively).
-
-@c What would be nice here would be an example program together with
-@c an image that says more than the mythical thousand words.
+@code{gfc_code} structure whose @code{next} member starts the chain of
+statements inside the block; this structure's @code{op} member should be set to
+the same value as the parent structure's @code{op} member.  The @code{SELECT}
+and @code{IF} statements may contain various blocks (the chain of @code{ELSE IF}
+and @code{ELSE} blocks or the various @code{CASE}s, respectively).  These chains
+are linked-lists formed by the @code{block} members.
+
+Consider the following example code:
+
+@example
+IF (foo < 20) THEN
+  PRINT *, "Too small"
+  foo = 20
+ELSEIF (foo > 50) THEN
+  PRINT *, "Too large"
+  foo = 50
+ELSE
+  PRINT *, "Good"
+END IF
+@end example
+
+This statement-block will be represented in the internal gfortran tree like
+this, were the horizontal link-chains are those induced by the @code{next}
+members and vertical links down are those of @code{block}. @samp{==|} and
+@samp{--|} mean @code{NULL} pointers to mark the end of a chain:
+
+@c XXX: Decide on right format for this "image".
+@example
+... ==> IF ==> ...
+        |
+        +--> IF foo < 20 ==> PRINT *, "Too small" ==> foo = 20 ==|
+             |
+             +--> IF foo > 50 ==> PRINT *, "Too large" ==> foo = 50 ==|
+                  |
+                  +--> ELSE ==> PRINT *, "Good" ==|
+                       |
+                       +--|
+@end example
+
+@c XXX: Make those seperate nodes?
+@subsection IF Blocks
+
+Conditionals are represented by @code{gfc_code} structures with their
+@code{op} member set to @code{EXEC_IF}.  This structure's @code{block}
+member must point to another @code{gfc_code} node being the header of the
+if-block.  This header's @code{op} member must be set to @code{EXEC_IF}, too,
+its @code{expr} member holds the condition to check for, and its @code{next}
+should point to the code-chain of the statements to execute if the condition is
+true.
+
+If in addition an @code{ELSEIF} or @code{ELSE} block is present, the
+@code{block} member of the if-block-header node points to yet another
+@code{gfc_code} structure that is the header of the elseif- or else-block.  Its
+structure is identical to that of the if-block-header, except that in case of an
+@code{ELSE} block without a new condition the @code{expr} member should be
+@code{NULL}.  This block can itself have its @code{block} member point to the
+next @code{ELSEIF} or @code{ELSE} block if there's a chain of them.
+
+@subsection Loops
+
+@code{DO} loops are stored in the tree as @code{gfc_code} nodes with their
+@code{op} set to @code{EXEC_DO} for a @code{DO} loop with iterator variable and
+to @code{EXEC_DO_WHILE} for infinite @code{DO}s and @code{DO WHILE} blocks.
+Their @code{block} member should point to a @code{gfc_code} structure heading
+the code-chain of the loop body; its @code{op} member should be set to
+@code{EXEC_DO} or @code{EXEC_DO_WHILE}, too, respectively.
+
+For @code{DO WHILE} loops, the loop condition is stored on the top
+@code{gfc_code} structure's @code{expr} member; @code{DO} forever loops are
+simply @code{DO WHILE} loops with a constant @code{.TRUE.} loop condition in
+the internal representation.
+
+Similarly, @code{DO} loops with an iterator have instead of the condition their
+@code{ext.iterator} member set to the correct values for the loop iterator
+variable and its range.
+
+@subsection @code{SELECT} Statements
+
+A @code{SELECT} block is introduced by a @code{gfc_code} structure with an
+@code{op} member of @code{EXEC_SELECT} and @code{expr} containing the expression
+to evaluate and test.  Its @code{block} member starts a list of @code{gfc_code}
+structures linked together by their @code{block} members that stores the various
+@code{CASE} parts.
+
+Each @code{CASE} node has its @code{op} member set to @code{EXEC_SELECT}, too,
+its @code{next} member points to the code-chain to be executed in the current
+case-block, and @code{extx.case_list} contains the case-values this block
+corresponds to.  The @code{block} member links to the next case in the list.
 
 
 @c ---------------------------------------------------------------------

[PATCH, Fortran] PING: Extend gfc_code internal documentation

[Daniel Kraft]

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

Daniel Kraft wrote:
> this patch extends the documentation of the gfc_code structure in the 
> gfc-internals.texi documentation.  It adds an example about how the 
> block-chaining for IF/SELECT works and has three detail subsections 
> about DO, IF and SELECT blocks.

Are there any comments on that one?  Otherwise I'll check it in on 
Saturday evening without the XXX comments, as discussed with FX.

Thanks,
Daniel

> Please give it a close look as I'm myself rather unsure about the things 
> I wrote about...  And there are two XXX marks in, please comment on 
> those, too.  Otherwise I think it should be faily simple and if it's ok 
> I'll check it in.  Then I can start writing a bit about gfc_expr in a 
> new following section.
> 
> 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: 275 bytes --]

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

	* gfc-internals.texi (section gfc_code):  Extended documentation about
	gfc_code in the internal datastructures chapter including details about
	how IF, DO and SELECT blocks look like and an example for how the
	block-chaining works.

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

Index: gcc/fortran/gfc-internals.texi
===================================================================
--- gcc/fortran/gfc-internals.texi	(revision 136954)
+++ gcc/fortran/gfc-internals.texi	(working copy)
@@ -284,9 +284,12 @@ should exhaust all possible valid combin
 structures.
 
 @menu
-* gfc_code:: Representation of Executable Statements
+* gfc_code:: Representation of Executable Statements.
 @end menu
 
+@c gfc_code
+@c --------
+
 @node gfc_code
 @section @code{gfc_code}
 @cindex statement chaining
@@ -309,13 +312,94 @@ current statement.
 If the current statement is one of @code{IF}, @code{DO}, @code{SELECT}
 it starts a block, i.e.@: a nested level in the program.  In order to
 represent this, the @code{block} member is set to point to a
-@code{gfc_code} structure whose @code{block} member points to the
-block in question.  The @code{SELECT} and @code{IF} statements may
-contain various blocks (the chain of @code{ELSE IF} and @code{ELSE}
-blocks or the various @code{CASE}s, respectively).
-
-@c What would be nice here would be an example program together with
-@c an image that says more than the mythical thousand words.
+@code{gfc_code} structure whose @code{next} member starts the chain of
+statements inside the block; this structure's @code{op} member should be set to
+the same value as the parent structure's @code{op} member.  The @code{SELECT}
+and @code{IF} statements may contain various blocks (the chain of @code{ELSE IF}
+and @code{ELSE} blocks or the various @code{CASE}s, respectively).  These chains
+are linked-lists formed by the @code{block} members.
+
+Consider the following example code:
+
+@example
+IF (foo < 20) THEN
+  PRINT *, "Too small"
+  foo = 20
+ELSEIF (foo > 50) THEN
+  PRINT *, "Too large"
+  foo = 50
+ELSE
+  PRINT *, "Good"
+END IF
+@end example
+
+This statement-block will be represented in the internal gfortran tree like
+this, were the horizontal link-chains are those induced by the @code{next}
+members and vertical links down are those of @code{block}. @samp{==|} and
+@samp{--|} mean @code{NULL} pointers to mark the end of a chain:
+
+@c XXX: Decide on right format for this "image".
+@example
+... ==> IF ==> ...
+        |
+        +--> IF foo < 20 ==> PRINT *, "Too small" ==> foo = 20 ==|
+             |
+             +--> IF foo > 50 ==> PRINT *, "Too large" ==> foo = 50 ==|
+                  |
+                  +--> ELSE ==> PRINT *, "Good" ==|
+                       |
+                       +--|
+@end example
+
+@c XXX: Make those seperate nodes?
+@subsection IF Blocks
+
+Conditionals are represented by @code{gfc_code} structures with their
+@code{op} member set to @code{EXEC_IF}.  This structure's @code{block}
+member must point to another @code{gfc_code} node being the header of the
+if-block.  This header's @code{op} member must be set to @code{EXEC_IF}, too,
+its @code{expr} member holds the condition to check for, and its @code{next}
+should point to the code-chain of the statements to execute if the condition is
+true.
+
+If in addition an @code{ELSEIF} or @code{ELSE} block is present, the
+@code{block} member of the if-block-header node points to yet another
+@code{gfc_code} structure that is the header of the elseif- or else-block.  Its
+structure is identical to that of the if-block-header, except that in case of an
+@code{ELSE} block without a new condition the @code{expr} member should be
+@code{NULL}.  This block can itself have its @code{block} member point to the
+next @code{ELSEIF} or @code{ELSE} block if there's a chain of them.
+
+@subsection Loops
+
+@code{DO} loops are stored in the tree as @code{gfc_code} nodes with their
+@code{op} set to @code{EXEC_DO} for a @code{DO} loop with iterator variable and
+to @code{EXEC_DO_WHILE} for infinite @code{DO}s and @code{DO WHILE} blocks.
+Their @code{block} member should point to a @code{gfc_code} structure heading
+the code-chain of the loop body; its @code{op} member should be set to
+@code{EXEC_DO} or @code{EXEC_DO_WHILE}, too, respectively.
+
+For @code{DO WHILE} loops, the loop condition is stored on the top
+@code{gfc_code} structure's @code{expr} member; @code{DO} forever loops are
+simply @code{DO WHILE} loops with a constant @code{.TRUE.} loop condition in
+the internal representation.
+
+Similarly, @code{DO} loops with an iterator have instead of the condition their
+@code{ext.iterator} member set to the correct values for the loop iterator
+variable and its range.
+
+@subsection @code{SELECT} Statements
+
+A @code{SELECT} block is introduced by a @code{gfc_code} structure with an
+@code{op} member of @code{EXEC_SELECT} and @code{expr} containing the expression
+to evaluate and test.  Its @code{block} member starts a list of @code{gfc_code}
+structures linked together by their @code{block} members that stores the various
+@code{CASE} parts.
+
+Each @code{CASE} node has its @code{op} member set to @code{EXEC_SELECT}, too,
+its @code{next} member points to the code-chain to be executed in the current
+case-block, and @code{extx.case_list} contains the case-values this block
+corresponds to.  The @code{block} member links to the next case in the list.
 
 
 @c ---------------------------------------------------------------------

Re: [PATCH, Fortran] PING: Extend gfc_code internal documentation

[Tobias Burnus]

Hi Daniel,

Daniel Kraft wrote:
> Are there any comments on that one?
Looks OK. Thanks for your fantastic work. Sorry that we don't do timely 
reviews, but somehow real life continues to interfere :-(
Besides, I have the feeling that you know by now more about several part 
of gfortran than some of us does ;-)


Some comments from a non-native speaker:

+This statement-block will be represented in the internal gfortran tree like
+this, were the horizontal link-chains are those induced by the @code{next}


Instead of "like this" I'd use "as follows".

+next @code{ELSEIF} or @code{ELSE} block if there's a chain of them.
+
+@subsection Loops


I'd add another empty line to make it easier to find the @subsections.

+@code{op} member set to @code{EXEC_IF}.  This structure's @code{block}
+member must point to another @code{gfc_code} node being the header of the
+if-block.  This header's @code{op} member must be set to @code{EXEC_IF}, too,

Instead of "being", I'd use "which is".


Tobias,
who had this week his doctoral defense

Re: [PATCH, Fortran] PING: Extend gfc_code internal documentation

[Daniel Kraft]

Tobias Burnus wrote:
> Hi Daniel,
> 
> Daniel Kraft wrote:
>> Are there any comments on that one?
> Looks OK. Thanks for your fantastic work. Sorry that we don't do timely 

Thanks, I'll address the comments and check in tomorrow evening as written.

> +This statement-block will be represented in the internal gfortran tree 
> like
> +this, were the horizontal link-chains are those induced by the @code{next}
> 
> Instead of "like this" I'd use "as follows".

Sounds good.

> +next @code{ELSEIF} or @code{ELSE} block if there's a chain of them.
> +
> +@subsection Loops
> 
> 
> I'd add another empty line to make it easier to find the @subsections.

Ok.

> +@code{op} member set to @code{EXEC_IF}.  This structure's @code{block}
> +member must point to another @code{gfc_code} node being the header of the
> +if-block.  This header's @code{op} member must be set to 
> @code{EXEC_IF}, too,
> 
> Instead of "being", I'd use "which is".

Will do "that is" as suggested by Dominique.

Cheers,
Daniel, who will start with gfc_expr hopefully soon...

-- 
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

Re: [PATCH, Fortran] [committed] PING: Extend gfc_code internal documentation

[Daniel Kraft]

Tobias Burnus wrote:
> Hi Daniel,
> 
> Daniel Kraft wrote:
>> Are there any comments on that one?
> Looks OK. Thanks for your fantastic work. Sorry that we don't do timely 
> reviews, but somehow real life continues to interfere :-(
> Besides, I have the feeling that you know by now more about several part 
> of gfortran than some of us does ;-)
> 
> 
> Some comments from a non-native speaker:
> 
> +This statement-block will be represented in the internal gfortran tree 
> like
> +this, were the horizontal link-chains are those induced by the @code{next}
> 
> 
> Instead of "like this" I'd use "as follows".
> 
> +next @code{ELSEIF} or @code{ELSE} block if there's a chain of them.
> +
> +@subsection Loops
> 
> 
> I'd add another empty line to make it easier to find the @subsections.
> 
> +@code{op} member set to @code{EXEC_IF}.  This structure's @code{block}
> +member must point to another @code{gfc_code} node being the header of the
> +if-block.  This header's @code{op} member must be set to 
> @code{EXEC_IF}, too,
> 
> Instead of "being", I'd use "which is".

Checked in with the suggested changes as revision 137226.

Thanks,
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