To: J3                                                     J3/24-161r1
From: generics
Subject: Edits for TEMPLATES: Introduction and deferred arguments
Date: 2024-October-22
References: 24-125r5, 24-126r4, 24-127r4

Introduction:
-------------

This is the first of 5 papers that provide edits for the approved
syntax for templates.

Section 1:
----------

* Introduce new clause after clause 19: Scope, association, and
  definition


20 Templates

20.1 Template semantics

A template is a scoping unit which is parameterized by deferred
arguments and can contain declarations, specifications, and
definitions.  Instantiation of a template occurs via association of
instantiation arguments with deferred arguments and yields concrete
(i.e., non-parameterized) instances of entities defined with the
template.

20.2 Deferred arguments

20.2.1 Declarations of deferred arguments

20.2.1.1 General

A deferred argument is an entity whose characteristics are determined
by its effective instantiation argument.  A deferred argument can be a
constant, procedure, or type and can appear in a REQUIREMENT
construct, TEMPLATE construct, or standalone template procedure.
Association with instantiation arguments occurs in the REQUIRE and
INSTANTIATE statements.

R2001  <deferred-arg> <<is>> <deferred-const-name>
               <<or>> <deferred-proc>
               <<or>> <deferred-type>

C2001 (R2001). A <deferred-arg> shall appear in a <deferred-arg-decl-stmt>
            or as the <function-name> or <subroutine-name> of an
            <interface-body>.

C2002 (R2001). A <deferred-arg> shall have at most one explicit
            specification in a given scoping unit.

Note: Deferred arguments are local identifiers and are not externally
      accessible.

A deferred argument declaration statement is used to declare
deferred arguments.

R2002 <deferred-arg-decl-stmt> <<is>> <deferred-arg-explicit-stmt>
                         <<or>> <require-stmt>

R2003 <deferred-arg-explicit-stmt> <<is>> <deferred-type-declaration-stmt>
                             <<or>> <deferred-const-declaration-stmt>
                             <<or>> <deferred-proc-declaration-stmt>

C2003 (R2003). A <deferred-arg-explicit-stmt> shall not have an
            <access-spec>.

20.2.1.2 Deferred types

A deferred type is a deferred argument that can appear in a type
specifier within a REQUIREMENT construct, TEMPLATE construct, or
standalone template procedure.

R2004 <deferred-type-declaration-stmt> <<is>>
         TYPE, <deferred-type-attr-list> :: <deferred-type-name-list>

C2004 (R2004). Each <deferred-type-name> shall appear in
               <deferred-arg-list> of the TEMPLATE, REQUIREMENT or
               standalone template procedure in which it appears.

R2005 <deferred-type-attr> <<is>> DEFERRED
                     <<or>> ABSTRACT
                     <<or>> EXTENSIBLE

C2005 (R2005). DEFERRED shall appear in each <deferred-type-attr-list>.

C2006 (R2005). The same <deferred-type-attr> shall not appear more than
            once in a given <deferred-type-attr-list>.

C2007 (R2005). A <deferred-type> entity shall not appear as
            <parent-type-name> in an EXTENDS attribute.

Note: A deferred type is not a <type-name>.  Consequently it shall not
      appear as a <derived-type-spec>, and so a deferred type
      may not be used in a <structure-constructor>.

A deferred type with the EXTENSIBLE attribute is an extensible derived
type. A deferred type with the ABSTRACT attribute is an abstract derived
type. A deferred type with the ABSTRACT attribute implicitly has the
EXTENSIBLE attribute, which can be confirmed with an explicit inclusion
of the EXTENSIBLE keyword in the <deferred-type-attr-list>.

Note: Examples of deferred type declarations are:

    TYPE, DEFERRED :: T1
    TYPE, EXTENSIBLE, DEFERRED :: T2
    TYPE, ABSTRACT, DEFERRED :: T3

Note: The distinction between deferred types that are extensible or not,
      and deferred types which are abstract or not, helps to ensure a
      processor can verify a template is internally consistent.  For
      example, a deferred type must not be permitted in a CLASS
      declaration if it might be instantiated as INTEGER. Additionally,
      a deferred type must not be permitted in a TYPE declaration if it
      might be instantiated with an abstract derived type. The following
      examples illustrate this point:

      SUBROUTINE S1_bad(T)(X, Y)
         TYPE, DEFERRED :: T
         TYPE(T)  :: X ! ok
         CLASS(T) :: Y ! invalid
      END SUBROUTINE

      SUBROUTINE S1(T)(X, Y)
         TYPE, DEFERRED :: T
         TYPE(T)  :: X ! ok
         TYPE(T)  :: Y ! ok
      END SUBROUTINE

      SUBROUTINE S2(T)(X, Y)
         TYPE, DEFERRED, EXTENSIBLE :: T
         TYPE(T)  :: X ! ok
         CLASS(T) :: Y ! ok
      END SUBROUTINE

      SUBROUTINE S3_bad(T)(X, Y)
         TYPE, DEFERRED, ABSTRACT :: T
         TYPE(T)  :: X ! invalid
         CLASS(T) :: Y ! ok
      END SUBROUTINE

      SUBROUTINE S3(T)(X, Y)
         TYPE, DEFERRED, ABSTRACT :: T
         CLASS(T) :: X ! ok
         CLASS(T) :: Y ! ok
      END SUBROUTINE

