SetupErrors

Analyses setup sheets and publishes consistency reports. Validates the dictionary for duplicate variables, missing labels, unknown controls, and formula correctness; inspects choices for unused entries and missing labels; audits exports for missing metadata and dictionary alignment; and reviews translations for missing or duplicate labels. Results are collected as IChecking objects and published to the __checkRep reporting worksheet via CheckingOutput.

Factory

create #

Create and initialise a setup checker instance

Signature:

Public Function Create(ByVal hostBook As Workbook, _
                       Optional ByVal passwordService As IPasswords, _
                       Optional ByVal dictionary As ILLdictionary, _
                       Optional ByVal choices As ILLChoices, _
                       Optional ByVal formulaStore As IFormulaData, _
                       Optional ByVal transManager As ISetupTranslationsTable, _
                       Optional ByVal stateScope As IApplicationState) As ISetupErrors

Factory method on the predeclared instance. Creates a new SetupErrors, calls Initialise with the supplied workbook and optional collaborators, then returns the instance through the ISetupErrors interface.

Parameters:

hostBook: Workbook. The workbook containing setup data.
passwordService: Optional IPasswords. Sheet protection handler.
dictionary: Optional ILLdictionary. Dictionary data accessor.
choices: Optional ILLChoices. Choices data accessor.
formulaStore: Optional IFormulaData. Formula validation handler.
transManager: Optional ISetupTranslationsTable. Translations table accessor.
stateScope: Optional IApplicationState. Application state guard.

Returns: ISetupErrors. A fully initialised instance ready to run checks.

Throws:

ProjectError.ObjectNotInitialized When hostBook is Nothing.

Initialisation

initialise #

Bind the checker to a workbook and optional collaborators

Signature:

Public Sub Initialise(ByVal hostBook As Workbook, _
                      Optional ByVal passwordService As IPasswords, _
                      Optional ByVal dictionary As ILLdictionary, _
                      Optional ByVal choices As ILLChoices, _
                      Optional ByVal formulaStore As IFormulaData, _
                      Optional ByVal transManager As ISetupTranslationsTable, _
                      Optional ByVal stateScope As IApplicationState)

Validates the workbook reference, stores it along with optional collaborators, then calls ConfigureDependencies to create any missing default instances and EnsureCheckContainer to prepare the results array.

Parameters:

hostBook: Workbook. The workbook containing setup tables.
passwordService: Optional IPasswords. Sheet protection handler.
dictionary: Optional ILLdictionary. Dictionary data accessor.
choices: Optional ILLChoices. Choices data accessor.
formulaStore: Optional IFormulaData. Formula validation handler.
transManager: Optional ISetupTranslationsTable. Translations table accessor.
stateScope: Optional IApplicationState. Application state guard.

Throws:

ProjectError.ObjectNotInitialized When hostBook is Nothing.

Execution

run #

Execute all setup checks and publish results

Signature:

Public Sub Run()

Suspends Excel UI via EnterBusyState, resets the check container, then runs each checker in sequence: CheckDictionary, CheckChoice, CheckExports, CheckTranslations. On completion, publishes all collected IChecking objects to the reporting worksheet via PrintReport. Restores Excel state even when an error occurs during the checking run.

Results

checkings #

Collection of generated checking objects

Signature:

Public Property Get Checkings() As BetterArray

Returns a BetterArray containing the IChecking instances produced by the most recent Run call. Raises when the checker has not been initialised.

Returns: BetterArray. The generated IChecking instances.

Internal members (not exported)

Helper workflow

self #

Current object instance

Signature:

Public Property Get Self() As ISetupErrors

Returns: ISetupErrors. The current instance cast to the interface.

ensure-initialised #

Ensure the checker has been initialised

Signature:

Private Sub EnsureInitialised()

Throws:

ProjectError.ObjectNotInitialized When the workbook reference is Nothing.

configure-dependencies #

Prepare collaborators when not provided

Signature:

Private Sub ConfigureDependencies()

Creates default instances for any optional collaborator that was not supplied during Initialise: resolves the formula sheet, creates Passwords, LLdictionary, LLChoices, FormulaData, and SetupTranslationsTable instances from the host workbook.

ensure-check-container #

Ensure the internal container for checkings exists

Signature:

Private Sub EnsureCheckContainer()

reset-check-container #

Reset the container prior to running checks

Signature:

Private Sub ResetCheckContainer()

application-scope #

Retrieve or create the application state scope

Signature:

Private Function ApplicationScope() As IApplicationState

Returns: IApplicationState. The cached or newly created scope.

enter-busy-state #

Suspend Excel UI features while running checks

Signature:

Private Sub EnterBusyState()

leave-busy-state #

Restore Excel UI configuration

Signature:

Private Sub LeaveBusyState(Optional ByVal silent As Boolean = False)

Parameters:

silent: Optional Boolean. When True, suppresses errors during restore. Defaults to False.

resolve-worksheet #

Resolve a workbook worksheet by name

Signature:

Private Function ResolveWorksheet(ByVal sheetName As String) As Worksheet

Parameters:

sheetName: String. The worksheet name to look up.

Returns: Worksheet. The resolved worksheet.

Throws:

ProjectError.ElementNotFound When the worksheet does not exist.

validate-workbook #

Validate the incoming workbook reference

Signature:

Private Sub ValidateWorkbook(ByVal hostBook As Workbook)

Parameters:

hostBook: Workbook. The workbook to validate.

