LinelistSpecs

Factory helpers

Seal #

seal

Seal the instance against further creation-only writes

Signature:

Public Sub Seal()

GuardNotSealed #

guard-not-sealed

Guard a creation-only setter against post-seal writes

Signature:

Private Sub GuardNotSealed(ByVal propName As String)

Parameters:

• propName: String. The property name for the error message.

InternalWorkbook #

internal-workbook

Setter for the backing workbook reference

Signature:

Public Property Set InternalWorkbook(ByVal specsWorkbook As Workbook)

Used during construction to assign the workbook before caches are initialised. Not part of the public interface.

State management

ResetObjectCaches #

reset-object-caches

Clear all collaborator object references

Signature:

Private Sub ResetObjectCaches()

ResetTranslationCache #

reset-translation-cache

Clear the translation scope cache

Signature:

Private Sub ResetTranslationCache()

ResetCategoryCache #

reset-category-cache

Clear the category list cache

Signature:

Private Sub ResetCategoryCache()

Guard helpers

EnsureWorkbook #

ensure-workbook

Verify that the backing workbook is assigned

Signature:

Private Sub EnsureWorkbook()

Lazy-initialisation guards for the workbook and category arrays.

Throws:

• ProjectError.ObjectNotInitialized When the workbook is Nothing.

EnsureCategoryCache #

ensure-category-cache

Create the category lookup if it does not exist

Signature:

Private Sub EnsureCategoryCache()

Worksheet resolution

ResolveSheet #

resolve-sheet

Resolve a worksheet of the designer workbook by name

Signature:

Private Function ResolveSheet(ByVal sheetName As String) As Worksheet

Direct worksheet lookups by name within the specifications workbook.

Looks a worksheet up in the designer workbook by name and raises a descriptive error when it is absent.

Parameters:

• sheetName: String. The worksheet name to find.

Returns: Worksheet. The resolved worksheet.

Throws:

• ProjectError.InvalidArgument When sheetName is empty.
• ProjectError.ElementNotFound When the sheet is missing.

MainSheet #

main-sheet

The designer's Main worksheet, resolved once per instance

Signature:

Private Function MainSheet() As Worksheet

Value used to call ResolveSheet on every read, and Prepare and Linelist together read a dozen tags. ResetCaches drops this reference.

Returns: Worksheet. The Main worksheet of the designer workbook.

Throws:

• ProjectError.ElementNotFound When the Main worksheet is missing.

DesignerHiddenStore #

designer-hidden-store

The designer workbook's hidden name store, built once per instance

Signature:

Private Function DesignerHiddenStore() As HiddenNames

Building one runs EnsureReady and a full metadata rebuild, and Value used to build a fresh store for each of the two hidden-name tags. ResetCaches drops it.

Returns: HiddenNames. The store over the designer workbook.

External workbook helpers

EnterBusyState #

enter-busy-state

Transition the application into a busy state

Signature:

Private Sub EnterBusyState(ByRef busyScope As ApplicationState)

Utilities for opening, closing, and validating external workbooks during the Prepare workflow.

Creates or refreshes an ApplicationState snapshot and applies the busy state (suppressing screen updates and calculation) if not already busy.

Parameters:

• busyScope: ApplicationState (ByRef). The state object to manage.

ImportGeobase #

import-geobase

Import geobase data from the path the user gave

Signature:

Private Sub ImportGeobase(ByVal geoObj As LLGeo)

Reads the geobase file path from the designer's Main worksheet. An empty path is a choice the user made and the import is skipped. A path that is set and will not open is a failure the user has to hear about: the linelist comes out with no geographic data at all, so the reason is filed as a report entry naming the path.

The file is opened read only, the way ImportSetupToLinelist opens the setup workbook. The geobase is read and never written.

Parameters:

• geoObj: LLGeo. The geo instance on the output workbook.

ExitBusyState #

exit-busy-state

Restore the application from a busy state

Signature:

Private Sub ExitBusyState(ByRef busyScope As ApplicationState)

