Google Apps Script:
Working with TOML

How to:

Since Google Apps Script is essentially JavaScript with access to Google’s suite of apps, working with TOML directly within Google Apps Script requires a bit of ingenuity. Google Apps Script doesn’t natively support TOML parsing, but you can leverage JavaScript libraries or write a simple parser for basic needs.

Let’s parse a simple TOML configuration string as an example:

// TOML string
var tomlString = `
[database]
server = "192.168.1.1"
ports = [ 8001, 8001, 8002 ]
connection_max = 5000
enabled = true
`;

// A simple TOML to JSON parser function
function parseTOML(tomlStr) {
  var result = {};
  var currentSection = result;
  tomlStr.split(/\r?\n/).forEach(line => {
    line = line.trim();
    if (line.startsWith('[')) { // New section
      var sectionName = line.replace(/\[|\]/g, '');
      result[sectionName] = {};
      currentSection = result[sectionName];
    } else if (line) {
      var keyValue = line.split('=').map(part => part.trim());
      var key = keyValue[0];
      var value = eval(keyValue[1]); // Use eval for simplicity; beware in production code
      currentSection[key] = value;
    }
  });
  return result;
}

// Test the parser
var configObject = parseTOML(tomlString);
console.log(configObject);

Sample output from the console.log would resemble a JSON object, making it easier to access the configuration properties within Google Apps Script:

{
  "database": {
    "server": "192.168.1.1",
    "ports": [8001, 8001, 8002],
    "connection_max": 5000,
    "enabled": true
  }
}

Deep Dive

TOML was created by Tom Preston-Werner, one of the founders of GitHub, to be more human-friendly than JSON for configuration files while retaining the ability to be unambiguously parsed. It aims to be as simple as possible, a goal that aligns nicely with the ethos of many development projects striving for simplicity and readability in their codebases.

In the context of Google Apps Script, using TOML can introduce some overhead, given the lack of direct support and the necessity to parse it manually or through third-party libraries. For smaller projects or those not deeply integrated into Google’s ecosystem, alternatives such as JSON or even simple key-value pair structures in script properties could suffice and be more straightforward to implement. However, for applications that prioritize human-friendly configuration files and are already committed to TOML, integrating TOML parsing through custom scripts adds a useful layer of flexibility and maintainability without departing from the preferred configuration paradigms.