3. Names, namespaces and imports

3.1 Root namespace and Global

CS-NAME-001. Global. denotes the actual CLR/global namespace root and bypasses the project's root namespace. It is valid in qualified type/member names, imports, aliases and absolute namespace declarations. Canonical casing is Global..

CS-NAME-005. A relative source namespace attaches beneath root_namespace. Without a configured root, ordinary namespace names resolve from the global root. Assembly name alone does not establish a root namespace.

Given the project root MyBank.Payments:

The compiler's source/build metadata is exposed through compiler; its fields are defined in chapter 26.

3.2 Automatic standard-library import

CS-NAME-002. Only the DirectSharp root is automatically available by default. Its subnamespaces are not all imported.

CS-NAME-003. The project setting auto_import_directsharp false disables the automatic DirectSharp root import. Omitting the setting, or writing auto_import_directsharp true, enables it. The disabled project uses explicit imports or qualification; manual imports remain available. This setting does not change Global qualification, import scope or automatic availability of any other namespace. It belongs inside the project declaration and requires a Boolean setting value.

project
    auto_import_directsharp false
    import DirectSharp
end project

The explicit import above remains valid after opting out. The opt-out does not remove an assembly/package reference or suppress a manually declared import.

DirectSharp.Runtime identifies the small runtime/compiler-support package, not a second user-facing standard-library root. The exact root API inventory is a library specification task.

3.3 Project-wide declarations

CS-PROJ-001. A project has one effective project ... end project declaration. A second declaration is a compile-time error with diagnostics identifying both declarations.

CS-PROJ-002. Project.ds is the recommended filename. The declaration determines its meaning; another ordinary .ds filename has the same semantics.

CS-NAME-004. Imports and aliases inside project apply project-wide. Outside it they are file-local. Assembly attributes belong in the project declaration.

CS-NAME-006. Imports accumulate. Conflicting aliases and ambiguous symbols produce compile-time errors; there is no last-declaration-wins rule. root_namespace has one effective value.

project
    root_namespace MyBank.Payments
    import Global.System.Text.*
    alias Json = Global.System.Text.Json.JsonSerializer

    assembly attributes
        Global.System.Reflection.AssemblyTitleAttribute("Payments")
    end attributes
end project

Assembly attribute binding follows the ordinary attribute model; the project declaration does not create a second attribute type system.

3.4 Wildcard imports

CS-NAME-007. Import patterns allow only a terminal *. Expansion occurs at compile time over known namespaces in the project and its references. A wildcard neither searches runtime directories nor dynamically loads assemblies.

import Global.System.Text.*
import Global.MyBank.Pay*

The first imports the known namespace tree beneath System.Text. The second matches known names with the MyBank.Pay prefix and their applicable descendants. Wildcards establish no precedence between exposed names.

Invalid forms:

import Global.MyBank.*.Services
import Global.MyBank.Pay?ents
import *

All violate the restricted wildcard grammar.

3.5 Aliases

CS-NAME-008. alias Name = qualified.name binds a compile-time spelling shortcut to a visible namespace, type, qualified static field/property, or enum member. It introduces no new CLR type, conversion, inheritance relationship or runtime object.

CS-NAME-009. A static-member alias names the member, not its current value. Each use of an alias to a property reads the property again.

alias utcNow = Global.System.DateTime.UtcNow
let first = utcNow
DoWork()
let second = utcNow

first and second need not be equal. Arbitrary expressions and calls are not alias targets:

alias invalid = Calculate()
alias alsoInvalid = a + b

An alias such as alias CustomerId = Guid is not a strong domain type. Class-local interface aliases are a separate explicit allowance in chapter 10.

Global.System.Text.StringBuilder can be represented by:

global::System.Text.StringBuilder

A type alias may become a C# using alias. A static-property alias can instead expand to the qualified member at each use:

var first = global::System.DateTime.UtcNow;
DoWork();
var second = global::System.DateTime.UtcNow;

3.7 Declaration collisions and contextual names

CS-NAME-010. Name identity is case-insensitive in source. Same-scope declarations that differ only in spelling case collide. Imported namespaces do not gain priority from import order, and ambiguous imported short names must be qualified rather than selected arbitrarily.

CS-NAME-011. A constructor's arguments.name is a compile-time reference to the named input, not a universal runtime dictionary. When a bare name is ambiguous between a parameter and a case-insensitively matching member, require explicit qualification; self.Name names the member and arguments.name names the parameter. The compiler must not silently change meaning based on identifier case.

CS-NAME-012. Contextual compiler names are available only in their defined contexts: result in result-producing actions, value/field in relevant property accessors, self for an instance/extension receiver, Cancellation in explicit async actions and owned producer contexts, and CurrentLoop/LastLoop/LastAttempt where their constructs establish context. An unavailable contextual name is a compile-time error, not an ambient nothing value.

External CLR metadata retains its original names and accessibility. The DirectSharp binder applies source identity and signature rules before C# emission; lowercasing every emitted CLR identifier is not a conforming implementation.

Specification contents · Previous: 2. Lexical structure · Next: 4. Types