1.1 Design and Extension Philosophy

RD-VBA is not a reinterpretation of VBA - it is an effort to fully realize its specification.

The language core shall remain strictly compatible with MS-VBAL specifications, but it shall not be treated as a fossilized language, either.

1.1.1 Platform Extensions

🧩 RDCore operates on a capability-driven host model, where extended features may or may not be available depending on the execution environment. Extensions must be resilient to partial capability availability.

The platform is intended to be massively extended through first and third party extensions whose capabiliites are negociated with the RD-VBA environment host.

Note

In the RDCore ecosystem, the default RD-VBA environment host is rdc.exe. Other LSP clients may eventually join the family, but would be packaged separately from the RDCore language platform.

1.1.2 Language Core Extensions

Where the specification defines implicit behaviors, RD-VBA may choose to make these behaviors explicit, provided that:

  • The underlying semantics remain unchanged;
  • Exiting code continues to behave identically;
  • The added explicitness improves clarity, diagnostics, or tooling.

This includes features such as:

  • The comment annotations syntax from the legacy Rubberduck VBIDE add-in;
  • The introduction of an explicit coercion operator for semantic disambiguation;
  • The explicit addition of runtime semantics for a unary '+' operator;

These additions do not alter the language - they reveal it.

✅ A valid language core extension makes explicit what was implicit.
❌ An invalid language core extension introduces new semantics.

Examples of valid language core extensions include:

  • Introducing a new Option Strict directive to restrict existing static and/or runtime semantics by issuing error diagnostics or new, explicitly specified compile-time errors.
    • ...provided that no new tokens are introduced without also introducing the native capability to output them as comment annotations, keeping the output strictly compliant with MS-VBAL.
  • Leveraging the obiquitously permitted late-binding and duck-typing to introduce and surface inherent deferred types to design-time symbols, enabling LSP-level enhanced capabilities around auto-completion lists, notably.

Examples of invalid language core extensions include:

  • Exposing symbols for descriptors and other internal meta-types that could introduce reflection semantics to the language;
  • Building on MS-VBAL explicitly specifying every Variant input in the standard library as expressions to be evaluated to introduce deferred execution semantics to the language (i.e. leveraging meta-types to introduce new semantics);
    • This would effectively make functions a first-class RD-VBA runtime entity that can be passed around as values - this should not be done without a careful and thorough consideration of the implications on the rest of the semantic model.

This however, does not make them invalid extensions in the RDCore ecosystem: each and every single one of these could be great platform-level extensions.

1.1.3 Core Semantic Flags

The language core features an analytical pipeline that attaches detailed semantic flags to abstract syntax tree (AST) nodes. See for example ComparisonOperatorSemanticFlags.

These flags are spec-driven and designed to describe the semantic reality of an operation, without any restraint or judgement.

The existence of a semantic flag is typically motivated by the presence of a branch or condition in the specified semantics: if the effective type of an operation evaluates a VBNullType differently than a VBNumericType, then the semantic flags for that operation should reflect the NullEffectiveType flag, and if the specifications mention something about a NaN operand, then there should be a HasNaNOperand semantic flag to reflect this fact.

👉 DO create new core semantic flags as needed to accurately reflect the semantic reality of an operation.
❌ DO NOT create new core semantic flags that no specified (RD-VBAL) semantics justify.

🧩 Extensions CAN (and should) enrich a semantic context well beyond the responsibilities of the language core, with diagnostics issued by analyzers that can inspect the complete semantic reality of the application: semantic flags aim to expose all the facts of this reality.

1.1.4 Core Diagnostics

🧩 RDCore.Diagnostics is the core platform extension responsible for issuing all language core diagnostics. Additional extensions (first or third party) may provide additional/advanced diagnostics to the LSP orchestration layer.

The schema of a diagnostic is specified by LSP 3.17 § Diagnostic, and includes a Code that the RDCore platform specifies as follows:

Format Description
VBC00000 Visual Basic Compilation error diagnostics
VBR00000 Visual Basic Runtime error diagnostics
VBA00000 Visual Basic Application error diagnostics
RDC00000 RDCore core diagnostics
RDX00000 RDCore extension diagnostics

The 00000 numeric portion of a diagnostic code depends on its nature:

  • Errors issued from the parser are normally syntax errors reporting a VBCompileErrorId with a numeric value between 42 and 999;
  • Errors issued from the static semantics analysis pass are compilation errors reporting a VBCompileErrorId with a numeric value greater than or equal to 9300;
  • Errors issued from a language core extension that are compilation errors, reporting a VBCompileErrorId with a numeric value between 8000 and 9299;
  • Errors issued from the runtime semantics analysis pass are runtime errors reporting a VBRuntimeErrorId with a numeric value corresponding to its MS-VBAL specified error code;
  • Errors raised from workspace source code have an unspecified VBA00000 diagnostic code that is defined by the custom error code raised in the workspace program;
  • Any other language core diagnostics issued from RDCore.Diagnostics are to be documented under a RDC00000 code;
  • Any other first-party platform extension diagnostics issued from any other extension, shall be documented under a RDX00000 code in the documentation pertaining to that extension.
  • Third-party patform extension diagnostics may be reported under an available RDX code, or a reasonably publisher-specific 3-letter prefix.