20.2.1.3 Deferred constants

A deferred constant is a deferred argument that can appear in constant
expressions within a REQUIREMENT construct, TEMPLATE construct, or
standalone template procedure.

R2006 <deferred-const-declaration-stmt> <<is>>
           <declaration-type-spec>, <deferred-const-attr-spec-list> ::
           <deferred-const-entity-decl-list>

R2007 <deferred-const-attr-spec> <<is>> <dimension-spec>
                           <<or>> DEFERRED
                           <<or>> PARAMETER
                           <<or>> <rank-clause>

R2008 <deferred-const-entity-decl>
     <<is>> <deferred-const-name> [ ( <array-spec> ) ]

C2008 (R2007). A <deferred-const-attr-spec-list> shall include both
            the DEFERRED and PARAMETER keywords.

C2009 (R2007). An entity declared in <deferred-const-declaration-stmt>
            shall be INTEGER, LOGICAL, or assumed-length CHARACTER.

C2010 (R2008). Each <deferred-const-name> shall appear in
            <deferred-arg-list> of the TEMPLATE, REQUIREMENT or
            standalone template procedure in which it appears.

C2011 (R2006). If <array-spec> appears in
            <deferred-const-declaration-stmt>, it shall be
            <implied-shape-spec>, <assumed-or-implied-rank-spec>,
            <explicit-shape-spec-list>, or
            <explicit-shape-bounds-spec>.

C2012 (R2006). If <implied-shape-spec>, <explicit-shape-spec> or
            <explicit-shape-bounds-spec> appears in
            <deferred-const-declaration-stmt>, then <lower-bound>
            shall not be specified.

C2013 (R2006). If <explicit-shape-bounds-spec> appears in
            <deferred-const-declaration-stmt>, then
            <explicit-bounds-expr> shall not appear as a lower bound.

Note: Deferred constants will always have default lower bounds.

Note: Examples of deferred constant declarations are:

    ! explicit shape
    INTEGER, DEFERRED, PARAMETER  :: x1
    INTEGER, DEFERRED, PARAMETER :: x2(3)
    INTEGER, PARAMETER :: v1(2) = [5,15] ! not a deferred constant
    INTEGER, DEFERRED, PARAMETER  :: x3(v1)

    ! implied shape
    INTEGER, DEFERRED, PARAMETER :: x4(*)
    INTEGER, DEFERRED, PARAMETER :: x5(*,*)
    INTEGER, DEFERRED, PARAMETER, RANK(2) :: x6

    ! assumed-or-implied-rank-spec
    INTEGER, DEFERRED, PARAMETER :: x7(..)

20.2.1.4 Deferred procedures

A deferred procedure is a deferred argument that can appear in
procedure references within a REQUIREMENT construct, TEMPLATE
construct, or standalone template procedure.  A deferred procedure's
interface shall be established in that construct. The interface of a
deferred procedure is established by its appearance in a
<deferred-proc-declaration-stmt> or as the <subroutine-name> or
<function-name> of an <interface-body> that appears in a deferred
interface block.

R2009 <deferred-proc-declaration-stmt> <<is>>
     PROCEDURE(<interface>), DEFERRED :: <deferred-proc-name-list>

C2014 (R2009). Each <deferred-proc-name> shall appear in the
            <deferred-arg-list> of the TEMPLATE, REQUIREMENT or
            standalone template procedure in which it appears.

C2015 (R2009). Each <subroutine-name> or <function-name> of an
            <interface-body> that appears in a deferred interface
            block shall appear in the <deferred-arg-list> of the
            TEMPLATE, REQUIREMENT or standalone template procedure in
            which it appears.

Note: The interface of a deferred procedure may be defined in terms of
      other deferred arguments.

Note: The following example declares deferred procedures F, S, and G:

   TYPE, DEFERRED :: T
   DEFERRED INTERFACE
      FUNCTION F(X)
         TYPE(T), INTENT(IN) :: X
         TYPE(T) :: F
      END FUNCTION
      SUBROUTINE S(Y)
         TYPE(T), INTENT(INOUT) :: Y
      END SUBROUTINE
   END INTERFACE
   PROCEDURE(F_I), DEFERRED :: G

===END===