GenerationLog

The single owner of a generation run's record. Start opens the run on the designer __check worksheet; Collect and Harvest take Checking bundles, stamp every entry with the flush time, keep the entries in an in-memory record and flush the bundle to the worksheet through CheckingOutput, which appends across renders. Finish writes the closing bundle (outcome and elapsed seconds, plus the sheet and variable counts when the driver knows them), installs the filter handler and shows the worksheet. ExportText writes the whole record to a text file, one line per entry, so the run stays readable outside the workbook.

THE RUN WINDOW

Entries land between Start and Finish. A bundle collected outside that window is ignored, the behaviour every driver leans on: the build core runs the same with or without an open log. The in-memory record stays alive after Finish, which is what a later text re-export reads. Start resets the worksheet, the render marker and the record, so a re-run begins clean.

SECTIONS AND SUBSECTIONS

A run that builds several linelists opens one section per linelist, through OpenSection and CloseSection. While a section is open every bundle is re-headed -- the section title becomes the bundle title and the bundle's own title becomes its subtitle -- and held back. Closing the section writes the held bundles in one pass, so the section title lands once as a level one heading and every part of that build reads as a subsection under it. Without an open section a bundle is written on its own, which is what the single build does.

BUNDLES CARRIED AS TEXT

The build runs as steps, and a step may run in another Excel instance where the log cannot reach. BundleText turns one bundle into a string that ends on a form feed, so the texts of several bundles are joined by plain concatenation; CollectText takes such a string back and collects every bundle in it, record-only flag included. Both sit on this class so the two sides of the carriage share one shape. A label carrying a tab or a vertical tab is cut at that character.

SHOWING THE REPORT

Finish closes the run and leaves the worksheet where it is. The driver shows it once, at the end, through ShowReport, with the screen back on.

Depends on: CheckingOutput, Checking, HiddenNames, BetterArray, LinelistSpecs

Factory

Create #

create

Create a log bound to the designer workbook

Signature:

Public Function Create(ByVal designerBook As Workbook) As GenerationLog

The workbook is where the __check worksheet lives. The run itself opens later, through Start.

Parameters:

  • designerBook: Workbook. The designer workbook.

Returns: GenerationLog. A ready instance.

Throws:

  • ProjectError.ElementNotFound When designerBook is Nothing.
Run lifecycle

SpecificationBundles #

specification-bundles

The bundles the specification collaborators filed, in harvest order

Signature:

Public Function SpecificationBundles(ByVal specs As LinelistSpecs) As BetterArray

The list Harvest walks, answered on its own so a build step running away from the log can carry the same bundles as text. The order is the dictionary, the choices, the exports, the analysis, the passwords, the format and the specifications themselves. A collaborator with nothing filed is skipped. Works on the predeclared instance: it reads no state.

Parameters:

  • specs: LinelistSpecs. The specifications after Prepare.

Returns: BetterArray. The Checking bundles, 1-based. Empty when nothing was filed.

Throws:

  • ProjectError.InvalidArgument When specs is Nothing.

BundleText #

bundle-text

One bundle as text, ready to be joined with others

Signature:

Public Function BundleText(ByVal checks As Checking, _
                           Optional ByVal recordOnly As Boolean = False) As String

The title line, then one line per entry, then the bundle end. An empty bundle answers an empty string, so a caller may append the answer without looking at it. Works on the predeclared instance.

Parameters:

  • checks: Checking. The bundle to carry.
  • recordOnly: Optional Boolean. True marks the bundle for the record alone.

Returns: String. The bundle text, or empty when the bundle holds nothing.

CollectText #

collect-text

Take every bundle carried in one text into the run

Signature:

Public Sub CollectText(ByVal bundlesText As String)

The text is what one or more BundleText answers make when joined. Each bundle is rebuilt as a Checking with its title, subtitle and scopes and handed to Collect with its record-only flag. A line short of its three fields is skipped, and a key the bundle already carries is skipped too. An empty text, and a run that is closed, take nothing.

Parameters:

  • bundlesText: String. The joined bundle texts.

ShowReport #

show-report

Bring the report worksheet to the front

Signature:

Public Function ShowReport() As Boolean