Parameters:

• busyScope: ApplicationState (ByRef). The state object to restore and release.

BuildPreservedSheetNames #

build-preserved-sheet-names

Build the list of sheet names the dictionary must avoid

Signature:

Private Function BuildPreservedSheetNames(ByVal messageTranslations As TranslationObject) As BetterArray

The dictionary generates one data-entry worksheet per sheet name it holds, and a generated name that collides with a worksheet already in the linelist breaks the build. This is the list of names it has to keep clear of.

It is read off the output workbook itself. Prepare has already run every exporter against that workbook by the time it calls this, so the real worksheets are the honest answer, and a list of constants drifts away from them on every change to the architecture. The constant list this replaced still carried a Translations worksheet the designer gave up, and it named Metadata as a temporary sheet when LLGeo creates a real one.

On top of the real worksheets go the temporary names that do not exist yet, and the translated names of the worksheets the build is about to create.

Parameters:

• messageTranslations: TranslationObject. The message translations that resolve the linelist worksheet names.

Returns: BetterArray. The list of preserved sheet names.

SafeTranslatedValue #

safe-translated-value

Look up a translation key, falling back to the key itself on failure

Signature:

Private Function SafeTranslatedValue(ByVal translations As TranslationObject, ByVal key As String) As String

Parameters:

• translations: TranslationObject. The translation object to query.
• key: String. The translation key.

Returns: String. The translated value, or the key if translation fails.

ResetPostImportCaches #

reset-post-import-caches

Clear caches that become stale after importing new data

Signature:

Private Sub ResetPostImportCaches()

Resets the variables object, category cache, and translation cache so they are rebuilt from the freshly imported data.

Workbook validation

ValidateWorkbookReference #

validate-workbook-reference

Validate a workbook reference and its structure

Signature:

Private Sub ValidateWorkbookReference(ByVal specsWorkbook As Workbook)

Structural validation of specifications workbooks.

Throws:

• ProjectError.ObjectNotInitialized When specsWorkbook is Nothing.
• ProjectError.ElementNotFound When required sheets are missing.

ValidateWorkbookStructure #

validate-workbook-structure

Check that a workbook contains all required worksheets and named ranges

Signature:

Private Sub ValidateWorkbookStructure(ByVal specsWorkbook As Workbook)

Iterates the list of required sheet names and collects any that are missing. If the format sheet exists, also validates that the DESIGNTYPE named range is present.

Parameters:

• specsWorkbook: Workbook. The workbook to validate.

Throws:

• ProjectError.ElementNotFound When required sheets or ranges are missing.

RequiredSheetNames #

required-sheet-names

Return the array of required designer worksheet names

Signature:

Private Function RequiredSheetNames() As Variant

Only includes sheets that LinelistSpecs reads directly from the designer workbook. Pass-through sheets (Dictionary, Choices, Analysis, Export) are excluded because InitTransfer imports them from the setup file directly into the linelist.

Returns: Variant. Array of sheet name strings.

WorksheetExistsInternal #

worksheet-exists-internal

Test whether a worksheet exists in a workbook

Signature:

Private Function WorksheetExistsInternal(ByVal specsWorkbook As Workbook, _
                                         ByVal sheetName As String) As Boolean

Parameters:

• specsWorkbook: Workbook. The workbook to search.
• sheetName: String. The worksheet name to look for.

Returns: Boolean. True when the worksheet exists.

RangeExistsInternal #

range-exists-internal

Test whether a named range exists on a worksheet

Signature:

Private Function RangeExistsInternal(ByVal hostSheet As Worksheet, _
                                     ByVal rangeName As String) As Boolean

Parameters:

• hostSheet: Worksheet. The worksheet to search.
• rangeName: String. The named range to look for.

Returns: Boolean. True when the named range exists.

JoinNames #

join-names

Join a BetterArray of names into a comma-separated, quoted string

Signature:

Private Function JoinNames(ByVal values As BetterArray) As String