Such a clean separation of application-defined errors and of specified semantic runtime errors is compliant with MS-VBAL; it is the MS-VBA implementation that weakly separates them using a vbObjectError constant, but the proper use of this constant was historically misunderstood and the distinction between run-time and application errors doesn't really exist. RDCore removes the need for that constant by internally representing them as different error metadata types, which clarifies their origin before they even reach the runtime.

The description of compilation and run-time errors shall match exactly with the corresponding MS-VBA descriptions. However, all RD-VBA trace messages can include an optional verbose message that the platform shall use to further explain the reason behind any error being raised, independent of (or supplemental to) any other verbose content including but not limited to execution stack traces.

Warning

A third-party extension that issues already-documented first-party diagnostic codes may be required to modify its codes before it can be distributed through the platform's official distribution channels. This ensures that all diagnostic codes published under the platform remain traceable and searchable online.

1.1.5 Extension Manifest

RDCore extensions are discovered by the environment host during the composition of the host environment. The extension manifest is a small text file in a human-readable JSON serialized format that describes the extension to the platform.

By default, the environment host may restrict capabilities request by unsigned or untrusted extensions. Users may override these defaults through configuration or development modes;

Important

Extension packages must include a signed manifest that binds metadata to the distributed artifacts (the extension server executable).

1.1.5.1 Schema

{
    "Name": "string",
    "Title", "string",
    "Version", "version-string",
    "Publisher", "string",
    "PublisherUrl", "url-string",
    "Description", "string",
    "Signature", "string"
}
Attribute Description
Name The file name of the extension executable (.exe) located in the same folder as the manifest file.
Title The friendly name, or title of the extension; must match the name of the folder it is located in.
Version A semantic version string minimally identifying the Major.Minor.Build version of the extension; must match the assembly file version of the extension executable (.exe) file.
Publisher The name of the publisher (copyright holder) of the extension.
PublisherUrl A reasonably short website URL provided by the publisher.
Description A short description of the extension.
Signature The SHA512 file-hash signature of the extension executable (.exe) file; must match exactly with the file-hash of the discovered extension executable (.exe).

1.1.5.2 Validation

An extension manifest discoverd under the platform's ./extensions folder must be validated by the host before the extension can be authorized to execute. This validation occurs in layers and helps ensure only trusted extensions are allowed to run.

  • If platform extension configuration is NOT explicitly listing the Title of the extension as Allowed, a NotAllowed validation flag is issued;
    • The environment host may prompt to allow discovered extensions that don't appear in the platform extension configuration; whether the host prompts to allow, or automatically blocks non-configured extensions is dependent on the host implementation.
  • If platform extension configuration is explicitly listing the Title of the extension as Blocked, a Blocked validation flag is issued;
  • If the Title in the extension manifest mismatches the folder location it was discovered in, a LocationMismatch validation flag is issued;
  • If the extension executable (.exe) named in the manifest is not found in the same folder as the manifest file, a FileNotFound validation flag is issued;
  • If the SHA512 file-hash signature in the manifest mismatches the SHA512 file-hash signature of the extension executable (.exe), a SignatureMismatch validation flag is issued;

See Validation Flags for more details.

If the validation result is NoFlags, the host may proceed to configure a client host for this extension server, start its executable process, and initiate the LSP connection handshake and capabilities exchange.

Tip

In order to facilitate building platform extensions, the rdc.exe host may be configured to allow unsigned extension builds using a --unsafe-dev-mode command-line flag.

1.1.6 Capabilities Provider

An environment host must implement IExtensionCapabilityProvider and provide all available extension capabilities.

This interface allows a host to determine whether certain extension capabilities should be enabled or not, through mechanisms that are implementation-dependent and may include but are in no way restricted to, the validation of an active subscription to said extended capabilities.

All platform extensions must gracefully handle being denied their extended capabilities by the capability provider. This includes:

  • TRACE output acknowledging the denied capabilities;
  • Responding to a LSP shutdown request and cleanly terminating upon a LSP exit notification from the environment host;

An abstract server application in the SDK should already handle these lifecycle events correctly, without needing any further configuration.

If an extension successfully registers any capability, its process continues to run and may handle a reduced set of LSP requests and notifications; otherwise the environment host requests the termination of the extension server process.

⏮️ RD-VBAL §1.0 Introduction | ⏭️ RD-VBAL §2.0 Computational Environment

Edit this page