Chart syntax

The Chart syntax is a short way to write a chart as text, one row per line. Users type it into the Quick Input, and insertChartFrom, updateChartFrom and the tools for an AI model take it with the format id chart-syntax.

In the editor from A first chart:

editor.commands.insertChartFrom({ format: 'chart-syntax', content: 'bar\nJan | 42\nFeb | 48' })

The type line

A first line that holds only a chart type, such as bar or Pie, with any spaces around it, is the type line.

  • Without a type line, the chart takes the type option of the command, such as insertChartFrom, or else the chart.defaultType option.
  • The type line wins over the type option.
  • The type line stays in the text. editChartAsText writes it back, and setDiagramInputType rewrites it.

A type registered with chartTypes is a type line in the Quick Input only. In code, such a line is read as a data row, so pass the type as the type option instead.

How the rows are read

RuleHow it reads
DelimitersComma, semicolon, pipe and tab, set with chart.delimiters
HeaderThe first row, when each cell after the first is text and not a number
{H}In front of any one cell, makes its row the header
LabelsThe first column
{L}In front of a cell in the first data row, makes its column the label column
Empty cellA missing value
Not a numberText
QuotesText that may contain the delimiter. "" is one quote
ListsA leading •, -, *, 1. or 1) is ignored, so a pasted list reads as rows
Single columnLines without a delimiter are one series, labeled 1, 2, 3
Empty lineSkipped

So Month | Sales is a header and Jan | 2 a data row. A header with numbers needs {H}, such as {H}Region | 2025 | 2026.

Which delimiter splits

The first line with an allowed delimiter decides it for the whole text. On a line with several, tab wins over pipe, pipe over semicolon, and semicolon over comma. So Jan ; 1,5 splits at the semicolon and reads 1,5 as a number.

Numbers

A number is digits with an optional sign, decimals and exponent, such as -2.5e3. 50% is text.

  • With chart.decimalSeparator at its default 'auto', 1.5 is read as 1.5, and so is 1,5 when the delimiter is not a comma.
  • Set decimalSeparator to '.' or ',' to fix the decimal separator.
  • Spaces inside a number are ignored, so 1 000 is 1000. A dot or comma as a thousands separator is not: with 'auto' and a pipe as the delimiter, 1.000 and 1,000 are 1.

Errors

An unclosed quote is an error on its line, such as Line 3: A quote is opened and never closed.

Reading a chart as text

editor.storage.diagrams.read({ format: 'chart-syntax' }) returns the selected chart's data as Chart syntax text, without a type line, and pos picks another chart. It uses the delimiter the chart was typed with, or else the first of chart.delimiters, and writes decimals with a comma unless that delimiter is a comma.

A pipe gets a space on each side, a tab none, and any other delimiter one after it.