[Patch, Fortran, Doc] Document type-bound operators

[Daniel Kraft <d at domob dot eu>]

Hi all,

this patch documents type-bound operators in gfc-internals.texi, handles 
them in dump-parse-tree.c and adds some items related to my F2003 work 
to the gfortran.texi Fortran 2003 status list (and also links to the 
Wiki pages from there).

This concludes type-bound operators from my point of view, excluding of 
course bug-fixes as they come up as well as the already created PRs for 
some issues.

Ok for trunk?

Daniel

--
Done:  Arc-Bar-Cav-Ran-Rog-Sam-Tou-Val-Wiz
To go: Hea-Kni-Mon-Pri

2009-08-28  Daniel Kraft  <d@domob.eu>

	PR fortran/37425
	* dump-parse-tree.c (show_typebound_proc): Renamed from `show_typebound'
	and accept gfc_typebound_proc and name instead of the symtree, needed
	for intrinsic operator output.
	(show_typebound_symtree): New method calling `show_typebound_proc'.
	(show_f2k_derived): Output type-bound operators also.
	(show_symbol): Moved output of `Procedure bindings:' label to
	`show_f2k_derived'.
	* gfortran.texi (Fortran 2003 status): Mention support of
	array-constructors with explicit type specification, type-bound
	procedures/operators, type extension, ABSTRACT types and DEFERRED.
	Link to Fortran 2003 wiki page.
	(Fortran 2008 status): Fix typo.  Link to Fortran 2008 wiki page.
	* gfc-internals.texi (Type-bound Procedures): Document the new
	members/attributes of gfc_expr.value.compcall used for type-bound
	operators.
	(Type-bound Operators): New section documenting their internals.

Index: gcc/fortran/gfortran.texi
===================================================================
--- gcc/fortran/gfortran.texi	(revision 151138)
+++ gcc/fortran/gfortran.texi	(working copy)
@@ -808,7 +808,8 @@ was used.
 @section Fortran 2003 status
 
 GNU Fortran supports several Fortran 2003 features; an incomplete
