DirectSharp Language Specification — v1.0

This specification defines DirectSharp v1.0: syntax, binding, evaluation, observable behavior and required diagnostics. Reference C# illustrates implementation strategies; the language rules remain authoritative.

The language guide teaches the language; the reference helps you locate a particular construct and its C# implementation account.

Contents

Choose a chapter below or use the alphabetical lookup. Each rule has a stable CS identifier and a direct link on its chapter page. Older links to sections of this page are retained below and lead to the corresponding chapter.

1. Scope and conformance

• 1.1 Semantics

• 1.2 Language and backend boundary

• 1.3 Core boundaries

• 1.4 Conformance

2. Lexical structure

• 2.1 Source text and files

• 2.2 Identifiers and casing

• 2.3 Comments and block endings

• 2.4 Statement boundaries

• 2.5 Numeric and Boolean literals

• 2.6 Quoted, raw and multiline strings

• Character and Unicode library contracts

• 2.7 Diagnostics and reference C# lowering

• Character helper exports

• Text transformation profiles

• Text layout and escaped contents

• Text helper exports and markup profiles

3. Names, namespaces and imports

• 3.1 Root namespace and Global

• 3.2 Automatic standard-library import

• 3.3 Project-wide declarations

• 3.4 Wildcard imports

• 3.5 Aliases

• 3.7 Declaration collisions and contextual names

4. Types

• 4.1 CLR types and generics

• 4.2 Absence and effective defaults

• 4.3 Default substitution and the CLR boundary

• 4.4 Diagnostics and default lowering

• 4.5 Runtime refinement and explicit conversion

• 4.6 Default and preset declarations

• 4.7 Real nullable values and declaration inference

• 4.8 Generic declarations and constraints

5. Declarations and scope

• 5.1 Local initialization

• 5.2 Readonly bindings

• 5.3 Name scope and iteration bindings

• 5.4 Object extraction

• Conditional extraction

• 5.5 Diagnostics and reference C# lowering

• 5.6 Multiple declarations and outer scope

6. Expressions and operators

• 6.1 Evaluation and operator binding

• 6.2 Arithmetic, division and remainder

• 6.3 Boolean negation and carried subjects

• 6.4 Conditional expressions

• 6.5 Presence fallback and explicit failure

• 6.6 Null-coalescing assignment

• 6.7 Chained assignment and mutation boundaries

• 6.8 Checked and unchecked overflow contexts

• 6.9 Diagnostics and reference C# lowering

• 6.10 Numeric helper member types

• 6.11 Property reads and required operations

7. Statements and control flow

• 7.1 Selection and results

• 7.2 Diagnostics and absence

• 7.3 Reference C# lowering

• 7.4 Conditions and case binding

• 7.5 Sequential enumeration and loop control

• 7.6 Loop metadata

• 7.7 Concurrent loop scheduling

• 7.8 Diagnostics and lowering

8. Actions and callables

• 8.1 Declarations, results and normal completion

• 8.2 Parameters and call binding

• 8.3 Block-form named calls and variable-length inputs

• 8.4 By-reference interoperability

• 8.5 Live parameter context

• 8.6 Action references, callable types and closures

• 8.7 Diagnostics and reference C# lowering

9. Classes, data and members

• 9.1 Classes, visibility and stored members

• 9.2 Properties and backing storage

• Empty parentheses on a property read

• 9.3 Constructors and initialization order

• 9.4 Promoted constructor inputs and named construction

• 9.5 Data records

• 9.6 Shallow copying

• 9.7 Class kinds

• 9.8 Required diagnostics

10. Inheritance and interfaces

• 10.1 Base classes and overriding

• 10.2 Interface intent and member mapping

• 10.3 CLR forwarding and diagnostics

11. Enums, flags and one-of types

• 11.1 Enum declarations and contextual members

• 11.2 Flags

• 11.3 One-of contracts

12. Contracts

• 12.1 Immediate requirements

