To: J3                                                     J3/24-105r3
From: Aury Shafran & Brad Richardson
Subject: Requirements and specs for simplified template procedures
Date: 2024-February-28

References:  24-107, 22-120r5, 22-151r3, 22-154r5, 23-007r1

1. Introduction
===============

There have been comments that the current template syntax is verbose.
This paper proposes a simplified method for the common case where a
template contains only a single procedure. We will call these
"simplified template procedures" (STP).

Note: This paper introduces illustrative syntax that uses curly braces
      rather than parentheses for deferred argument lists and
      instantiation argument lists.  Our motivation is to avoid
      ambiguity in the syntax where an STP is instantiated and the
      resulting procedure is referenced in a single statement.  (See
      final example below.)


A clarifying example is provided here for the canonical swap template.
The existing verbose syntax permits the following implementation:

    template swap_tmpl{T}
        type, deferred :: T
    contains

       subroutine swap(a, b)
          type(T), intent(inout) :: a, b
          type(T) :: tmp
          tmp = a
          a = b
          b = tmp
      end subroutine swap
    end template

    ...
    instantiate swap_tmpl{my_T}
    instantiate swap_tmpl{real}, only: swap_real => swap
    instantiate swap_tmpl{integer}, only: swap_integer => swap
    ...
    call swap(a, b)
    call swap_real(x,y)
    call swap_integer(i,j)

Illustrative syntax for a simplified version is the following:

    subroutine swap{T}(a, b)
        type, deferred :: T
        type(T), intent(inout) :: a, b
        type(T) :: tmp
        tmp = a
        a = b
        b = tmp
    end subroutine swap

    ...
    ! Long form instantiation:
    instantiate swap{my_T}
    call swap(a,b)

    ! Inline instantiation
    call swap{real}(x, y)
    call swap{integer}(i, j)

2. Requirements
===============

Requirements for STPs:

  a. It should be possible to easily convert an existing,
     non-templated, procedure to an STP.
  b. An STP should support deferred arguments, analogous to those of
     an ordinary template construct.
  c. It should be possible to reference an instantiation of an STP as
     a normal procedure.
  d. It should be possible to instantiate an STP and reference the
     resulting procedure in a single statement.  It should also be
     possible to separately instantiate an STP to be referenced
     subsequently.
  e. An STP should enforce type-safety (aka "strong concepts").
  f. Instantiations of an STP with the same instantiation arguments
     should be the same procedure.  (As with normal templates.)
  g. An STP shall be defined within a program unit.

3. Specifications
=================

  a. An STP definition is a procedure definition with additional
     syntax to accommodate a deferred argument list.  The
     specification section of an STP is the union of a
     template-specification-part and a specification-part.

  b. An STP can be instantiated in the specification section using
     an INSTANTIATE statement.

For example (see example in introduction):

    instantiate swap{real}
    real :: a, b
    a = 1.0
    b = 2.0
    call swap(a, b)

  c. The single statement instantiation-plus-reference of an STP
     should look like a conventional procedure reference with minimal
     additional syntax for instantiation arguments.

Example 1: Single statement invocation:

    real :: a, b
    a = 1.0
    b = 2.0
    call swap{real}(a, b)

Example 2: Single statement declarations
    ! instantiate initial target of procedure pointer
    procedure(), pointer :: my_swap => swap{real}
    ! provide interface for dummy procedure
    procedure(swap{real}) :: dummy_proc

Example 3: Single statement procedure actual argument
    call do_something(x, swap{real})


4. Nominal plans for syntax
===========================

To avoid ambiguities, the syntax for instantiaton and deferred
arguments will use "{" and "}" as delimiters.  The generics syntax
paper will be updated to reflect this change.

===END===