Parameters:

• values: BetterArray. The names to join.

Returns: String. Formatted string like "'Sheet1', 'Sheet2'".

SafeWorkbookName #

safe-workbook-name

Safely retrieve a workbook's name, returning "" on error

Signature:

Private Function SafeWorkbookName(ByVal specsWorkbook As Workbook) As String

Parameters:

• specsWorkbook: Workbook. The workbook whose name to retrieve.

Returns: String. The workbook name or "".

Collaborator ensures

RequirePrepared #

require-prepared

Refuse a read of a collaborator Prepare has to supply

Signature:

Private Sub RequirePrepared(ByVal memberName As String)

How each collaborator is obtained. Read the residency table in the class description first: it says which workbook each one is backed by.

The collaborators that live on the DESIGNER are built here on first read, from a worksheet RequiredSheetNames() guarantees is present.

The four that live on the LINELIST have no loader. Prepare sets them from the transfer, and their accessors raise before that. A loader for them used to resolve a designer worksheet the designer no longer carries.

The four pass-through collaborators are imported from the setup file straight into the linelist. Reading one before Prepare has run is a caller mistake, and this is the message that says so.

Parameters:

• memberName: String. The accessor the caller asked for.

Throws:

• ProjectError.ErrorUnexpectedState Always.

EnsureTranslations #

ensure-translations

Load the translations collaborator on first read

Signature:

Private Sub EnsureTranslations()

Creates the LLTranslation instance from the designer's linelist translation worksheet. Prepare replaces it with the copy on the linelist.

EnsureGeo #

ensure-geo

Load the geo collaborator on first read

Signature:

Private Sub EnsureGeo()

Built over the designer's Geo worksheet. Prepare replaces it with the copy on the linelist.

EnsurePasswords #

ensure-passwords

Load the passwords collaborator on first read

Signature:

Private Sub EnsurePasswords()

Built over the designer's password worksheet. Prepare replaces it with the copy on the linelist.

EnsureFormulaData #

ensure-formula-data

Load the formula data collaborator on first read

Signature:

Private Sub EnsureFormulaData()

EnsureVariables #

ensure-variables

Build the variables collaborator over the dictionary

Signature:

Private Sub EnsureVariables()

Reads the dictionary through its accessor, so a call before Prepare raises there and names Prepare.

EnsureFormat #

ensure-format

Load the format collaborator on first read

Signature:

Private Sub EnsureFormat()

Resolves the design name from the DESIGNTYPE named range on the designer's format worksheet, then creates the LLFormat instance.

ResolveDesignName #

resolve-design-name

Extract the design name from the format worksheet's DESIGNTYPE range

Signature:

Private Function ResolveDesignName(ByVal formatSheet As Worksheet) As String

Parameters:

• formatSheet: Worksheet. The format worksheet.

Returns: String. The trimmed design type name.

Throws:

• ProjectError.ElementNotFound When the DESIGNTYPE range is missing.

EnsureCategoryLookup #

ensure-category-lookup

Ensure choices, variables and the category lookup are ready

Signature:

Private Sub EnsureCategoryLookup()

Choices reads through its accessor, so a call before Prepare raises there.

NumberOfExports #

number-of-exports

Return the number of exports defined in the export specifications

Signature:

Private Function NumberOfExports() As Long

Returns: Long. The export count.

List auto helpers

AddListAuto #

add-list-auto

Populate the "list auto" dictionary column for list_auto variables

Signature:

Private Sub AddListAuto()

Automatic list column generation for formula-based variables.

Adds a "list auto" column to the dictionary, then reads the control details of every list_auto variable. Those details name the DIRECT origin, the variable whose entered values the automatic list collects, and each one is tagged list_auto_origin. An origin that is itself a formula is followed through RecursiveListAuto, and everything found down that chain is tagged list_auto_indirect_origin: it is watched for changes and never collected from.

