Appendices

A. Language vocabulary

Keywords are case-insensitive. Canonical source uses lowercase. An indivisible multiword token uses snake_case; compositional grammar keeps independently meaningful words separate. end if is a closing keyword followed by a construct qualifier, not end_if. Escaped identifiers use @ where a name would otherwise conflict with language vocabulary.

The tables group vocabulary by its language role. A word's appearance in a contextual grammar does not make an arbitrary .NET member with that name a globally reserved keyword.

Gate, IConsumable<T>, IConcurrentConsumable<T>, ILiveConsumable<T>, Consumables, ServiceProvider, ServiceScope, ServiceScopeFactory, MainServiceProvider, Chars, Unicode and ordinary type names such as String belong to type/library binding. GetService, RuleFor, NotEmpty, AddDbContext, WriteLine and SaveChangesAsync are APIs, not newly reserved language statements.

Retired forms must not be inferred from this inventory. Current source uses constructor rather than on create, for_each rather than for each, try_get rather than tryget, and contract otherwise rather than or throw. Core does not define deep_copy_of, has_any_flag, has_no_flag, is default, a validation keyword DSL, a project feature-activation block or a standalone generate construct.

B. Operator binding

Parentheses explicitly group expressions without changing once-only operand evaluation in source order. The following groups are ordered from highest to lowest binding:

convert operand to T consumes one immediate operand; its completed conversion binds strongly as defined in chapter 8. It does not absorb surrounding arithmetic without parentheses. Normal binary operators associate left-to-right unless specified otherwise; this table does not admit invalid operand types or general mathematical comparison chains. Predicate-local type/pattern grammar remains governed by its construct rules.

let total = convert (subtotal + tax) to Integer
let next = (convert amount to Integer) + 1
let eligible = not (balance > limit) and isActive

Composite conversion sources require parentheses. Bitwise/comparison/predicate combinations should use parentheses wherever grouping would otherwise obscure the intended operation. Assignment is a statement-context operation, not a freely nestable C-style assignment expression.

C. Predicate contracts

Scalar defaults count as empty: 0, false and Guid.Empty are examples. String absence and "" are empty; " " is not empty but is whitespace. A non-absent collection with zero items is empty without requiring equality to a particular empty collection object. Enumerable emptiness may probe enumeration; an efficient non-enumerating check is permitted where observably equivalent.

An ordinary reference type with no meaningful non-absent default/equality contract is empty only when absent. No structural equality is invented for this test. value = default is the contextual default comparison; is default is not a current predicate.

is not negates an applicable predicate. Explicit _case_sensitive String forms override the normal case-insensitive comparison for their operation; they do not change identifier binding. Built-in predicates are distinct from recognized Boolean Is*/Has* members, which still bind as normal APIs. Email, IBAN, JSON and telephone policies belong in libraries.

D. Conversion contracts

A conversion selects one recognized step. It does not search A→B→C chains, serializers, TypeConverter, unrestricted reflection or arbitrary Convert.ChangeType fallbacks.

Target-typed String literals may initialize recognized targets or satisfy unambiguous parameters. An arbitrary runtime String does not implicitly parse merely because assignment has a target type: use text as T or convert text to T. One accessible exactly-one-String constructor can participate in direct construction; compiler selection does not execute that user constructor during compilation.

Explicit target-typed fractional-to-integral narrowing truncates toward zero and warns about possible loss. This does not silently add lossy conversions to unrelated overload resolution. Untargeted fractional literals infer Decimal. Integer-operand / yields a fractional Double result; div truncates its quotient toward zero.

tryconvert is not try_get convert: the former requires a real safe protocol; the latter explicitly catches normally catchable computation failures. Ordinary culture-stable conversions use recognized deterministic contracts. Explicit .NET Parse/TryParse APIs remain available for application-specific culture, styles and format policy.

E. Construct grammar summary

These shapes describe already-defined constructs. Brackets denote optional grammar, braces repeated grammar and capitalized labels syntactic categories. They are notation rather than literal DirectSharp source.

