2.2. RDPROJ Structure

Note

This specification may be incomplete at this time.

Because the truth of a RD-VBA program is its source code, RD-VBA source code lives directly on the file system, within a structured system of folders. Since doing this completely decouples a VBA project from its host document, there needs to be a data structure somewhere that explicitly defines the structure and content of a project.

2.2.1. Conventions

  • Because the truth of a RD-VBA workspace is in the file system, the oganization of the folders designated as workspaces constitutes meaningful metadata that structures both the physical file system and the workspace folders (projects) under it.
  • A workspace folder (project) may exist in itself, or under a workspace directory.
  • A .rdworkspace file describes a LSP workspace, or a VBProjectGroup.
  • A .rdproj file describes a LSP workspace folder, or a VBProject.
  • These files do not have a name, only an extension: instead, the name of the folder they are located in is the canonical identifier name of the workspace or workspace folder.
  • The term workspace root describes either:
    • The physical file system location (full path) of the folder that contains the .rdworkspace file, in the context of file-level operations;
    • An absolute file Uri pointing to that location, in most other contexts.
Important

Workspace Folder (project) names must therefore be valid PascalCase identifier names, however the uniqueness of the workspace folder names under a given workspace is mandated by the LSP specification, not by the file system.

Warning

Because RD-VBA identifier names are semantically case-insensitive, folder names "project1" and "Project1" are considered as identical regardless of whether or not the underlying file system supports it.

2.2.2. WorkspaceFile

RD-VBA is able to discover a file system folder as a workspace when the folder contains a text file named .rdworkspace that can be successfully deserialized into a WorkspaceFile. This folder is then the root of that workspace.

The model describes the content of the workspace:

{
  "Folders": [],
  "Files": []
}
Member Description
Folders An array of folder names that are directly under the root. Each one of these folder is expected to contain a serialized ProjectFile.
Files An array of file names from the root folder, that are included in the workspace.
Tip

This model is intended to natively support VB6 project groups (.vbg).

2.2.3. ProjectFile

This specification may be incomplete at this time.

RD-VBA is able to discover a file system folder as a workspace folder when the folder contains a text file named .rdproj that can be successfully deserialized into a ProjectFile. This folder is then the root of that workspace folder.

{
  "Version": "",
  "Configuration": [],
  "ProjectInfo": RDCoreProject
}
Member Description
Version A string value containing the RD-VBA language core version the project file was serialized with.
Configuration A string value containing the location (relative path) of any configuration files to bind at run-time.
ProjectInfo An object that describes the content of a RD-VBA project.
Tip

This model is intended to natively support VB6 vbproject (.vbp).

2.2.3.1 RDCoreProject

A serializable model representing a RD-VBA project.

{
  "Name": "",
  "References": [RDCoreReference],
  "Modules": [RDCodeModule],
  "OtherFiles": [RDCoreFile],
  "Folders": []
}
Member Description
Name A string value containing the name the project file was serialized with.
References An array of RDCoreReference describing the project references.
Modules An array of RDCoreModule describing the project source files.
OtherFiles An array of RDCoreFile describing any non-source files included in the project.
Folders An array of string values containing the names of all the folders in the project, whether they contain source code files or not.
Important

The Name of a project must be a valid identifier name that should not be VBA, or any other reserved identifier name. The reason for wording of the above statement is that whether a source project can reference a different project that has the same name, is explicitly specified as host-dependent behavior. For all intents and purposes, a RD-VBA host environment should very explicitly deny the addition of any such ambiguous project references.

2.2.3.2. RDCoreReference

Describes a reference within a project.

{
  "Name": "",
  "Guid": "",
  "AbsolutePath": "",
  "Major": 0,
  "Minor": 0,
  "IsUnremovable": false
}
Member Description
Name The identifier name (token) used in workspace source code to reference this library.
Guid A Globally Unique Identifier optionally identifying the referenced library in a host-defined application registry.
AbsolutePath The full path to the physical location of the referenced library, if it exists.
Major The major version number of the referenced library, if available.
Minor The minor version number of the referenced library, if available.
IsUnremovable A soft indicator marking the reference as unremovable from a LSP client.
Note

🧩 A supplied Guid necessarily refers to a COM registered library that implies platform-specific Windows Registry lookups to resolve; The environment host may use implementation-dependent alternative means to provide symbols and semantics for such references.

2.2.3.2 RDCoreModule

Describes the modules (source files) of a workspace folder.

{
  "Name": "",
  "Super": null
}
Member Description
Name The identifier name (token) used in workspace source code to reference this module.
DocClassType A string value that can be parsed as a member of the DocClassType enumeration.
Important

The value of the Name property of a RDCoreModule must be unique across the entire workspace and is always supplied by a VB_Name attribute. In case of a mismatch with the value of a VB_Name attribute, the attribute value always takes precedence.

2.2.3.2.1 DocClassType Enum

Note

🧩 This enum type is intended to be extended as additional document modules are explicitly supported.

The DocClassType enumeration defines constants that internally map extensible modules to certain specific class types:

Name Value
Unknown 0
ExcelWorkbook 1
ExcelWorksheet 2
AccessForm 3
AccessReport 4

Document modules can only be added to a VBA project via the host application that defines them; exporting them from a MS-VBA project via the VBIDE Extensibility API produces a .cls file that would then re-import as a class module. Rubberduck historically exported them with a .doccls extension to distinguish the two class types, since the base class metadata is externally defined.

While RD-VBA can load the necessary symbols for these interfaces, their implementation belongs to their respective host application. In other words, RD-VBA cannot create a Workbook host document nor a Worksheet module in its Sheets collection, because that's the job of Microsoft Excel.

Instead, RD-VBA identifies the required interfaces using this enum, and this allows static semantics to correctly identify all the members and available events.

Workspace source code that is directly dependent on a host document necessarily requires an appropriate host to evaluate correctly; in such cases the RD-VBA runtime implementation is free to fire up an automation host process as needed, if such a host exists in the runtime environment.

🎯 A more portable approach would be to refactor the MS-VBA legacy code such that any host-dependent calls are decoupled from the logic. RDCore semantic analysis capabilities should provide ample support for all the diagnostics and refactoring tools that would be needed to do this.

2.2.3.3 RDCoreFile

Describes additional(non-source) files contained in a workspace folder but not necessarily given to a language server for processing.

💡 This means, for example, that a RDCoreProject could include README.md, CONTRIBUTING.md, and LICENCE.md text/markdown files that would always be bundled with the project, but ignored by the RD-VBA language core.

{
  "Name": "",
}
Member Description
Name The identifier name (token) used in workspace source code to reference this module.

⏮️ RD-VBAL§2.1 Computational Environment | ⏭️ RD-VBAL§2.3 Application Host

Edit this page