#pragma exhibit -- permit verification of resources available in a scope

[leeo3264]

#pragma exhibit Proposal

Motivation
Facilitate an exploration of the effects of the various accessibility modifiers on the visibility of resources to a scope in C#. The eventual goal is to document deficiencies in the current accessibility system in the language and propose remedies, however it may also be useful as a developer’s tool.

Purpose
The #pragma exhibit directive is designed to check the availability of members of the scope in which it appears. It requires in that scope
the inclusion of an abstract class to serve as an exhibit, which the compiler will parse to verify the correct name, signature, and expected
availability of members from other namespaces or class types.

Structure
#pragma exhibit <etype> <NamespaceOrClass> <ExhibitClass>
• <etype> : The type of exhibition, exactly one of complete, employment, or partial.
◦ #pragma exhibit complete <NamespaceOrClass> <ExhibitClass>
Ensures that <ExhibitClass> contains a restatement of all top-level elements of the target namespace or class,
except for nested namespaces and nested types in classes.
◦ #pragma exhibit employment <NamespaceOrClass> <ExhibitClass>
Similar to exhibit complete except that the exhibition only contains the top-level elements of the namespace or class currently used
in the scope containing the pragma directive. This may be employed to document the dependencies of the code in the scope.
◦ #pragma exhibit partial <NamespaceOrClass> <ExhibitClass>
similar to the other exhibit types, but with no restrictions to completeness; a subset of the available resources is given for verification.
This may be useful for presenting to a developer a menu or summary of intended resources to employ.
• <NamespaceOrClass> : The namespace or class whose top-level members are to be verified. This must be accessible from the
scope containing the pragma directive.
• <ExhibitClass> : The name of an abstract class specifying the expected members. This is required to reside in the scope containing
the pragma directive.

Example -- csharp --

// Provide an example namespace and class
namespace ExampleNamespace
{
    public class ExampleClass
    {
        public ExampleClass( int initialValue ) // Constructor
            { ExampleField = initialValue; }
        public int ExampleField; // Field
        public int ExampleProperty { get; set; } // Property
        public void ExampleMethod() // Method
        { Console.WriteLine( "This is an example method." ); }
        public event EventHandler ExampleEvent; // Event
        public delegate void ExampleDelegate( string message ); // Delegate

        private int[] numbers = new int[ 10 ];
        public int this[ int index ] // Indexer
        {
            get { return numbers[ index ]; }
            set { numbers[ index ] = value; }
        }
        ~ExampleClass() // Finalizer
        { 
            // Cleanup code
        }
    }

    public interface IExampleInterface { }
    public struct ExampleStruct { }
    public enum ExampleEnum { Value1, Value2, Value3 }
    public delegate void ExampleDelegate( string message );
}

namespace VerifyingExampleNamespace
{
    // verify the contents of ExampleNamespace
    #pragma exhibit complete ExampleNamespace EExampleNamespaceExhibit

    abstract class EExampleNamespaceExhibit
    {
        class ExampleClass { }
        interface IExampleInterface { }
        struct ExampleStruct { }
        enum ExampleEnum { Value1, Value2, Value3 }
        delegate void ExampleDelegate( string message );
    }

    // In this scope, the members of EExampleNamespaceExhibit are verified
    // through the pragma to match all of the top-level members of
    // ExampleNamespace.  Any omission or misstatement of the resources of the
    // target namespace is a compile-time error.


    // verify the contents of ExampleClass in the namespace ExampleNamespace
    #pragma exhibit complete ExampleNamespace.ExampleClass EExampleClassExhibit