• 12.2 Failure customization and exception category

• 12.3 Normal-exit postconditions

• 12.4 Entry snapshots

• 12.5 Reference lowering and diagnostics

13. Exceptions

• 13.1 Structured handlers

• 13.2 Retry and cleanup

• 13.3 Last completed attempt

• 13.4 Best-effort value acquisition and statements

• 13.5 Reference lowering and diagnostics

14. Receiver and resource scopes

• 14.1 Receiver scopes and conditional qualification

• 14.2 Bounded resource ownership

• 14.3 Lexical disposable locals

• 14.4 Authored cleanup and finalization

• 14.5 Reference lowering and diagnostics

15. Collections, enumeration and consumption

• 15.1 Literals, kinds and element types

• 15.2 Required indexed access

• 15.3 Dictionary coalescing assignment

• 15.4 Enumeration and LINQ

• Inclusive positional selection

• Count-taking selection and skipping

• 15.5 Destructive and forward-only consumption

• Consumable CLR contract and adapters

• 15.6 Reference lowering and diagnostics

• 15.7 Exported factories and sequence helpers

16. Predicates and pattern matching

• 16.1 Absence, emptiness, whitespace and type

• 16.2 String predicates and ordinary Boolean members

• 16.3 Wildcard and sequence patterns

• 16.4 Regex captures

• 16.5 Reference lowering and diagnostics

17. Async, iteration and concurrency

• 17.1 Async action contracts

• 17.2 Cancellation

• 17.3 Iterators and asynchronous streams

• 17.4 Structured child operations

• 17.5 Limits and timeouts

• 17.6 Concurrent enumeration and collection

• 17.7 Concurrent condition-driven loops

• 17.8 Asynchronous consumption

• 17.9 Gates and atomic state

• 17.10 Reference C# lowering and diagnostics

18. Lazy values

• 18.1 Declaration and typing

• 18.2 First use and publication

• 18.3 State inspection

• 18.4 Examples and diagnostics

• 18.5 Reference C# lowering

19. Events

• 19.1 Declaration and callable type

• 19.2 Imperative subscription

• 19.3 Declarative handlers

• 19.4 Reference C# lowering and failures

20. Dependency injection and services

• 20.1 Object dependencies

• 20.2 Effective contracts and initialization

• 20.3 Service identity and ownership

• 20.4 Composition and registration

• 20.5 Lifetimes and graph safety

• 20.6 Providers and scopes

• 20.7 Main provider and assisted construction

• 20.8 Reference C# relation

• 20.9 Missing-service exception construction

21. Attributes and documentation metadata

• 21.1 Declaration attributes

• 21.2 Structured descriptions

22. Extensions

• 22.1 Declarations and receiver

• 22.2 Binding and .NET relation

23. Features

• 23.1 Typed library adapters

• 23.2 Context and captured expressions

• 23.3 Catalog and boundary

24. Wrappers

• 24.1 Compile-time transformation

• 24.2 Targets and source fragments

• 24.3 Order, identity and hygiene

• 24.4 Diagnostics and source mapping

25. Preprocessing and includes

• 25.1 Conditional compilation

• 25.2 Typed definitions

• 25.3 Explicit substitution

• 25.4 Include semantics

26. Project model

• 26.1 Project-wide source configuration

• 26.2 Standard library and references

• 26.3 Compiler context

27. .NET interoperability

• 27.1 Ordinary CLR binding

• 27.2 Semantic boundaries

• 27.3 Public representation

28. Reference C# lowering

• 28.1 Purpose and conformance

• 28.2 Backend patterns

• 28.3 Cleanup and failure

• 28.4 Source maps and diagnostics

Appendices

• A. Language vocabulary

• B. Operator binding

• C. Predicate contracts

• D. Conversion contracts

• E. Construct grammar summary

• F. Required diagnostic conditions

• G. Library contracts referenced by the language

• H. Version and backend scope