Move compile package source files into directories

[chrispcampbell]

As a minor follow-on to the monorepo refactoring that was completed for #191, I would like to reorganize the compile package source files into directories so that they are grouped logically by component:

• preprocess
• parse
• model
• generate

I'm also planning to rename the files to use lowercase-hyphen.js style instead of CamelCase.js for consistency with the cli package and with other forthcoming packages.

There should be no changes to the implementation; only the file locations and imports should be affected. This is the last planned refactoring for the cli and compile packages for now; the next phase will focus on adding new packages.

[chrispcampbell]

I spent a little while analyzing the source files in the compile package to get a sense of the dependency tree/graph. I've included my notes below (collapsed to save space). The notes are in the order of the dependencies, so later files depend on earlier ones. To summarize, the flow goes in this order:

• _shared
• preprocess
• parse
• model
• generate
• top-level (index)

The flow is mostly linear, though there are a couple cycles within the model module. Someday I would like to make the stages/modules more independent (parse -> AST -> generate), but the groupings in the current refactoring should be good enough for now.

Click to expand

//
// _shared
//
// helpers.js
// read-dat.js
// subscript.js
//

// helpers.js
// (only has external dependencies)

// read-dat.js
import { canonicalVensimName } from './helpers.js'

// subscript.js
// used by:
//   parse-and-generate.js
//   generate/code-gen.js
//   generate/equation-gen
//   generate/loop-index-vars.js
//   generate/model-lhs-reader.js
//   model/equation-reader.js
//   model/model.js
//   model/subscript-range-reader.js
//   model/variable-reader.js
//   model/var-name-reader.js
import { cFunctionName, matchRegex, readCsv } from './helpers.js'

/////////////////////////////////////////////////////////////////////////////////////////

//
// preprocess
//
// preprocess.js
//

// preprocess.js
import { splitEquations, replaceDelimitedStrings } from '../_shared/helpers.js'

/////////////////////////////////////////////////////////////////////////////////////////

//
// parse
//
// model-reader.js
// parser.js
//

// parser.js
// used by:
//   index.js
//   parse-and-generate.js
//   generate/model-lhs-reader.js
//   model/equation-reader.js
//   model/model.js
//   model/var-name-reader.js
import antlr4 from 'antlr4'
import { ModelLexer, ModelParser } from 'antlr4-vensim'

// model-reader.js
// used by:
//   generate/equation-gen.js
//   generate/model-lhs-reader.js
//   model/equation-reader.js
//   model/subscript-range-reader.js
//   model/variable-reader.js
//   model/var-name-reader.js
import { ModelVisitor } from 'antlr4-vensim'

/////////////////////////////////////////////////////////////////////////////////////////

//
// model
//
// model.js
//   equation-reader.js
//     expr-reader.js
//   subscript-range-reader.js
//   toposort.js
//   var-name-reader.js
// variable.js
// variable-reader.js

// equation-reader.js
// used by:
//   model/model.js
import {} from '../_shared/subscript.js'
import ModelReader from '../parse/model-reader.js'
import { createParser } from '../parse/parser.js'
import ExprReader from './expr-reader.js'
import Model from './model.js'
import VariableReader from './variable-reader.js'

// expr-reader.js
// used by:
//   model/equation-reader.js
import { createParser } from '../parse/parser.js'
import Model from './model.js'

// model.js
// used by:
//   parse-and-generate.js
//   generate/code-gen.js
//   generate/equation-gen.js
//   model/equation-reader.js (CYCLE!)
//   model/expr-reader.js (CYCLE!)
//   model/variable-reader.js
//   model/var-name-reader.js
import {} from '../_shared/subscript.js'
import { createParser } from '../parse/parser.js'
import EquationReader from './equation-reader.js'
import SubscriptRangeReader from './subscript-range-reader.js'
import toposort from './toposort.js'
import VarNameReader from './var-name-reader.js'
import VariableReader from './variable-reader.js'
import Variable from './variable.js'

// subscript-range-reader.js
// used by:
//   model/model.js
import { cFunctionName, matchRegex, readCsv } from './_shared/helpers.js'
import { Subscript } from '../_shared/subscript.js'
import ModelReader from '../parse/model-reader.js'

// toposort.js
// used by:
//   model/model.js
// (no dependencies)

// variable.js
// used by:
//   model/model.js
//   model/variable-reader.js
// (no dependencies)

// variable-reader.js
// used by:
//   model/equation-reader.js
//   model/model.js
import { canonicalName, vlog, strlist, cartesianProductOf } from '../_shared/helpers.js'
import { sub, isDimension, isIndex, normalizeSubscripts, isSubdimension } from '../_shared/subscript.js'
import ModelReader from '../parse/model-reader.js'
import Model from './model.js'
import Variable from './variable.js'

// var-name-reader.js
// used by:
//   model/model.js
import { canonicalName } from './_shared/helpers.js'
import { sub, isIndex, normalizeSubscripts } from '../_shared/subscript.js'
import ModelReader from '../parse/model-reader.js'
import { createParser } from '../parse/parser.js'

/////////////////////////////////////////////////////////////////////////////////////////

//
// generate
//
// code-gen.js
//   equation-gen.js
//     loop-index-vars.js
//   model-lhs-reader.js
//

// code-gen.js
// used by:
//   index.js
//   parse-and-generate.js
import { asort, lines, strlist, abend, mapIndexed } from '../_shared/helpers.js'
import { sub, allDimensions, allMappings, subscriptFamilies } from '../_shared/subscript.js'
import Model from '../model/model.js'
import ModelLHSReader from './model-lhs-reader.js'
import EquationGen from './equation-gen.js'

// equation-gen.js
// used by:
//   generate/code-gen.js
import { ModelLexer, ModelParser } from 'antlr4-vensim'
import {} from '../_shared/helpers.js'
import {} from '../_shared/subscript.js'
import ModelReader from '../parse/model-reader.js'
import Model from '../model/model.js'
import ModelLHSReader from './model-lhs-reader.js'
import LoopIndexVars from './loop-index-vars.js'

// loop-index-vars.js
// used by:
//   generate/equation-gen.js
import { isDimension } from '../_shared/subscript.js'

// model-lhs-reader.js
// used by:
//   generate/code-gen.js
//   generate/equation-gen.js
import { canonicalName } from '../_shared/helpers.js'
import { sub, isDimension } from '../_shared/subscript.js'
import ModelReader from '../parse/model-reader.js'
import { createParser } from '../parse/parser.js'

/////////////////////////////////////////////////////////////////////////////////////////

//
// top level
//
// index.js
// parse-and-generate.js
//

// index.js
export { canonicalName } from './_shared/helpers.js'
export { readDat } from './_shared/read-dat.js'
export { preprocessModel } from './preprocess/preprocessor.js'
export { parseModel } from './parse/parser.js'
export { generateCode } from './generate/code-gen.js'
export { parseAndGenerate, printNames } from './parse-and-generate.js'

// parse-and-generate.js
import { readXlsx } from './_shared/helpers.js'
import { readDat } from './_shared/read-dat.js'
import { printSubscripts, yamlSubsList } from './_shared/subscript.js'
import { parseModel } from './parse/parser.js'
import Model from './model/model.js'
import { generateCode } from './generate/code-gen.js'

[ToddFincannonEI]

The README has extensive documentation on the compile process, including a diagram of the linear flow that you described here. It might help make sense of the compile process going forward.

[chrispcampbell]

@ToddFincannonEI: Yep, that README documentation has been helpful for me in the past; the only thing new or different here was to employ a directory structure to help delineate and express the module (subsystem) boundaries to aid newcomers and to help accommodate future refactoring.