Project       := project { ProjectSetting } end project
AutoImport    := auto_import_directsharp (true | false)
Action        := [Access] [async] action Name(Parameters)
                 [returns Type | yields Type] Body end action
Await         := await UnaryExpression
TaskCapture   := task_of(Expression)
Constructor   := [Access] constructor(Parameters) Body end constructor
Class         := [Access] class Name [GenericParameters] [ClassHeader]
                 { Member } end class
InterfaceBody := implements Interface { Member } end implements
ClassKind     := [Access] class kind Name [GenericParameters]
                 { KindContribution } end class kind
Extension     := extension Type { ExtensionAction } end extension
If            := if Condition then Body { elseif Condition then Body }
                 [else Body] end if
Enumeration   := [concurrent] for_each Binding in Source [LoopInputs]
                 Body end for_each
Consumption   := [concurrent] consume Binding from Source [LoopInputs]
                 Body end consume
Concurrent    := concurrent (all | first | any) [PublishedResults]
                 [with Inputs] Body end concurrent
RunCall       := [ResultBinding =] run Invocation
RunBlock      := [ResultBinding =] run Body end run
GateRegion    := enter Expression [with Inputs] Body leave
AtomicRegion  := atomic Body end atomic
AtomicSwap    := atomic swap(Location, Location)
Extraction    := let from Expression { ExtractionLocal } end let
ConditionalExtraction := let_if from Expression { ExtractionLocal } end let_if
ExtractionLocal := Identifier [ as Type ] = Expression
Needs         := needs { NeedDeclaration } end needs
Services      := services Name [Parameters] Body end services
Using         := using ResourceDeclarations Body end using
Use           := (use | use_if) Expression [Refinement] Body end (use | use_if)
TryGet        := try_get Expression | try_get Body take Expression end try_get
Metadata      := attributes AttributeList | attributes { Attribute } end attributes
Description   := description String

Full type/member/pattern/parameter rules in the chapters constrain these shapes. The notation does not permit every combination mechanically: resource ownership, async ABI, legal attributes, constructor placement and supported concurrent sources still apply. Qualified endings verify the construct they close. Keyword normalization does not fuse closing qualifiers.

An applicable generic declaration places its parameter list after the declaration name and its restrictions in the header. The Action shape above is the nongeneric case; generic actions use that same callable/result model with these additional pieces:

GenericParameters := < of Identifier { , Identifier } >
GenericArguments  := < of Type { , Type } >
GenericConstraint := where Identifier
                     ( inherits Type | implements Type | has constructor )

These angle brackets are literal delimiters in the source. Commas separate parameters/arguments; each nested constructed type has its own list. Chapter 4 defines the legal CLR restriction boundary, and the generic reference shows complete declarations.

F. Required diagnostic conditions

The specification names conditions rather than inventing implementation diagnostic numbers.

Warnings/analyzers address cases that cannot be statically proved, such as imported aliases hiding shared mutation or opaque registration graphs. A diagnostic must explain the actionable source condition and preserve relevant DirectSharp locations. Backend compilation success does not excuse accepting a source program whose language contract requires rejection.

G. Library contracts referenced by the language

The language's required library relationships are distinct from grammar and from optional conveniences.

Application-facing APIs use the DirectSharp namespace. The implementation is largely C#/.NET and may use a small required runtime assembly. The language does not prescribe an invented final interface signature for every helper: an API must implement the observable contract while preserving ordinary .NET compatibility. Optional mapping, serialization, copying and framework adapters remain separate packages/capabilities.

H. Version and backend scope

This specification describes the DirectSharp v1.0 core design and its initial .NET/C# backend relationship. The language semantics are independent of a particular SDK, runtime release or editor.

Source semantics, CLR representation and compiler/runtime package versions are separate compatibility concerns. A reference C# example illustrates semantics within its shown context; it is not a universal promise about all historical .NET targets. Imported libraries keep their own versioned API contracts. Optional libraries/features do not become core language guarantees merely by being available through a reference.

Specification contents · Previous: 28. Reference C# lowering