The direct tag is written over whatever is there. A variable can be reached as an indirect origin of one list and be the direct origin of another, and the two arrive in whichever order the dictionary happens to hold, so the stronger tag has to win rather than the earlier one.

RecursiveListAuto #

recursive-list-auto

Mark the variables a formula origin is built on

Signature:

Private Sub RecursiveListAuto(ByVal varName As String)

Parses the control details of a formula-type variable using the Formulas engine, extracts the list of referenced variables, tags each of them list_auto_indirect_origin, and recurses into any that are themselves formulas or case_when types.

These variables are NOT collected from. A list built out of them would be a list of whatever happens to sit under a variable that merely feeds a formula -- an ordinary choice column, most of the time. They carry the tag so an edit to one still tells the workbook that an automatic list may have moved.

The write is onEmpty:=True, so a variable already tagged as a direct origin keeps that tag.

Parameters:

• varName: String. The formula variable whose references to trace.

Category helpers

CachedCategories #

cached-categories

Read one category list out of the lookup

Signature:

Private Function CachedCategories(ByVal cacheKey As String) As BetterArray

A Collection raises on a key it does not hold, which is how a miss is read. The lookup this replaced was two parallel BetterArrays walked one entry at a time, and every walk opened with a full copy of the internal array. A 500-variable dictionary spent about 125,000 item reads on cache misses alone.

Parameters:

• cacheKey: String. The key to look up.

Returns: BetterArray. The cached list, or Nothing when the key is absent.

ResolveCategoryList #

resolve-category-list

Build a category list from the choices sheet for a given variable

Signature:

Private Function ResolveCategoryList(ByVal varName As String, _
                                     ByVal useShortlabels As Boolean) As BetterArray

Determines the category name from the variable's control type and control details, then queries the choices collaborator.

Parameters:

• varName: String. The variable name.
• useShortlabels: Boolean. Whether to use short labels.

Returns: BetterArray. The resolved category list.

Throws:

• ProjectError.InvalidArgument When varName is empty.
• ProjectError.ElementNotFound When the variable or category is not found.

NormaliseControlType #

normalise-control-type

Strip parenthesised suffixes from a control type string

Signature:

Private Function NormaliseControlType(ByVal controlValue As String) As String

Parameters:

• controlValue: String. The raw control type value.

Returns: String. The normalised, lower-cased control type.

ExtractChoiceFormula #

extract-choice-formula

Extract the choice name from a CHOICE_FORMULA(...) control details string

Signature:

Private Function ExtractChoiceFormula(ByVal controlDetails As String) As String

Parameters:

• controlDetails: String. The raw control details value.

Returns: String. The extracted choice name.

Core accessors

ResolveTranslationScope #

resolve-translation-scope

Query the translations collaborator for a given scope

Signature:

Private Function ResolveTranslationScope(ByVal scopeValue As Byte) As TranslationObject

Parameters:

• translationScope: Byte. The translation scope to resolve.

Returns: TranslationObject. The resolved translation object.

Throws:

• ProjectError.ElementNotFound When the scope returns Nothing.

Workbook orchestration

EmptyFirstSheet #

empty-first-sheet

The first worksheet of a workbook, when it carries nothing

Signature:

Private Function EmptyFirstSheet(ByVal outWkb As Workbook) As Worksheet

The placeholder Excel puts in a new workbook, and the one a template ships. Its name is localised -- Sheet1, Feuille1, Hoja1 -- so the name is no test at all and the CONTENT is what is read: a worksheet holding no value, no table, no shape and no pivot is a placeholder whatever it is called.

It is only ever called before the first exporter writes, so "empty now" and "empty because nothing has been put there yet" are the same thing. Called later it would happily answer a real worksheet that has not been filled in.

Parameters:

• outWkb: Workbook. The output workbook, freshly opened.

Returns: Worksheet. The placeholder, or Nothing when the first sheet holds something.

Checkings

Checks #

checks

The report entries of this instance

Signature:

Private Property Get Checks() As Checking