-list can be found below.
+list can be found below.  See also the
+@uref{http://gcc.gnu.org/wiki/Fortran2003, wiki page} about Fortran 2003.
 
 @itemize
 @item 
@@ -820,7 +821,8 @@ Intrinsics @code{command_argument_count}
 @cindex array, constructors
 @cindex @code{[...]}
 Array constructors using square brackets. That is, @code{[...]} rather
-than @code{(/.../)}.
+than @code{(/.../)}.  Type-specification for array constructors like
+@code{(/ some-type :: ... /)}.
 
 @item
 @cindex @code{FLUSH} statement
@@ -912,7 +914,23 @@ Renaming of operators in the @code{USE} 
 Interoperability with C (ISO C Bindings)
 
 @item
-BOZ as argument of INT, REAL, DBLE and CMPLX.
+BOZ as argument of @code{INT}, @code{REAL}, @code{DBLE} and @code{CMPLX}.
+
+@item
+@cindex type-bound procedure
+@cindex type-bound operator
+Type-bound procedures with @code{PROCEDURE} or @code{GENERIC}, and operators
+bound to a derived-type.
+
+@item
+@cindex @code{EXTENDS}
+@cindex derived-type extension
+Extension of derived-types (the @code{EXTENDS(...)} syntax).
+
+@item
+@cindex @code{ABSTRACT} type
+@cindex @code{DEFERRED} procedure binding
+@code{ABSTRACT} derived-types and declaring procedure bindings @code{DEFERRED}.
 
 @end itemize
 
@@ -924,7 +942,7 @@ The next version of the Fortran standard
 being worked on by the Working Group 5 of Sub-Committee 22 of the Joint
 Technical Committee 1 of the International Organization for
 Standardization (ISO) and the International Electrotechnical Commission
-(IEC). This group is known at @uref{http://www.nag.co.uk/sc22wg5/, WG5}.
+(IEC). This group is known as @uref{http://www.nag.co.uk/sc22wg5/, WG5}.
 The next revision of the Fortran standard is informally referred to as
 Fortran 2008, reflecting its planned release year. The GNU Fortran
 compiler has support for some of the new features in Fortran 2008. This
@@ -933,6 +951,9 @@ support is based on the latest draft, av
 differ from the drafts, no guarantee of backward compatibility can be
 made and you should only use it for experimental purposes.
 
+The @uref{http://gcc.gnu.org/wiki/Fortran2008Status, wiki} has some information
+about the current Fortran 2008 implementation status.
+
 
 @c ---------------------------------------------------------------------
 @c Compiler Characteristics
Index: gcc/fortran/dump-parse-tree.c
===================================================================
--- gcc/fortran/dump-parse-tree.c	(revision 151138)
+++ gcc/fortran/dump-parse-tree.c	(working copy)
@@ -680,40 +680,39 @@ show_components (gfc_symbol *sym)
 /* Show the f2k_derived namespace with procedure bindings.  */
 
 static void
-show_typebound (gfc_symtree* st)
+show_typebound_proc (gfc_typebound_proc* tb, const char* name)
 {
-  gcc_assert (st->n.tb);
   show_indent ();
 
-  if (st->n.tb->is_generic)
+  if (tb->is_generic)
     fputs ("GENERIC", dumpfile);
   else
     {
       fputs ("PROCEDURE, ", dumpfile);
-      if (st->n.tb->nopass)
+      if (tb->nopass)
 	fputs ("NOPASS", dumpfile);
       else
 	{
-	  if (st->n.tb->pass_arg)
-	    fprintf (dumpfile, "PASS(%s)", st->n.tb->pass_arg);
+	  if (tb->pass_arg)
+	    fprintf (dumpfile, "PASS(%s)", tb->pass_arg);
 	  else
 	    fputs ("PASS", dumpfile);
 	}
-      if (st->n.tb->non_overridable)
+      if (tb->non_overridable)
 	fputs (", NON_OVERRIDABLE", dumpfile);
     }
 
-  if (st->n.tb->access == ACCESS_PUBLIC)
+  if (tb->access == ACCESS_PUBLIC)
     fputs (", PUBLIC", dumpfile);
   else
     fputs (", PRIVATE", dumpfile);
 
-  fprintf (dumpfile, " :: %s => ", st->name);
+  fprintf (dumpfile, " :: %s => ", name);
 
-  if (st->n.tb->is_generic)
+  if (tb->is_generic)
     {
       gfc_tbp_generic* g;
-      for (g = st->n.tb->u.generic; g; g = g->next)
+      for (g = tb->u.generic; g; g = g->next)
 	{
 	  fputs (g->specific_st->name, dumpfile);
 	  if (g->next)
@@ -721,14 +720,24 @@ show_typebound (gfc_symtree* st)
 	}
     }
   else
-    fputs (st->n.tb->u.specific->n.sym->name, dumpfile);
+    fputs (tb->u.specific->n.sym->name, dumpfile);
+}
+
+static void
+show_typebound_symtree (gfc_symtree* st)
+{
+  gcc_assert (st->n.tb);
+  show_typebound_proc (st->n.tb, st->name);
 }
 
 static void
 show_f2k_derived (gfc_namespace* f2k)
 {
   gfc_finalizer* f;
+  int op;
 
+  show_indent ();
+  fputs ("Procedure bindings:", dumpfile);
   ++show_level;
 
   /* Finalizer bindings.  */
@@ -739,7 +748,22 @@ show_f2k_derived (gfc_namespace* f2k)
     }
 
   /* Type-bound procedures.  */
-  gfc_traverse_symtree (f2k->tb_sym_root, &show_typebound);
+  gfc_traverse_symtree (f2k->tb_sym_root, &show_typebound_symtree);
+
+  --show_level;
+
+  show_indent ();
+  fputs ("Operator bindings:", dumpfile);
+  ++show_level;
+
+  /* User-defined operators.  */
+  gfc_traverse_symtree (f2k->tb_uop_root, &show_typebound_symtree);
+
+  /* Intrinsic operators.  */
+  for (op = GFC_INTRINSIC_BEGIN; op != GFC_INTRINSIC_END; ++op)
+    if (f2k->tb_op[op])
+      show_typebound_proc (f2k->tb_op[op],
+			   gfc_op2string ((gfc_intrinsic_op) op));
 
   --show_level;
 }
@@ -801,11 +825,7 @@ show_symbol (gfc_symbol *sym)
     }
 
   if (sym->f2k_derived)
-    {
-      show_indent ();
-      fputs ("Procedure bindings:\n", dumpfile);
-      show_f2k_derived (sym->f2k_derived);
-    }
+    show_f2k_derived (sym->f2k_derived);
 
   if (sym->formal)
     {
Index: gcc/fortran/gfc-internals.texi
===================================================================
--- gcc/fortran/gfc-internals.texi	(revision 151138)
+++ gcc/fortran/gfc-internals.texi	(working copy)
@@ -31,7 +31,8 @@
 @c @end tex
 
 @copying
-Copyright @copyright{} @value{copyrights-gfortran} Free Software Foundation, Inc.
+Copyright @copyright{} @value{copyrights-gfortran} Free Software Foundation,
+Inc.
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.2 or
@@ -568,6 +569,7 @@ substring reference as described in the 
 
 @menu
 * Type-bound Procedures:: Type-bound procedures.
+* Type-bound Operators::  Type-bound operators.
 @end menu
 
 
@@ -652,6 +654,50 @@ expression of type @code{EXPR_COMPCALL} 
 except that its target procedure is of course a @code{SUBROUTINE} and not a
 @code{FUNCTION}.
 
+Expressions that are generated internally (as expansion of a type-bound
+operator call) may also use additional flags and members.
+@code{value.compcall.ignore_pass} signals that even though a @code{PASS}
+attribute may be present the actual argument list should not be updated because
+it already contains the passed-object.
+@code{value.compcall.base_object} overrides, if it is set, the base-object
+(that is normally stored in @code{symtree} and @code{ref} as mentioned above);
+this is needed because type-bound operators can be called on a base-object that
+need not be of type @code{EXPR_VARIABLE} and thus representable in this way.
+Finally, if @code{value.compcall.assign} is set, the call was produced in
+expansion of a type-bound assignment; this means that proper dependency-checking
+needs to be done when relevant.
+
+
+@c Type-bound operators
+@c --------------------
+
+@node Type-bound Operators
+@section Type-bound Operators
+
+Type-bound operators are in fact basically just @code{GENERIC} procedure
+bindings and are represented much in the same way as those (see
+@ref{Type-bound Procedures}).
+
+They come in two flavours:
+User-defined operators (like @code{.MYOPERATOR.})
+are stored in the @code{f2k_derived} namespace's @code{tb_uop_root}
+symtree exactly like ordinary type-bound procedures are stored in
+@code{tb_sym_root}; their symtrees' names are the operator-names (e.g.
+@samp{myoperator} in the example).
+Intrinsic operators on the other hand are stored in the namespace's
+array member @code{tb_op} indexed by the intrinsic operator's enum
+value.  Those need not be packed into @code{gfc_symtree} structures and are
+only @code{gfc_typebound_proc} instances.
+
+When an operator call or assignment is found that can not be handled in
+another way (i.e. neither matches an intrinsic nor interface operator
+definition) but that contains a derived-type expression, all type-bound
+operators defined on that derived-type are checked for a match with
+the operator call.  If there's indeed a relevant definition, the
+operator call is replaced with an internally generated @code{GENERIC}
+type-bound procedure call to the respective definition and that call is
+further processed.
+
 
 @c ---------------------------------------------------------------------
 @c LibGFortran