Treat GET XLS ... as synonymous with GET DIRECT ...

[chrispcampbell]

In the past couple weeks I've received two models that use GET XLS DATA and other GET XLS variants.

On Windows, the GET XLS ... functions differ from GET DIRECT ... in that GET XLS opens Excel and uses it to read the data, whereas GET DIRECT does not use Excel and (presumably) uses a library instead to read the data.

On macOS, GET XLS ... is functionally equivalent to GET DIRECT ... functions.

So far my guidance has been to change their models to use GET DIRECT ... since it's mostly functionally equivalent, and is supported by SDE. But we could consider treating the GET XLS ... variants as synonymous with GET DIRECT ... variants, and that way no changes would be needed to models that use the GET XLS variants.

Workaround

Until such time that we update SDE as described above, users can apply the following changes to the sde.config.js file (note the changes marked with "CHRIS EDIT"):

    // The following files will cause the model to be rebuilt when watch mode is
    // is active.  Note that these are globs so we use forward slashes regardless
    // of platform.
    // CHRIS EDIT: Add 'model/*.xlsx' to the list of watch paths so that the
    // model is rebuilt any time there is a change to the xlsx files
    watchPaths: ['config/**', 'model/model.mdl', 'model/*.xlsx'],

    // Read csv files from `config` directory
    modelSpec: configProcessor({
      config: configDir,
      out: corePath(),
      // CHRIS EDIT: Specify a relative path to the xlsx files.  This is more
      // flexible, and also a workaround for the following SDE issue:
      //   https://github.com/climateinteractive/SDEverywhere/issues/303
      spec: {
        directData: {
          '?data': '../model/data.xlsx'
        }
      }
    }),

    plugins: [
      // CHRIS EDIT: Apply custom find/replace to the mdl file at build time to
      // perform the following replacements:
      //   1. Change "GET XLS ..." to the equivalent "GET DIRECT ..."
      //        GET XLS CONSTANTS -> GET DIRECT CONSTANTS
      //        GET XLS DATA -> GET DIRECT DATA
      //   2. Convert explicit xlsx file references to indirect tags (this form has
      //      better performance at compile time and also makes it easier to
      //      customize the relative file path below in `spec.directData`)
      //        'data.xlsx' -> '?data'
      {
        postProcessMdl: (_, mdl) => {
          mdl = mdl.replaceAll('GET XLS CONSTANTS', 'GET DIRECT CONSTANTS')
          mdl = mdl.replaceAll('GET XLS DATA', 'GET DIRECT DATA')
          mdl = mdl.replaceAll(`'data.xlsx'`, `'?data'`)
          return mdl
        }
      }

      // ... other plugins
    ]

Additional context

Compare the docs:

• GET XLS DATA
• GET DIRECT DATA

See also their general notes on GET XLS functions:
https://www.vensim.com/documentation/fn_get_xls____notes.html