    abstract class EExampleClassExhibit
    {
        EExampleClassExhibit ( int initialvalue ) { } // Constructor
        int ExampleField; // Field
        int ExampleProperty { get; set; } // Property
        void ExampleMethod() { }
        event EventHandler ExampleEvent;
        delegate void ExampleDelegate( string message );
        abstract internal int this[ int index ] { get; set; } // Indexer
        ~EExampleClassExhibit() { } // Finalizer
    }

In this example, the EExampleNamespaceExhibit abstract class includes all of the top-level accessible members of ExampleNamespace.
The #pragma exhibit complete directive ensures that the compiler verifies the availability and correctness of these members within the
scope containing the pragma. Similarly, EExampleClassExhibit shows all of the accessible top-level members of
ExampleNamespace.ExampleClass .

Additional Considerations
• Nested Namespaces: Nested namespaces are not included in the exhibit class, as they are always publicly accessible. The contents
of nested namespaces may be verified with additional exhibits – similarly for nested types in class types.
• Compile-Time Verification: The pragma directive ensures that the compiler checks the availability of members at compile time,
providing a robust mechanism for managing and validating resources. Any failure simply results in a compile-time error.
• Exhibit Accessibility: The abstract class for the exhibit is not expected to be used outside the scope or instantiated, thus in it the use
of the public or other accessibility modifiers is not necessary, other than to conform specific rules for abstract classes. For instance,
indexers declared in an abstract class cannot be marked private, and thus in the example it is declared internal. Otherwise declaring
the accessibility of members in the abstract class employed for the exhibit will be of no consequence.

Utility
• This proposal is useful for exploring accessibility modifiers and documenting dependencies. It provides a robust mechanism
for managing and validating resources at compile time, which may be beneficial for developers.

[CyrusNajmabadi]

Can you fixup your markdown? It's very difficult to make out what you're asking for with the incorrect code fencing everywhere. Thanks.

[leeo3264]

Fixing the markdown is definitely a priority. If it helps, I have my original manuscript
pragma exhibit propoasl.odt

[CyrusNajmabadi]

It provides a robust mechanism for managing and validating resources at compile time, which may be beneficial for developers.

Why is a language feature needed for this. This seems just as possible with an analyzer that does the same management/validation.

[leeo3264]

Indeed I can envision an analyzer generating the abstract class that has members that correspond to the contents of a namespace or class in another assembly. The pragma proposal just validates that the abstract class is a true exhibition at compile time.

[colejohnson66]

So the idea is that you can write a class that implements the same shape as some arbitrary abstract class, but without actually deriving from it? What is the purpose of that? Why not just derive from the abstract class?

Also, why would this need to be a #pragma directive and not an attribute? #pragma directives change compiler behavior and, if I recall correctly, are invisible to analyzers, whereas attributes can be used by analyzers. As @CyrusNajmabadi said, an analyzer is the best option for this unique decision.

[leeo3264]

Actually, it is the other way around. The class (or namespace) in another assembly is in a way projected to the working scope as an unused abstract class. The pragma proposal is just a verifier at compile time. The main motivation for the pragma proposal is to succinctly document accessibility changes in an upcoming package proposal -- even so I can envision having a verified abstract class functioning as an exhibit being useful when looking for dependencies or analyzing code.

[siegfriedpammer]

This looks like a lot of code duplication and cumbersome to maintain/keep in sync. If you want to document/verify the API surface of your application, there are other tools, like for example https://github.com/dotnet/roslyn-analyzers/blob/main/src/PublicApiAnalyzers/PublicApiAnalyzers.Help.md which was developed by the Roslyn/C# language design team.

Generally, this is not something that needs a language change, it can be expressed using analyzers and a DSL. Language changes are very costly to implement and I'd rather see language features that increase the expressiveness of the language and enable new things such as extensions or discriminated unions.

The eventual goal is to document deficiencies in the current accessibility system in the language

What do you mean by that?

[leeo3264]

The idea of implementing a pragma adds a tool without requiring a language change. The main utility is simply to verify the presence of a resource. In a development environment the resource pool can be in flux -- so this permits dependencies to be cleanly shown. If I use a resource that is deprecated and removed, that is caught by the pragma rather than deep in the code.

It basically states: "I understand these resources are available here". Nikalus Wirth's successor to Pascal had required lists of resources that are shared across assemblies -- that has since proven to be redundant and his successor languages indicated the proposed sharing of a resource right at its definition. Still, seeing a verified list of employable resources may be helpful at the development stage.

The employment of an analyzer is definitely an aid to the proposal. If I include a summary generated from the analyzer (the exhibit abstract type in this case) the pragma proposal automatically guarantees that it is correct at compile time -- rather than having to continuously reverify its presence. Granted, an analyzer can be automatically programmed to perform this guarantee, but that is just a design choice. or style -- implementing it as a pragma right in the language clearly documents the intention but again, that is just a design style.

regarding "the eventual goal is to document deficiencies in the current accessibility system in the language" -- current accessibility specifications document the consequence of the accessibility modifiers in a very laborious fashion. I just hope to be more succinct with examples.

[HaloFour]

Adding a pragma would be a language change. You could accomplish the compile-time verification through just an analyzer, which could be configured through attributes pointing to the "exhibit" classes and can emit error diagnostics if the API does not match.

[leeo3264]

Perhaps I misstated. I interpret a pragma as a compiler feature, and not a language feature. I'll grant you that tailoring an analyzer to react to attributes is probably a superior implementation -- what I'm trying to do is document consequences of accessibility modifications inline with the code itself to keep examples succinct. It might just as well be an aid to certain developers also.

[333fred]

I interpret a pragma as a compiler feature, and not a language feature

It is not. It is part of the language syntax, and is a full change to the language.