Skip to content

Add multi-line ('''...''') string literals to the Legend grammar - #4998

Open
rafaelbey wants to merge 1 commit into
masterfrom
multi-line-string
Open

Add multi-line ('''...''') string literals to the Legend grammar#4998
rafaelbey wants to merge 1 commit into
masterfrom
multi-line-string

Conversation

@rafaelbey

@rafaelbey rafaelbey commented Jul 29, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Adds Java text-block style multi-line string literals ('''...''') to the Legend grammar.

function model::greeting(): String[1]
{
  let banner = '''
    Welcome to Legend.
      This line keeps its own indentation.
    ''';
  $banner;
}

Accepted wherever a string literal is: function bodies, let statements, graph-fetch trees and embedded data.

Tagged values are deliberately out of scope for now — see "Known gap" below.

Design: authored-as-a-block, not inferred

A block is re-emitted as a block only when it was authored as one, tracked by a multiLine flag on CString. The parser sets it from the token shape alone; the composer obeys it. Neither inspects the value — there is no heuristic anywhere.

The alternative — deciding from the value (e.g. "ends in a newline") — would silently reformat existing literals into ''' blocks on the next save, across every model in the wild.

multiLine is formatting metadata and never affects a value's meaning:

  • excluded from CString.equals / hashCode — the same characters are the same string;
  • @JsonInclude(NON_DEFAULT) keeps it off the wire unless a block is actually used;
  • threaded through CStringDeserializer, which otherwise dropped it on every JSON round-trip (Studio's flow is grammar → JSON → grammar, so without this the feature would have been a no-op there).

Parity with legend-pure

Legend Pure has its own text-block implementation in a separate parser. PureGrammarParserUtility.processTextBlock is kept behaviourally identical to legend-pure's processMultilineString, so both grammars accept the same source and produce the same value:

  • opening ''' must be followed — after optional spaces or tabs — by a line terminator;
  • line terminators normalized; opening-delimiter line and closing ''' dropped;
  • minimum indentation computed over non-blank lines plus the last (closing-delimiter) line;
  • indentation measured with Character.isWhitespace;
  • trailing whitespace stripped per line;
  • escapes processed last.

That closing-delimiter line is load-bearing rather than cosmetic: it is what pins the strip width, so a value's own indentation survives. Without it, " a\n b" would come back as "a\nb".

Round-trip safety

Trusting the flag puts the burden on the composer: it must encode any value so the parser reads it back unchanged. The parser dedents, strips trailing whitespace per line, then unescapes — so anything those steps would consume is emitted as an escape rather than a raw character:

Value contains Emitted as
\r \r escape — a raw CR would normalize to \n
''' \'\'\' — raw would terminate the block early
trailing whitespace on a line unicode escape — raw would be stripped
a whitespace-only line unicode escapes — raw would read back empty
no trailing newline closing delimiter on the last content line, with each line's own leading whitespace escaped so the indentation strip cannot eat it

testFlagIsObeyedForAnyValue drives a battery of these through compose → parse, asserting value equality and a composing fixed point.

Tests

  • TestTextBlockStringParsing (11) — value extraction: indentation, trailing-whitespace stripping, blank lines, escapes, CR normalization, block detection.
  • TestMultiLineStringRoundtrip (17) — round-trip fixtures plus the behavioural rules: single-line literals never reformat, indentation preservation, each fallback, multiLine surviving the JSON protocol, and an unterminated-block parser error.
  • TestServiceGrammarRoundtrip (21) — unchanged from master, confirming no downstream DSL is affected by the stricter lexer.

Grammar module: 325 tests, 0 failures, 0 Checkstyle violations.

A full mvn clean install over the whole 600-module reactor was run against an earlier revision of this branch that also covered tagged values — PCT suites green there (Java binding 1117; 1205 each for H2, DuckDB, SqlServer, Trino, Spanner). The current revision is strictly smaller: dropping tagged-value support only reverts files to master, so that evidence still holds for everything that remains.

