KSLCore/ksl.utilities.io/OutputDirectory

OutputDirectory

class OutputDirectory(outputDirectoryPath: Path = KSLFileUtil.programLaunchDirectory, outFileName: String = "out.txt", autoCreateOutFile: Boolean = true)(source)

This class provides basic context for creating and writing output files. Files and directories created by instances of this class will be relative to the Path supplied at creation.

Side-effects at construction

outDir (the base directory) is created eagerly.
out (the log writer) is created eagerly only when autoCreateOutFile is true (the default). When false, out is a discard-all writer wrapping Writer.nullWriter() and no file is created on disk.
The four subdirectory properties (excelDir, dbDir, csvDir, plotDir) are lazy. Each subdirectory is created on first access to its property and not before. Code that never reads a subdirectory property never causes its directory to appear on disk.

The laziness lets callers that fan out an OutputDirectory per simulation run (e.g. ParallelDesignedExperiment per design point, ConcurrentScenarioRunner per scenario) avoid materialising empty format-specific subdirectories under every run's folder when the model never writes Excel / DB / CSV / plot artefacts. The autoCreateOutFile flag lets those same callers suppress the per-run log file when they're operating in a flat (shared-directory) mode where a per-run log file would be noise rather than signal.

Parameters

outputDirectoryPath

the base output directory to use for writing text files relative to this OutputDirectory instance

outFileName

the name of the file backing the out property when autoCreateOutFile is true; ignored otherwise

autoCreateOutFile

when true (default), create outFileName under outDir at construction time and back out with it. When false, no file is created and out is a no-op writer that discards everything written to it.

Constructors

OutputDirectory

constructor(outputDirectoryPath: Path = KSLFileUtil.programLaunchDirectory, outFileName: String = "out.txt", autoCreateOutFile: Boolean = true)

constructor(outDirName: String = "OutputDir", outFileName: String = "out.txt", autoCreateOutFile: Boolean = true)

Creates a OutputDirectory with the current program launch directory with the base directory

Types

Companion

object Companion

Properties

csvDir

val csvDir: Path

The path to the default CSV directory, relative to this output directory. Lazily created on first access (see excelDir).

dbDir

val dbDir: Path

The path to the default database directory, relative to this output directory. Lazily created on first access (see excelDir).

excelDir

val excelDir: Path

The path to the default Excel directory, relative to this output directory. Lazily created on first access — OutputDirectory instances that never read this property never cause excelDir/ to appear on disk.

out

val out: LogPrintWriter

Can be used like System.out, but writes to a file in outDir when autoCreateOutFile is true. When false, this writer discards everything written to it (wraps Writer.nullWriter()) and no file is created on disk.

outDir

var outDir: Path

The path to the default output directory. Always created eagerly regardless of autoCreateOutFile — the directory itself is the routing target the caller supplied; only the file contents are optional.

plotDir

val plotDir: Path

The path to the default plot directory, relative to this output directory. Lazily created on first access (see excelDir).

Functions

createFile

fun createFile(fileName: String): File

Makes a new PrintWriter within the base directory with the given file name

createPrintWriter

fun createPrintWriter(fileName: String): PrintWriter

Makes a new PrintWriter within the base directory with the given file name

createSubDirectory

fun createSubDirectory(dirName: String): Path

Makes a Path to the named subdirectory within the base directory

toRenderContext

fun OutputDirectory.toRenderContext(confidenceLevel: Double = 0.95, numericPrecision: Int = 4, maxPlotsPerSection: Int = 20): RenderContext

Creates a RenderContext whose output and plot directories are rooted in this OutputDirectory.

toString

open override fun toString(): String

Resolves a path to the named subdirectory without creating it. Used by toString so that printing an OutputDirectory doesn't trigger materialisation of the lazy subdirectories.