What this class reports into the generation log. GenerationLog.Harvest collects these after Prepare, alongside the entries of the dictionary, the choices, the exports, the analysis, the passwords and the format.

Returns: Checking. The entries, created on first use.

LogCheck #

log-check

File one report entry

Signature:

Private Sub LogCheck(ByVal message As String, _
                     Optional ByVal scope As Byte = checkingNote)

Checking.Add raises on a duplicate key, and one report carries the entries of several classes, so the key names this class and a counter.

Parameters:

• message: String. The message text.
• scope: Optional Byte. The checking scope. Defaults to checkingNote.

Error handling

ThrowError #

throw-error

Raise a project error with the class name as source

Signature:

Private Sub ThrowError(ByVal errNumber As Long, ByVal messageText As String)

Internal error-raising utility.

Parameters:

• errNumber: Long. The ProjectError constant.
• messageText: String. The error description.

Test support

TestAssignDictionary #

test-assign-dictionary

Inject a dictionary collaborator for testing

Signature:

Public Sub TestAssignDictionary(ByVal dict As LLdictionary)

Backdoor setters for injecting mock collaborators during testing.

Parameters:

• dict: LLdictionary. The dictionary to expose through Dictionary().

TestAssignLLWorkbook #

test-assign-ll-workbook

Inject the output workbook for testing

Signature:

Public Sub TestAssignLLWorkbook(ByVal wkb As Workbook)

Lets a suite drive Linelist's worksheet members over a plain workbook, without running Prepare. Prepare is the only production writer of this field.

Parameters:

• wkb: Workbook. The workbook to expose through LLWorkbook().

TestAssignDesignFormat #

test-assign-design-format

Inject a design-format collaborator for testing

Signature:

Public Sub TestAssignDesignFormat(ByVal fmt As LLFormat)

Parameters:

• fmt: LLFormat. The format object to expose through DesignFormat().

TestAssignFormulaData #

test-assign-formula-data

Inject a formula-data collaborator for testing

Signature:

Public Sub TestAssignFormulaData(ByVal data As FormulaData)

Parameters:

• data: FormulaData. The formula data to expose through FormulaDataObject().

TestAssignChoices #

test-assign-choices

Inject a choices collaborator for testing

Signature:

Public Sub TestAssignChoices(ByVal choicesObj As LLChoices)

Lets a suite reach Categories, and through it every dropdown a variable can carry, without running Prepare.

Parameters:

• choicesObj: LLChoices. The choices object to expose through Choices().

TestAssignTransObject #

test-assign-trans-object

Inject one TranslationObject for every translation scope

Signature:

Public Sub TestAssignTransObject(ByVal trans As TranslationObject)

Sets all five scope-cache fields so TransObject returns the same object regardless of scope, mirroring the former single-object test stubs.

Parameters:

• trans: TranslationObject. The translation object to expose.

• Analysis.cls
• AnalysisOutput.cls
• CrossTable.cls
• TableSpecs.cls
• DesignerEntry.cls
• GenerationLog.cls
• LLVariables.cls
• TimeSeriesGraphs.cls
• EventLinelist.cls
• Linelist.cls
• LLDataEntry.cls
• SectionBuilder.cls
• VarWriter.cls
• EventsDesignerAdvanced.bas
• InitTransfer.bas
• HeadlessBuild.bas
• TestAnalysisOutput.bas
• TestCrossTable.bas
• TestTableSpecs.bas
• TestDesignerEntry.bas
• TestLLVariables.bas
• TestApplicationState.bas
• TestTemporaryRepos.bas
• TestGraphSeries.bas
• TestTimeSeriesGraphs.bas
• TestHeadlessLinelistBuild.bas
• LinelistDataStub.cls
• TestHelpers.bas
• TestHelpersLite.bas
• TestEventLinelistSheets.bas
• TestLinelist.bas
• TestLinelistSpecs.bas
• TestLLDataEntry.bas
• TestLLTranslation.bas
• TestSectionBuilder.bas
• TestVarWriter.bas