Two modules fail in that run and neither is related to this change — both reproduce independently of it:

  • TestQueryStoreManager — a file-descriptor leak in the test class itself. JUnit 4 builds a new instance per test method, so the field initializer creates one TestMongoClientProvider, @Before replaces it with a second, and @After closes only the second; the first leaks a bound socket and a netty selector per test. A single method run in isolation passes.
  • Test_Relational_ClickHouse_PCT — four exp/log exclusions in EssentialFunctions_manifest.json report as "expected to fail but now PASSES" on an Apple Silicon host. The image is pinned (25.1.1-alpine), so this is architecture, not version: the container runs linux/arm64 locally and x86-64 in CI, and ClickHouse's vectorized exp/log fast paths on x86-64 differ from the libm results the ARM build produces. The exclusions are correct for CI and should not be removed — this is local-only noise.

Known gap: tagged values

legend-pure accepts multi-line strings in tagged values too — the documentation use case, doc.doc = '''...'''. This PR does not.

TaggedValue carries a bare String with nowhere to record how it was authored, so symmetric support would need a second protocol flag plus its own indentation handling threaded through the annotation renderer. That was not clean enough to carry, so it is deferred until the composer side can be expressed as simply as it is for CString.

A ''' block in a tagged value still parses and its value is dedented correctly; it just composes back as an escaped single-line string. Value preserved, block formatting lost on round-trip. Tracked in the type-system doc's divergence register.

Docs

docs/engineering/architecture/type-system.md — a deliberately thin page recording that the type system is inherited from Legend Pure, where the engine touches it, and a standing register of divergences. §3.1 documents the text-block contract with an explicit "if you change one, change the other" note.

Also removes an empty, unreferenced placeholder class (shared.core.api.grammar.Parser).

🤖 Generated with Claude Code

@rafaelbey
rafaelbey requested a review from a team as a code owner July 29, 2026 15:52
@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Build

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Build
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785340339000, 1785340342000
	Checkout repo : 1785340342000, 1785340346000
	Cache Maven dependencies : 1785340346000, 1785340356000
	Set up JDK : 1785340356000, 1785340366000
	Check Java version : 1785340366000, 1785340366000
	Configure git : 1785340366000, 1785340366000
	Download deps and plugins : 1785340366000, 1785340392000
	Restore legend-pure snapshot : done, 1785340392000, 1785340392000
	Set pure version override : 1785340392000, 1785340392000
	Collect Workflow Telemetry : 1785340392000, 1785340392000
	Set profiles that required github secrets : 1785340392000, 1785340392000
	Purge stale legend-engine artifacts from local Maven repo : 1785340392000, 1785340392000
	Build (PR) : 1785340392000, 1785347199000
	Build (Master + Docker Snapshot) : done, 1785347199000, 1785347199000
	Upload build output : 1785347199000, 1785347502000
	Upload m2 repository : 1785347502000, 1785347527000
	Purge engine artifacts before cache save : 1785347527000, 1785347527000
	Set Test Matrix : 1785347527000, 1785347527000
	Upload CI Event : 1785347527000, 1785347527000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - graphql

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Test Module - graphql
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347554000, 1785347555000
	Checkout repo : 1785347555000, 1785347560000
	Before Test : 1785347560000, 1785347692000
	Restore legend-pure snapshot : done, 1785347692000, 1785347692000
	Included Modules : 1785347692000, 1785347692000
	Test : 1785347692000, 1785347812000
	Upload Test Results : 1785347812000, 1785347813000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - duckdb

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Test Module - duckdb
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347560000, 1785347561000
	Checkout repo : 1785347561000, 1785347564000
	Before Test : 1785347564000, 1785347706000
	Restore legend-pure snapshot : done, 1785347706000, 1785347706000
	Included Modules : 1785347706000, 1785347706000
	Test : 1785347706000, 1785347842000
	Upload Test Results : 1785347842000, 1785347842000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - clickhouse

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Test Module - clickhouse
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347554000, 1785347555000
	Checkout repo : 1785347555000, 1785347560000
	Before Test : 1785347560000, 1785347718000
	Restore legend-pure snapshot : done, 1785347718000, 1785347718000
	Included Modules : 1785347718000, 1785347718000
	Test : 1785347718000, 1785347848000
	Upload Test Results : 1785347848000, 1785347849000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - spanner

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Test Module - spanner
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347560000, 1785347561000
	Checkout repo : 1785347561000, 1785347564000
	Before Test : 1785347564000, 1785347725000
	Restore legend-pure snapshot : done, 1785347725000, 1785347725000
	Included Modules : 1785347725000, 1785347725000
	Test : 1785347725000, 1785347862000
	Upload Test Results : 1785347862000, 1785347862000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - postgres

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Test Module - postgres
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347554000, 1785347555000
	Checkout repo : 1785347555000, 1785347560000
	Before Test : 1785347560000, 1785347721000
	Restore legend-pure snapshot : done, 1785347721000, 1785347721000
	Included Modules : 1785347721000, 1785347721000
	Test : 1785347721000, 1785347870000
	Upload Test Results : 1785347870000, 1785347870000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - h2

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Test Module - h2
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347554000, 1785347555000
	Checkout repo : 1785347555000, 1785347560000
	Before Test : 1785347560000, 1785347725000
	Restore legend-pure snapshot : done, 1785347725000, 1785347725000
	Included Modules : 1785347725000, 1785347725000
	Test : 1785347725000, 1785347893000
	Upload Test Results : 1785347893000, 1785347893000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - sqlserver

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Test Module - sqlserver
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347555000, 1785347556000
	Checkout repo : 1785347556000, 1785347560000
	Before Test : 1785347560000, 1785347796000
	Restore legend-pure snapshot : done, 1785347796000, 1785347796000
	Included Modules : 1785347796000, 1785347797000
	Test : 1785347797000, 1785347917000
	Upload Test Results : 1785347917000, 1785347918000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - elasticsearch

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Test Module - elasticsearch
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347555000, 1785347558000
	Checkout repo : 1785347558000, 1785347561000
	Before Test : 1785347561000, 1785347770000
	Restore legend-pure snapshot : done, 1785347770000, 1785347770000
	Included Modules : 1785347770000, 1785347770000
	Test : 1785347770000, 1785347927000
	Upload Test Results : 1785347927000, 1785347928000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - relationalStore

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Test Module - relationalStore
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347560000, 1785347561000
	Checkout repo : 1785347561000, 1785347565000
	Before Test : 1785347565000, 1785347719000
	Restore legend-pure snapshot : done, 1785347719000, 1785347719000
	Included Modules : 1785347719000, 1785347719000
	Test : 1785347719000, 1785347938000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - oracle

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Test Module - oracle
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347556000, 1785347558000
	Checkout repo : 1785347558000, 1785347561000
	Before Test : 1785347561000, 1785347760000
	Restore legend-pure snapshot : done, 1785347760000, 1785347760000
	Included Modules : 1785347760000, 1785347760000
	Test : 1785347760000, 1785347946000
	Upload Test Results : 1785347946000, 1785347947000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - deephaven

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Test Module - deephaven
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347554000, 1785347555000
	Checkout repo : 1785347555000, 1785347560000
	Before Test : 1785347560000, 1785347707000
	Restore legend-pure snapshot : done, 1785347707000, 1785347707000
	Included Modules : 1785347707000, 1785347707000
	Test : 1785347707000, 1785348043000
	Upload Test Results : 1785348043000, 1785348044000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - trino

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Test Module - trino
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347555000, 1785347556000
	Checkout repo : 1785347556000, 1785347560000
	Before Test : 1785347560000, 1785347819000
	Restore legend-pure snapshot : done, 1785347819000, 1785347819000
	Included Modules : 1785347819000, 1785347819000
	Test : 1785347819000, 1785348057000
	Upload Test Results : 1785348057000, 1785348058000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - memsql

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Test Module - memsql
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347560000, 1785347563000
	Checkout repo : 1785347563000, 1785347566000
	Before Test : 1785347566000, 1785347751000
	Restore legend-pure snapshot : done, 1785347751000, 1785347751000
	Included Modules : 1785347751000, 1785347751000
	Test : 1785347751000, 1785348095000
	Upload Test Results : 1785348095000, 1785348097000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - sql

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Test Module - sql
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347554000, 1785347556000
	Checkout repo : 1785347556000, 1785347560000
	Before Test : 1785347560000, 1785347716000
	Restore legend-pure snapshot : done, 1785347716000, 1785347716000
	Included Modules : 1785347716000, 1785347716000
	Test : 1785347716000, 1785348142000
	Upload Test Results : 1785348142000, 1785348143000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - core

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Test Module - core
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347555000, 1785347556000
	Checkout repo : 1785347556000, 1785347561000
	Before Test : 1785347561000, 1785347796000
	Restore legend-pure snapshot : done, 1785347796000, 1785347796000
	Included Modules : 1785347796000, 1785347796000
	Test : 1785347796000, 1785348235000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - javaBinding

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Test Module - javaBinding
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347560000, 1785347561000
	Checkout repo : 1785347561000, 1785347563000
	Before Test : 1785347563000, 1785347722000
	Restore legend-pure snapshot : done, 1785347722000, 1785347722000
	Included Modules : 1785347722000, 1785347722000
	Test : 1785347722000, 1785348244000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - ide-tools

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Test Module - ide-tools
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347560000, 1785347562000
	Checkout repo : 1785347562000, 1785347565000
	Before Test : 1785347565000, 1785348134000
	Restore legend-pure snapshot : done, 1785348134000, 1785348134000
	Included Modules : 1785348134000, 1785348134000
	Test : 1785348134000, 1785348509000
	Upload Test Results : 1785348509000, 1785348510000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - python

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Test Module - python
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347561000, 1785347562000
	Checkout repo : 1785347562000, 1785347568000
	Before Test : 1785347568000, 1785347781000
	Restore legend-pure snapshot : done, 1785347781000, 1785347781000
	Included Modules : 1785347781000, 1785347781000
	Test : 1785347781000, 1785349237000
	Upload Test Results : 1785349237000, 1785349238000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - databricks

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Test Module - databricks
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347554000, 1785347555000
	Checkout repo : 1785347555000, 1785347560000
	Before Test : 1785347560000, 1785347748000
	Restore legend-pure snapshot : done, 1785347748000, 1785347748000
	Included Modules : 1785347748000, 1785347748000
	Test : 1785347748000, 1785349351000
	Upload Test Results : 1785349351000, 1785349352000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Run Unit Tests

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Run Unit Tests
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347554000, 1785347555000
	Checkout repo : 1785347555000, 1785347560000
	Before Test : 1785347560000, 1785347711000
	Restore legend-pure snapshot : done, 1785347711000, 1785347711000
	Excluded Modules : 1785347711000, 1785347711000
	Test : 1785347711000, 1785349366000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - server

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Test Module - server
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347554000, 1785347555000
	Checkout repo : 1785347555000, 1785347560000
	Before Test : 1785347560000, 1785347722000
	Restore legend-pure snapshot : done, 1785347722000, 1785347722000
	Included Modules : 1785347722000, 1785347722000
	Test : 1785347722000, 1785349482000
	Upload Test Results : 1785349482000, 1785349483000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - snowflake

Workflow telemetry for commit d0484afa9e7f048716a9f0f824564f684269dcfe
You can access workflow job details here

Step Trace

gantt
	title Test Module - snowflake
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785347560000, 1785347562000
	Checkout repo : 1785347562000, 1785347566000
	Before Test : 1785347566000, 1785348078000
	Restore legend-pure snapshot : done, 1785348078000, 1785348078000
	Included Modules : 1785348078000, 1785348078000
	Test : 1785348078000, 1785349968000
	Upload Test Results : 1785349968000, 1785349969000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026 •
edited
Loading

Copy link
Copy Markdown

Test Results

  1 066 files  +  2    1 066 suites  +2   4h 13m 26s ⏱️ - 6m 2s
19 835 tests +27  19 656 ✔️ +27  179 💤 ±0  0 ❌ ±0 
44 034 runs  +27  43 855 ✔️ +27  179 💤 ±0  0 ❌ ±0 

Results for commit 38c6254. ± Comparison against base commit ab7a53c.

♻️ This comment has been updated with latest results.

@rafaelbey
rafaelbey force-pushed the multi-line-string branch from d0484af to e17c370 Compare July 29, 2026 19:27
@rafaelbey
Add multi-line ('''...''') string literals to the Legend grammar
38c6254 
Adds Java text-block style triple-quoted string literals, accepted wherever a
string literal is: function bodies, let statements, graph-fetch trees and
embedded data.

Whether a literal is a block is recorded on a multiLine flag on CString, set
from the token shape alone, and the composer simply obeys it. Nothing inspects
the value to decide - a block is a block because it was written as one, so an
existing literal never reformats on save. The flag is formatting metadata:
excluded from equals, kept off the wire via @JsonInclude(NON_DEFAULT), and
threaded through CStringDeserializer so it survives the JSON round-trip.

Trusting the flag puts the burden on the composer, which must encode any value
so the parser reads it back unchanged. The parser dedents, strips trailing
whitespace per line and then unescapes, so anything those steps would consume is
emitted as an escape rather than a raw character: carriage returns, an embedded
''', trailing whitespace, whitespace-only lines, and - when the value has no
trailing newline, so the closing delimiter shares the last content line - each
line's own leading whitespace.