The one owner of showing the report. The drivers call it once, at the end of a run, and the ribbon calls it whenever the user asks for the last report, so a report opened either way opens the same way.

WHY THE WORKBOOK IS ACTIVATED FIRST

Worksheet.Activate raises 1004 when the sheet belongs to a workbook that is not the active one. A generation ends with the built linelist open and in front, so the activation Finish used to do raised every time and its On Error Resume Next swallowed it. That is why the report never appeared at the end of a run.

The sheet is created very hidden and Activate raises on a hidden sheet, so the visibility write comes before it.

An empty sheet is not a report. A designer that has never generated anything carries __check as a blank very hidden sheet, and showing that would leave the user looking at an empty grid with no way back.

Returns: Boolean. True when a report was found and brought to the front.

Internal members (not exported)

Factory

Seal #

seal

Seal the instance against further setup writes

Signature:

Public Sub Seal()

GuardNotSealed #

guard-not-sealed

Guard a setup setter against post-seal mutation

Signature:

Private Sub GuardNotSealed(ByVal propName As String)

Parameters:

PublicAccessors

DesignerBook #

designer-book

The designer workbook the run writes on

Signature:

Public Property Get DesignerBook() As Workbook

Returns: Workbook. The workbook given at creation.

DesignerBook #

designer-book-set

Assign the designer workbook

Signature:

Public Property Set DesignerBook(ByVal designerBook As Workbook)

Parameters:

RecordLength #

record-length

The number of entries in the in-memory record

Signature:

Public Property Get RecordLength() As Long

Counts every stamped entry the run has collected, the header and closing bundles included. Answers 0 before the first Start.

Returns: Long. The entry count.

RecordLine #

record-line

One record entry as its text line

Signature:

Public Property Get RecordLine(ByVal index As Long) As String

The line shape is the one the text export writes: hh:mm:ss [scope] bundle-title entry-label.

Parameters:

Returns: String. The formatted line.

Throws:

SectionTitle #

section-title

The title of the section that is open

Signature:

Public Property Get SectionTitle() As String

Answers an empty string when no section is open, which is the state of a single build from the first bundle to the last.

Returns: String. The open section title.

Run lifecycle

Start #

start

Open the run on the __check worksheet

Signature:

Public Sub Start(Optional ByVal setupPath As String = vbNullString, _
                 Optional ByVal linelistName As String = vbNullString)

Resolves the __check worksheet, creating it very hidden when absent, clears it and drops the render marker of the previous run so the writer formats a first render. Opens a fresh writer, resets the in-memory record, starts the wall clock and stamps the run header as the first bundle: the start time and the platform of the run, plus the setup path and the linelist name when the caller knows them.

Parameters:

PlatformTag #

platform-tag

The platform of the run, on one tag

Signature:

Private Function PlatformTag() As String

A generation report is read on another machine and long after the run, and the two platforms do not behave the same: a geobase export Windows accepts has refused on a Mac. The name and the bitness come from the compile constants, so they are the build that is running and cannot be misread. The Excel version comes from the application.

Returns: String. Something of the shape "mac-64 excel-16.90".

OpenSection #

open-section

Open one section of the report

Signature:

Public Sub OpenSection(ByVal sectionTitle As String)

A section is one whole piece of work, and for a run that builds several linelists that is one linelist. While the section is open every bundle Collect takes is held back and re-headed: the section title becomes the bundle title and the bundle's own title becomes its subtitle. Closing the section writes the held bundles in one pass, which puts the section title on the sheet once, at level one, with every part of the build under it at level two.

Opening a section closes the one that was open before it, so a driver that walks a table calls this once per row and the rows never mix. An empty title closes the open section and opens none. A call outside the run window is ignored, like every other call here.

Parameters:

CloseSection #

close-section

Write the open section to the worksheet and close it

Signature:

Public Sub CloseSection()

The held bundles go to the writer as one batch, which is what makes the section title land once. A section that took no bundle writes nothing. Calling this with no section open is a no-op, so a driver may close after every row and after the loop.

Collect #

collect

Take one Checking bundle into the run

Signature:

Public Sub Collect(ByVal checks As Checking, _
                   Optional ByVal recordOnly As Boolean = False)