Throws:

ProjectError.ObjectNotInitialized When hostBook is Nothing.

Core checking routines

check-dictionary #

Validate dictionary sheet for structure, duplicates, and formulas

Signature:

Private Sub CheckDictionary()

Unprotects the dictionary, exports, and choices sheets, then iterates bottom-up through the dictionary rows checking for: duplicate variable names, short variable names, missing main labels, missing sheet names, unknown controls, choice formula mismatches, formula validity, min/max validation types, format/type consistency, and export column alignment. Collects all findings into a single IChecking object and re-protects sheets on exit.

check-choice #

Inspect choices sheet for unused or inconsistent entries

Signature:

Private Sub CheckChoice()

Unprotects the choices sheet, builds a list of choice names actually referenced in dictionary controls, then flags unused choices, missing list names, missing ordering values, and missing labels. Collects all findings into a single IChecking object and re-protects on exit.

check-exports #

Audit exports sheet for missing metadata and dictionary alignment

Signature:

Private Sub CheckExports()

Iterates over each export row, checking active exports for missing label, password, metadata, format, filename, and header values. Also validates that the corresponding dictionary column exists and is not empty, checks password/identifier consistency, and validates filename variable references.

check-translations #

Review translations table for missing and duplicate labels

Signature:

Private Sub CheckTranslations()

Unprotects the translations sheet, updates the translations manager from the registry, then queries for missing and duplicate labels. Collects findings into a single IChecking object and re-protects on exit.

check-analysis #

Run analysis table checks across all sections

Signature:

Private Sub CheckAnalysis()

Resolves the analysis worksheet, removes empty rows via Analysis.RemoveRows, then delegates to CheckTable for each of the seven analysis sections. Caches the worksheet and WorksheetFunction references and passes them to CheckTable to avoid repeated lookups.

CheckTable #

Evaluate a specific analysis section for structural errors.

Signature:

Private Sub CheckTable(ByVal partName As String, _
                       ByVal analysisSheet As Worksheet, _
                       ByVal workFun As WorksheetFunction)

Parameters:

partName: String. The section display name (e.g. "Global summary").
analysisSheet: Worksheet. The cached analysis worksheet.
workFun: WorksheetFunction. The cached worksheet function object.

print-report #

Publish all collected checkings to the reporting worksheet

Signature:

Private Sub PrintReport()

Resolves the __checkRep worksheet, clears its content, creates a CheckingOutput helper, and prints all collected IChecking objects. Installs the worksheet change handler for filtering support and activates the report sheet.

Message helpers

format-message #

Format an error message by replacing numbered placeholders

Signature:

Private Function FormatMessage(ByVal messageTag As String, _
                               Optional ByVal valueOne As String = vbNullString, _
                               Optional ByVal valueTwo As String = vbNullString, _
                               Optional ByVal valueThree As String = vbNullString, _
                               Optional ByVal valueFour As String = vbNullString) As String

Parameters:

messageTag: String. The message template with %1..%4 placeholders.
valueOne: Optional String. Replacement for %1.
valueTwo: Optional String. Replacement for %2.
valueThree: Optional String. Replacement for %3.
valueFour: Optional String. Replacement for %4.

Returns: String. The formatted message.

formula-message #

Validate a formula string and return a formatted error when invalid

Signature:

Private Function FormulaMessage(ByVal formValue As String, _
                                ByVal messageTag As String, _
                                Optional ByVal valueOne As String = vbNullString, _
                                Optional ByVal valueTwo As String = vbNullString, _
                                Optional ByVal formulaType As String = "linelist") As String

Parameters:

formValue: String. The formula expression to validate.
messageTag: String. The message template to use on failure.
valueOne: Optional String. Replacement for %1.
valueTwo: Optional String. Replacement for %2.
formulaType: Optional String. Formula type ("linelist" or "analysis"). Defaults to "linelist".

Returns: String. The formatted error message, or empty when the formula is valid.

replace-placeholder #

Replace a single placeholder token in a template string

Signature:

Private Function ReplacePlaceholder(ByVal template As String, _
                                    ByVal placeholder As String, _
                                    ByVal replacement As String) As String

Parameters:

template: String. The template containing the placeholder.
placeholder: String. The token to replace (e.g. "%1").
replacement: String. The value to substitute.

Returns: String. The template with the placeholder replaced.

Interface implementation

ISetupErrors_Initialise #

Signature:

Private Sub ISetupErrors_Initialise(ByVal hostBook As Workbook, _
                                    Optional ByVal passwordService As IPasswords, _
                                    Optional ByVal dictionary As ILLdictionary, _
                                    Optional ByVal choices As ILLChoices, _
                                    Optional ByVal formulaStore As IFormulaData, _
                                    Optional ByVal transManager As ISetupTranslationsTable, _
                                    Optional ByVal stateScope As IApplicationState)

Delegated members satisfying the ISetupErrors contract. See the corresponding Public members above for full documentation.

throw-error #

Raise a ProjectError-based exception

Signature:

Private Sub ThrowError(ByVal errNumber As ProjectError, ByVal errorMessage As String)

Wrapper around Err.Raise that standardises the source to CLASS_NAME, providing a consistent stack trace across all methods in this class.

Parameters:

errNumber: ProjectError. The error code to raise.
errorMessage: String. Human-readable description of the failure.

Throws:

ProjectError Always raises the specified error.

Used in (4 file(s))