2.0 RD-VBA Computational Environment

Note

This specification may be incomplete at this time.

MS-VBAL 2. VBA Computational Environment
VBA is a programming language used to define computer programs that perform computations that occur within a specific computational environment called a VBA Environment. A VBA Environment is typically hosted and controlled by another computer application called the host application. The host application controls and invokes computational processes within its hosted VBA Environment. The host application can also make availabel whtin its hosted VBA Environment computational resources that enable VBA programs to access host application data and host computational processes. The remainder of this section defines the key computational concepts of the VBA Environment.

👉 A RD-VBA program does run inside a host, but that host is rdc.exe rather than a Microsoft Office application. This does have yet-unresolved implications with regards to run-time interoperability, but should not affect general semantic compatibility.

🎯 rdc.exe is a command-line interface (CLI) application whose role is to assemble and host the library that is defined by the source code in a workspace program. This application is a work in progress.

  • In RD-VBA the concepts of a workspace and of a workspace folder are defined by the Language Server Protocol (LSP v3.17);
  • A workspace program is an executable in-memory representation of a RD-VBA workspace;
Tip

In LSP, a Workspace Folder corresponds essentially to a VBProject, and a Workspace corresponds to a project group.

This means a RD-VBA project must necessarily stand on its own and physically exist in the file system, which constitutes a fundamental paradigm shift for VBA code.

2.0.1 Supported Languages

A RD-VBA environment host may configure language-level restrictions or extensions, depending on the capabilities of the host application:

  • VBA refers to the Visual Basic for Applications language as per the MS-VBAL language specification;
  • VB6 largely refers to the same language definition, without the restrictions around attribute semantics and with a limited set of additional semantics;
  • VBX refers to extended RD-VBA; an environment host that signals support for this language code may support semantics that would be illegal in VB6 or VBA;
  • VBS refers to a diminished language specification that removes Option Explicit and declared types, forcing the use of duck-typing using implicit Variant declarations;
  • BASIC refers to a diminished language specification that removes procedure scopes, forcing the use of REM for comments (this makes annotations unavailable), line numbers and GoSub/Return for control flow; Do...Loop and Do...While constructs are undefined, forcing the use of While...Wend constructs; etc.

This list is prioritized but not intended to be exhaustive; additional dialects may be supported by different RD-VBA hosts.

🎯 The scope of the RDCore SDK minimally covers VBA, then VB6, then VBX, and so on.
👉 The LSP paradigm shift alone brings RD-VBA much closer to how VB6 works already.

2.0.2 Client/Server Capabilities

The RDCore platform is a set of cooperating processes — an LSP client (rdc.exe in client mode), the language server, the parsing server, the RD-VBA environment host (rdc.exe in host mode), and any number of extension servers. Every link between two of these processes is a JSON-RPC connection that carries the standard LSP initialize/initialized handshake plus a second, non-LSP handshake that exchanges platform capabilities.

The LSP layer is kept pure LSP: platform capabilities do not ride on the LSP initialize experimental field. They are exchanged by a dedicated request immediately after initialized.

2.0.2.1 The rdcore/platform/initialize handshake

Once the LSP initialized notification has been sent on a platform connection, the connecting side sends an rdcore/platform/initialize request (client → server) and awaits the response before considering the connection ready.

Message Shape
Request — PlatformInitializeParams ExpectedComponent: the CoreServerComponent the caller believes it is connecting to. Expected: a CorePlatformClientCapabilities describing the capabilities the caller expects the peer to provide.
Response — PlatformInitializeResult Component: the peer's own CoreServerComponent. Provided: the flat list of capability type names (e.g. "ParseFullDocument") the peer actually provides.

The responding side builds Provided by reflecting the [assembly: ProvidesCorePlatformClientCapability<T>] attributes declared on its entry assembly, so a component's capability set is a compile-time property of the build rather than runtime configuration. The rdcore/platform/initialize method itself is answered by a handler the SDK registers on every RDCore server (alongside the LSP shutdown, exit, and $/setTrace handlers).

Note

The handshake is currently informational. The response is retained (IRDCoreClientApp.PlatformInfo) and logged, and PlatformInitializeResult.Provides<T>() lets a caller test for a capability, but the platform does not yet refuse a connection whose peer reports the wrong component or a missing required capability. Enforcement is a later milestone.

2.0.2.2 Platform components

CoreServerComponent Process Role
ClientApp rdc.exe (default) An LSP client. Cannot be started by another platform process. Also runs in command mode (rdc.exe <verb>), which advertises the CliCommand capability.
LanguageServer RDCore.LanguageServer.exe Platform coordinator; owns the child servers.
ParsingServer RDCore.ParseServer.exe Stateless syntax service.
EnvironmentHost rdc.exe with RDCORE_MODE=host Owns the RD-VBA runtime environment.
Extension (varies) A platform extension server. Discovered from its extension.manifest.json and brought up by the language server during platform assembly.

2.0.2.3 Defined capabilities

This catalogue is intended to exhaustively document the platform capabilities the SDK defines. Each capability is a CorePlatformClientCapability record and, where it implies an out-of-band request, a non-LSP method.

Capability Method Provided by Description
ParseFullDocument rdcore/parser/document ParsingServer Lets the language server request a parse result containing the full syntax tree of a specified workspace document.
DefineSymbols rdcore/host/symbols/define EnvironmentHost Lets the language server send a module's member symbol descriptors to the environment host for definition in its runtime session.
CliCommand (none — in-process CLI dispatch) ClientApp, Extension Advertises that the declaring component contributes rdc.exe command-mode verbs. The CLI declares it for its native verbs; an extension declares it so rdc.exe describe-ext records the capability in its manifest.
Note

Anchored-offset (fragment) parsing and further environment-host runtime operations will be added here as they are implemented. The handshake for every capability listed is still informational (see 2.0.2.1).

Note

First and third party extensions distributed through the RDCore Platform Cloud Infrastructure MAY use a capability provider that MAY validate the availability of certain advanced capabilities by requiring 2FA authentication, the validation of an active subscription (free or paid), and the validation of the signed build against the certified distribution channel build.

In this section

⏮️ RD-VBAL §1.0 Introduction | ⏭️ RD-VBAL §3.0 Syntax Tree

Edit this page