Parsing is kept behaviourally identical to legend-pure's processMultilineString
so both grammars accept the same source and produce the same value.

Tagged values are deliberately left out for now. legend-pure supports them, but
TaggedValue carries a bare String with nowhere to record how it was authored, so
symmetric support would need a second protocol flag plus its own indentation
handling in the annotation renderer. Deferred until that composer side can be as
simple as it is for CString; a block in a tagged value still parses, it just
composes back single-line.

Documents the type system and this gap in
docs/engineering/architecture/type-system.md.

Also removes an empty, unreferenced placeholder class
(shared.core.api.grammar.Parser).
@rafaelbey
rafaelbey force-pushed the multi-line-string branch from e17c370 to 38c6254 Compare July 29, 2026 20:11
@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Build

Workflow telemetry for commit e17c370de0a83b9954f5b3e8fe00b10e13c9c8ad
You can access workflow job details here

Step Trace

gantt
	title Build
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785353286000, 1785353288000
	Checkout repo : 1785353288000, 1785353293000
	Cache Maven dependencies : 1785353293000, 1785353303000
	Set up JDK : 1785353303000, 1785353309000
	Check Java version : 1785353309000, 1785353309000
	Configure git : 1785353309000, 1785353309000
	Download deps and plugins : 1785353309000, 1785353333000
	Restore legend-pure snapshot : done, 1785353333000, 1785353333000
	Set pure version override : 1785353333000, 1785353333000
	Collect Workflow Telemetry : 1785353333000, 1785353333000
	Set profiles that required github secrets : 1785353333000, 1785353333000
	Purge stale legend-engine artifacts from local Maven repo : 1785353333000, 1785353333000
	Build (PR) : 1785353333000, 1785359942000
	Build (Master + Docker Snapshot) : done, 1785359942000, 1785359942000
	Upload build output : 1785359942000, 1785360292000
	Upload m2 repository : 1785360292000, 1785360318000
	Purge engine artifacts before cache save : 1785360318000, 1785360318000
	Set Test Matrix : 1785360318000, 1785360318000
	Upload CI Event : 1785360318000, 1785360318000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Build

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Build
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785360352000, 1785360357000
	Checkout repo : 1785360357000, 1785360363000
	Cache Maven dependencies : 1785360363000, 1785360376000
	Set up JDK : 1785360376000, 1785360388000
	Check Java version : 1785360388000, 1785360388000
	Configure git : 1785360388000, 1785360388000
	Download deps and plugins : 1785360388000, 1785360407000
	Restore legend-pure snapshot : done, 1785360407000, 1785360407000
	Set pure version override : 1785360407000, 1785360407000
	Collect Workflow Telemetry : 1785360407000, 1785360407000
	Set profiles that required github secrets : 1785360407000, 1785360407000
	Purge stale legend-engine artifacts from local Maven repo : 1785360407000, 1785360407000
	Build (PR) : 1785360407000, 1785366082000
	Build (Master + Docker Snapshot) : done, 1785366082000, 1785366082000
	Upload build output : 1785366082000, 1785366458000
	Upload m2 repository : 1785366458000, 1785366481000
	Purge engine artifacts before cache save : 1785366481000, 1785366481000
	Set Test Matrix : 1785366481000, 1785366481000
	Upload CI Event : 1785366481000, 1785366482000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - duckdb

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Test Module - duckdb
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366509000, 1785366510000
	Checkout repo : 1785366510000, 1785366515000
	Before Test : 1785366515000, 1785366672000
	Restore legend-pure snapshot : done, 1785366672000, 1785366672000
	Included Modules : 1785366672000, 1785366672000
	Test : 1785366672000, 1785366809000
	Upload Test Results : 1785366809000, 1785366809000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - clickhouse

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Test Module - clickhouse
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366509000, 1785366510000
	Checkout repo : 1785366510000, 1785366515000
	Before Test : 1785366515000, 1785366670000
	Restore legend-pure snapshot : done, 1785366670000, 1785366670000
	Included Modules : 1785366670000, 1785366670000
	Test : 1785366670000, 1785366810000
	Upload Test Results : 1785366810000, 1785366811000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - elasticsearch

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Test Module - elasticsearch
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366509000, 1785366510000
	Checkout repo : 1785366510000, 1785366516000
	Before Test : 1785366516000, 1785366681000
	Restore legend-pure snapshot : done, 1785366681000, 1785366681000
	Included Modules : 1785366681000, 1785366681000
	Test : 1785366681000, 1785366829000
	Upload Test Results : 1785366829000, 1785366830000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - postgres

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Test Module - postgres
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366510000, 1785366512000
	Checkout repo : 1785366512000, 1785366515000
	Before Test : 1785366515000, 1785366685000
	Restore legend-pure snapshot : done, 1785366685000, 1785366685000
	Included Modules : 1785366685000, 1785366685000
	Test : 1785366685000, 1785366830000
	Upload Test Results : 1785366830000, 1785366831000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - h2

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Test Module - h2
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366509000, 1785366511000
	Checkout repo : 1785366511000, 1785366516000
	Before Test : 1785366516000, 1785366688000
	Restore legend-pure snapshot : done, 1785366688000, 1785366688000
	Included Modules : 1785366688000, 1785366688000
	Test : 1785366688000, 1785366847000
	Upload Test Results : 1785366847000, 1785366848000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - sqlserver

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Test Module - sqlserver
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366509000, 1785366511000
	Checkout repo : 1785366511000, 1785366516000
	Before Test : 1785366516000, 1785366718000
	Restore legend-pure snapshot : done, 1785366718000, 1785366718000
	Included Modules : 1785366718000, 1785366718000
	Test : 1785366718000, 1785366850000
	Upload Test Results : 1785366850000, 1785366851000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - graphql

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Test Module - graphql
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366516000, 1785366517000
	Checkout repo : 1785366517000, 1785366520000
	Before Test : 1785366520000, 1785366737000
	Restore legend-pure snapshot : done, 1785366737000, 1785366737000
	Included Modules : 1785366737000, 1785366737000
	Test : 1785366737000, 1785366853000
	Upload Test Results : 1785366853000, 1785366855000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - oracle

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Test Module - oracle
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366509000, 1785366510000
	Checkout repo : 1785366510000, 1785366515000
	Before Test : 1785366515000, 1785366677000
	Restore legend-pure snapshot : done, 1785366677000, 1785366677000
	Included Modules : 1785366677000, 1785366677000
	Test : 1785366677000, 1785366858000
	Upload Test Results : 1785366858000, 1785366859000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - relationalStore

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Test Module - relationalStore
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366509000, 1785366510000
	Checkout repo : 1785366510000, 1785366515000
	Before Test : 1785366515000, 1785366662000
	Restore legend-pure snapshot : done, 1785366662000, 1785366662000
	Included Modules : 1785366662000, 1785366662000
	Test : 1785366662000, 1785366873000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - spanner

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Test Module - spanner
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366509000, 1785366512000
	Checkout repo : 1785366512000, 1785366516000
	Before Test : 1785366516000, 1785366718000
	Restore legend-pure snapshot : done, 1785366718000, 1785366718000
	Included Modules : 1785366718000, 1785366718000
	Test : 1785366718000, 1785366873000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - trino

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Test Module - trino
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366517000, 1785366518000
	Checkout repo : 1785366518000, 1785366522000
	Before Test : 1785366522000, 1785366690000
	Restore legend-pure snapshot : done, 1785366690000, 1785366690000
	Included Modules : 1785366690000, 1785366690000
	Test : 1785366690000, 1785366909000
	Upload Test Results : 1785366909000, 1785366911000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - memsql

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Test Module - memsql
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366509000, 1785366510000
	Checkout repo : 1785366510000, 1785366515000
	Before Test : 1785366515000, 1785366671000
	Restore legend-pure snapshot : done, 1785366671000, 1785366671000
	Included Modules : 1785366671000, 1785366671000
	Test : 1785366671000, 1785366947000
	Upload Test Results : 1785366947000, 1785366948000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - deephaven

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Test Module - deephaven
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366509000, 1785366510000
	Checkout repo : 1785366510000, 1785366515000
	Before Test : 1785366515000, 1785366680000
	Restore legend-pure snapshot : done, 1785366680000, 1785366680000
	Included Modules : 1785366680000, 1785366680000
	Test : 1785366680000, 1785367016000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - ide-tools

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Test Module - ide-tools
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366509000, 1785366511000
	Checkout repo : 1785366511000, 1785366515000
	Before Test : 1785366515000, 1785366675000
	Restore legend-pure snapshot : done, 1785366675000, 1785366675000
	Included Modules : 1785366675000, 1785366675000
	Test : 1785366675000, 1785367059000
	Upload Test Results : 1785367059000, 1785367060000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - core

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Test Module - core
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366515000, 1785366517000
	Checkout repo : 1785366517000, 1785366520000
	Before Test : 1785366520000, 1785366703000
	Restore legend-pure snapshot : done, 1785366703000, 1785366703000
	Included Modules : 1785366703000, 1785366703000
	Test : 1785366703000, 1785367144000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - sql

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Test Module - sql
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366516000, 1785366518000
	Checkout repo : 1785366518000, 1785366521000
	Before Test : 1785366521000, 1785366724000
	Restore legend-pure snapshot : done, 1785366724000, 1785366724000
	Included Modules : 1785366724000, 1785366724000
	Test : 1785366724000, 1785367156000
	Upload Test Results : 1785367156000, 1785367158000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - javaBinding

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Test Module - javaBinding
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366513000, 1785366515000
	Checkout repo : 1785366515000, 1785366518000
	Before Test : 1785366518000, 1785366742000
	Restore legend-pure snapshot : done, 1785366742000, 1785366742000
	Included Modules : 1785366742000, 1785366742000
	Test : 1785366742000, 1785367183000
	Upload Test Results : 1785367183000, 1785367184000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - server

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Test Module - server
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366509000, 1785366510000
	Checkout repo : 1785366510000, 1785366515000
	Before Test : 1785366515000, 1785366674000
	Restore legend-pure snapshot : done, 1785366674000, 1785366674000
	Included Modules : 1785366674000, 1785366674000
	Test : 1785366674000, 1785368006000
	Upload Test Results : 1785368006000, 1785368007000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - snowflake

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Test Module - snowflake
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366509000, 1785366511000
	Checkout repo : 1785366511000, 1785366515000
	Before Test : 1785366515000, 1785366675000
	Restore legend-pure snapshot : done, 1785366675000, 1785366675000
	Included Modules : 1785366675000, 1785366675000
	Test : 1785366675000, 1785368009000
	Upload Test Results : 1785368009000, 1785368010000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - python

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Test Module - python
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366509000, 1785366510000
	Checkout repo : 1785366510000, 1785366515000
	Before Test : 1785366515000, 1785366670000
	Restore legend-pure snapshot : done, 1785366670000, 1785366670000
	Included Modules : 1785366670000, 1785366670000
	Test : 1785366670000, 1785368108000
	Upload Test Results : 1785368108000, 1785368109000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Run Unit Tests

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Run Unit Tests
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366509000, 1785366509000
	Checkout repo : 1785366509000, 1785366514000
	Before Test : 1785366514000, 1785366654000
	Restore legend-pure snapshot : done, 1785366654000, 1785366654000
	Excluded Modules : 1785366654000, 1785366654000
	Test : 1785366654000, 1785368304000
Loading

@github-actions

github-actions Bot commented Jul 29, 2026

Copy link
Copy Markdown

Workflow Telemetry - Build CI / Test Module - databricks

Workflow telemetry for commit 38c6254da15fce9dd14250b6794fdbf2103dac25
You can access workflow job details here

Step Trace

gantt
	title Test Module - databricks
	dateFormat x
	axisFormat %H:%M:%S
	Set up job : milestone, 1785366510000, 1785366511000
	Checkout repo : 1785366511000, 1785366516000
	Before Test : 1785366516000, 1785366675000
	Restore legend-pure snapshot : done, 1785366675000, 1785366675000
	Included Modules : 1785366675000, 1785366675000
	Test : 1785366675000, 1785368523000
	Upload Test Results : 1785368523000, 1785368524000
Loading

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@rafaelbey