Stamps every entry of the bundle with the flush time, appends the entries to the in-memory record and flushes the bundle to the worksheet. A Nothing or empty bundle is skipped, and so is any bundle arriving outside the run window (before Start or after Finish).

THE RECORD-ONLY PATH

recordOnly keeps a bundle out of the worksheet and puts it in the in-memory record alone, so it reaches the text file and nothing else. It carries the detail bundles: one entry per variable written is a few hundred entries on a normal linelist, and CheckingOutput ends every row it writes with an EntireColumn.AutoFit. The worksheet keeps the sheet, section and analysis milestones plus every fault, which is what a reader opens it for.

THE BUNDLE OF AN OPEN SECTION

The bundle is held in the section, and CloseSection writes the whole section in one pass. The record line carries the section title in front of the bundle title, so the text file reads the same way the worksheet does.

Parameters:

SubsectionOf #

subsection-of

One bundle re-headed as a subsection of the open section

Signature:

Private Function SubsectionOf(ByVal checks As Checking) As Checking

A copy is taken because the caller owns the bundle it handed over, and because a Checking is sealed at creation: its title is written by the factory alone. Append carries the entries across with their scopes.

Parameters:

Returns: Checking. The copy, headed by the section and subheaded by the bundle.

Harvest #

harvest

Collect the bundles of the specification collaborators

Signature:

Public Sub Harvest(ByVal specs As LinelistSpecs)

Pulls the checkings of the dictionary, the choices, the exports, the analysis, the passwords, the format and the specifications themselves, in that order. The pull runs after LinelistSpecs.Prepare, when the collaborators have filed their entries.

Parameters:

Throws:

CollectOneText #

collect-one-text

Rebuild one bundle from its text and collect it

Signature:

Private Sub CollectOneText(ByVal bundleText As String)

Parameters:

ScopeFromWord #

scope-from-word

The scope a plain scope word stands for

Signature:

Private Function ScopeFromWord(ByVal scopeWord As String) As Byte

The reverse of ScopeText. A word this class does not know answers the note scope, the way Checking reads an unknown type label.

Parameters:

Returns: Byte. The CheckingScope value.

Finish #

finish

Close the run

Signature:

Public Sub Finish(ByVal outcome As String, _
                  Optional ByVal sheetCount As Long = -1, _
                  Optional ByVal variableCount As Long = -1)

Writes the closing bundle (the outcome, the elapsed seconds, and the sheet and variable counts when the driver passes them), installs the worksheet filter handler, then releases the writer. A workbook that refuses the code injection the filter needs gets a warning entry in the closing bundle and the run still closes whole. The record stays alive for the text export. A log that never started, or already finished, ignores the call. The worksheet is left as it is: the driver shows it through ShowReport once its screen is back on.

Parameters:

ExportText #

export-text

Write the whole record to a text file

Signature:

Public Function ExportText(ByVal folderPath As String, ByVal baseName As String) As String

One line per entry, in the order the run collected them: hh:mm:ss [scope] bundle-title entry-label. The file lands in the given folder as -generation.txt, which puts it beside the generated linelist when the caller passes the output folder and the linelist name.

Parameters:

Returns: String. The full path of the written file.

Throws:

Internal helpers

ResolveCheckingSheet #

resolve-checking-sheet

Resolve the __check worksheet, creating it when absent

Signature:

Private Function ResolveCheckingSheet() As Worksheet

A created worksheet lands very hidden at the end of the workbook. Finish makes it visible once the run closes.

Returns: Worksheet. The resolved or newly created worksheet.

ScopeText #

scope-text

The plain scope word of one entry

Signature:

Private Function ScopeText(ByVal checks As Checking, ByVal keyName As String) As String

Reads the type descriptor of the entry and strips the icon characters, leaving Error, Warning, Info, Note or Success for the record and the text lines.

Parameters:

Returns: String. The plain scope word.

ErrorHandling

ThrowError #

throw-error

Raise a ProjectError-coded runtime error

Signature:

Private Sub ThrowError(ByVal errNumb As Long, ByVal errorMessage As String)

Parameters:

Throws:

Used in (12 file(s))