ota-meshi/toml-eslint-parser

A TOML parser that produces output compatible with ESLint

toml-eslint-parser

A TOML parser that produces output compatible with ESLint.

Features

• Converts TOML text to AST.
• Support for TOML 1.0.0.
• Experimental support for TOML 1.1.0. (Specifications for November 2023)

Installation

npm install --save-dev toml-eslint-parser

Usage

Configuration

Use .eslintrc.* file to configure parser. See also: https://eslint.org/docs/user-guide/configuring.

Example .eslintrc.js:

module.exports = {
  overrides: [
    {
      files: ["*.toml"],
      parser: "toml-eslint-parser",
    },
  ],
};

Advanced Configuration

The following additional configuration options are available by specifying them in parserOptions in your ESLint configuration file.

Example .eslintrc.js:

module.exports = {
  overrides: [
    {
      files: ["*.toml"],
      parser: "toml-eslint-parser",
      // Additional configuration options
      parserOptions: {
        tomlVersion: "1.0.0",
      },
    },
  ],
};

parserOptions.tomlVersion

Select the TOML version by setting "1.0.0", "1.1.0", "1.0", "1.1", "latest", or "next". By default "1.0.0" is used.

• "1.0.0" ... Parsed using TOML v1.0.0 specifications.
• "1.0" ... Alias for "1.0.0".
• "1.1.0" ... Parsed using the TOML v1.1.0 specification, which is currently under development. TOML 1.1.0 has not been released yet, so "1.1.0" is still an experimental feature. Please note that this may be subject to breaking changes in minor version releases of this parser.
• "1.1" ... Alias for "1.1.0".
• "latest" ... Currently an alias for "1.0.0". When a new version of TOML is released, we plan to change to that version in a minor version release of this parser.
• "next" ... Currently an alias for "1.1.0".

Usage for Custom Rules / Plugins

• AST.md is AST specification.
• keys-order.ts is an example.
• You can see the AST on the Online DEMO.

Usage for Directly

Example:

import type { AST } from "toml-eslint-parser";
import { parseTOML, getStaticTOMLValue } from "toml-eslint-parser";

const code = `
# This is a TOML document

title = "TOML Example"

[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00

[database]
enabled = true
ports = [ 8001, 8001, 8002 ]
data = [ ["delta", "phi"], [3.14] ]
temp_targets = { cpu = 79.5, case = 72.0 }

[servers]

[servers.alpha]
ip = "10.0.0.1"
role = "frontend"

[servers.beta]
ip = "10.0.0.2"
role = "backend"
`;

const ast: AST.TOMLProgram = parseTOML(code);
console.log(ast);
// {
//   type: 'Program',
//   body: [
//     {
//       type: 'TOMLTopLevelTable',
//       body: [
//         {
//           type: 'TOMLKeyValue',
//           key: { /* ... */ },
//           value: { /* ... */ },
//           /* ... */
//         },
//         {
//           type: 'TOMLTable',
//           kind: 'standard',
//           key: { /* ... */ },
//           body: [ /* ... */ ],
//           /* ... */
//         },
//         /* ... */
//       ]
//       /* ... */
//     }
//   ],
//   tokens: [ /* ... */ ],
//   comments: [
//     {
//       type: 'Block',
//       value: ' This is a TOML document',
//       // ...
//     }
//   ],
// }

const value = getStaticTOMLValue(ast);
console.log(value);
// {
//   title: 'TOML Example',
//   owner: { name: 'Tom Preston-Werner', dob: 1979-05-27T15:32:00.000Z },
//   database: {
//     enabled: true,
//     ports: [ 8001, 8001, 8002 ],
//     data: [ [ /* ... */ ], [ /* ... */ ] ],
//     temp_targets: { cpu: 79.5, case: 72 }
//   },
//   servers: {
//     alpha: { ip: '10.0.0.1', role: 'frontend' },
//     beta: { ip: '10.0.0.2', role: 'backend' }
//   }
// }

Testing

This project uses files from BurntSushi/toml-test and iarna/toml-spec-tests repositories for testing.

Related Packages

• eslint-plugin-jsonc ... ESLint plugin for JSON, JSON with comments (JSONC) and JSON5.
• eslint-plugin-yml ... ESLint plugin for YAML.
• eslint-plugin-toml ... ESLint plugin for TOML.
• eslint-plugin-json-schema-validator ... ESLint plugin that validates data using JSON Schema Validator.
• jsonc-eslint-parser ... JSON, JSONC and JSON5 parser for use with ESLint plugins.
• yaml-eslint-parser ... YAML parser for use with ESLint plugins.

toml-eslint-parser's Issues

Support TOML 1.1

Changes for now: toml-lang/toml@1.0.0...main

Add to official (and unofficial) TOML lists

I found out about this parser because it was used to close renovatebot/renovate#18668.

It isn't listed:

• As an official implementation (though it is among the Validators and Formatter lists)
• Among the unofficial conformance / performance matrix

parser and AST as a separated library?

I want a library that implements AST for TOML for node.js. this eslint plugin looks to have that mechanism but is not a simple library. Could you publish it as a separate library?

Dependency Dashboard

This issue provides visibility into Renovate updates and their statuses. Learn more

This repository currently has no open or pending branches.

---

• Check this box to trigger a request for Renovate to run again on this repository

Idea: Support comments and whitespace

I'm not sure how hard it would be, but I have a use case to use this package as a tool for rewriting TOML files without affecting style and whitespaces. So, the first idea that I had would be to write a function which can take the toml eslint AST and generate the TOML source.

I'm not so sure how far away an idea like this is, but I feel like it's a small change to at the least maintain newlines and comments.

I'm not entirely sure, but I thought I'd throw this idea in here.

Cheers

– Cole