Riffle 0.1.0 is a small, deterministic, end-of-line-terminated configuration language. Java 17 is the reference implementation in this repository, but the language is defined independently of Java.
LANGUAGE_SPEC.md is the normative specification for every implementation; this file is the Java binding guide. Java type names in the spec appear only in non-normative appendices.
- Every entry is
key = valueand ends at the end of its line. - Nonempty collections open on their own line and close on their own line; an empty collection may be written inline as
{}or[]. Indentation has no syntactic significance. - String is the default scalar type; every other scalar says so with an
@typemarker. - Values are never inferred:
123,true,nulland~are strings. - Comments are
#or//, on their own line or after whitespace.
schemaVersion = @int 1
provider = chatgpt
model = gpt-6-sol
transport = chatgpt-oauth
capabilities = {
tools = @boolean true
streaming = @boolean true
contextWindow = @int 272000
maxOutputTokens = @int 128000
reasoning = [
none
low
medium
high
xhigh
max
]
defaultReasoning = high
tokenizer = heuristic
replayRequirements = [
chatgpt-oauth
]
}
options = {
chatgpt-oauth = {}
}
Blank lines group entries for readability; they are allowed and ignored, and the canonical writer does not emit them.
- Files are UTF-8. A byte-order mark at the start is ignored; a BOM anywhere else is an error. The writer escapes U+FEFF inside values and keys, so such a value still round-trips.
- Line endings are LF or CRLF. A lone carriage return is an error.
- Spaces and tabs separate tokens and indent lines. Indentation is never significant.
- Blank lines and comment lines are ignored, including inside collections.
- Every entry and array element occupies its own line. A nonempty collection's opener must be the last token on its line and its closer must be on its own line; an empty collection may also be written as an empty block.
- Strings do not span lines. Use
\ninside a quoted string.
- A full-line comment begins after optional indentation with
#or//. - An inline comment begins only when
#or//follows at least one space or tab, and is never inside a quoted string. A"opens a quoted string only as the first character of a key or value, sok = he said "hi" # cends at#. - Without preceding whitespace, a marker is part of a bare string:
https://example.org/a#fragmentandpath//segmentare unchanged. name = hello #worldhas the valuehello; write"hello #world"for the whole text.
- The document root is an implicit, insertion-ordered map.
- An empty map may be written
{}or as{and}on separate lines; a nonempty map is written in block form. - Nonempty collections are never written inline, and the canonical writer writes empty ones as
{}or[].
An empty collection may be written inline or as an empty block; a populated one is written in block form. The writer normalizes an empty block to the inline form. Turning an empty collection into a populated one moves the content onto its own lines — these are two separate documents:
Empty:
options = {
chatgpt-oauth = {}
}
Populated:
options = {
chatgpt-oauth = {
key = Test value
}
}
Arrays work the same way: tools = [] becomes tools = [, one element per line, then ]. Writing chatgpt-oauth = { key = Test value } is rejected, because a value runs to the end of its line — a nonempty collection cannot be inline.
- A bare key matches
[A-Za-z0-9_][A-Za-z0-9_.-]*:provider,chatgpt-oauth,1,schema.version. - Any other key is quoted, using the string escapes:
"key with spaces" = value. - A dot in a key is a literal dot, not a path separator.
- Keys are always strings and are case-sensitive. Duplicate keys in one map are an error.
String is the default. Every other scalar carries a marker.
| Kind | Syntax | Java 17 type |
|---|---|---|
| string | text, "text", @string text |
String |
| int | @int 42 |
Integer |
| long | @long 42 |
Long |
| decimal | @decimal 0.25 |
BigDecimal |
| boolean | @boolean true |
Boolean |
| null | @null |
dedicated null value |
| map | {} or { … } |
RiffleObject |
| array | [] or [ … ] |
RiffleArray |
The Java column is informative. The portable definitions and ranges are in LANGUAGE_SPEC.md.
@intis a signed 32-bit kind and@longis a signed 64-bit kind. They stay distinct even where a host language has one integer type.- Integers are base 10 with an optional
-;+, underscores, hex, leading zeros and decimal points are rejected. - Decimals use
-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?. The writer emits the normalized value, so@decimal 1.0is written@decimal 1. Canonical rendering uses the fixed algorithm in spec §11.3. @nulltakes no payload.@floatand any other unknown type is an error.
- Trimmed at both ends, interior whitespace preserved.
key =is the empty string. - The first character must not be
@,{,[,},]or"; quote values that start with them. - Control characters are invalid in a bare string; quote and escape them.
- A quoted value is EOL-delimited: its opening and closing
"are the first and last quotes before optional trailing whitespace and an optional inline comment. Interior"characters are literal data;\"is still accepted and means the same thing. A closing quote is required on the line. - Escapes are exactly
\",\\,\n,\r,\t,\b,\fand\uXXXXwith surrogate pairs handled correctly. - Invalid escapes, isolated surrogates, unclosed quotes and literal control characters are errors.
- Quoted keys keep their old rule: the first unescaped
"closes the key, because a key ends at=rather than EOL. Interior quotes in keys must be written\".
literalMarker = "@int 123"
literalComment = "# not a comment"
"display name" = Jane Doe
padded = " keeps spaces "
multiline = "line one\nline two"
a = "He said "hello""
b = "He said \"hello\""
Both a and b above decode to He said "hello". When a value must be quoted, the canonical writer prefers the literal form. For quoted values, an inline comment is recognized before a later quote, so k = "a # b" # comment "text" has value a # b. When a value needs " # text or " // text as data, escape that interior quote: k = "a\" # text". Keys keep emitting escaped interior quotes.
The writer removes quotes that are not needed ("display name" keeps them, Jane Doe does not) and escapes line breaks.
An untyped array holds one value per line and may mix kinds:
values = [
hello
@int 123
@boolean true
@null
{
name = example
}
[
one
two
]
]
A bare null element is the string "null"; the null value is @null.
@type [ supplies the element type for immediate elements only, and @type [] is an empty typed array. Element kinds are string, int, long, decimal, boolean, null, map and array.
ports = @int [
8080
8081
]
flags = @boolean [
true
false
]
servers = @map [
{
host = a.example
}
{}
]
rows = @array [
[
@int 1
]
@int [
2
3
]
]
Inside a typed array, elements are written without repeating the marker: @int [ elements are integers, @null [ elements are the literal word null, @map [ elements are maps, and @array [ elements are arrays or nested typed arrays. A typed array and an untyped array of the same typed elements are the same value, so @int [\n 1\n] equals [\n @int 1\n].
Typed arrays are authoring sugar: the canonical writer emits untyped arrays with @type elements, so ports = @int [ … ] is written as ports = [ with @int 8080 elements.
| Rejected | Write instead |
|---|---|
key { / key [ |
key = { / key = [ |
key : value |
key = value |
a root wrapped in { … } |
the implicit root map |
| a root array | a map |
x = { a = b } |
the map on following lines |
x = { } |
{} or a block, with no interior spaces |
x = [ one ] |
the elements on following lines |
@int with no payload |
@int 42 |
@null null |
@null |
@float 1.0 |
@decimal 1.0 |
@int "1" |
@int 1 |
x = {} y = 2 |
one entry per line |
| a lone CR | LF or CRLF |
- Nesting deeper than 128 collections is a resource-limit error. The writer applies the same
bound: a value tree that deep has no valid document, so
Riffle.writethrowsIllegalArgumentExceptioninstead of producing text the parser would reject. - Parsing and writing keep time and memory proportional to the document; there is no
document-size limit. Bound untrusted input yourself, with a size check before
parse(Path)or a boundedReader. - A decimal's normalized base-10 exponent must be in
[-2147483647, 2147483648]. A literal whose normalized form falls outside that range is aNUMBER_OUT_OF_RANGEparse error. - Canonical decimal output chooses plain notation when the decimal token is at most 256 characters and scientific notation otherwise. Very large coefficients with zero scale now use scientific form; their old plain spelling still parses but is no longer canonical.
import io.github.dhoard.riffle.*;
import java.math.BigDecimal;
import java.nio.file.Path;
import java.util.List;
import java.util.Map;
RiffleObject profile = Riffle.parse(Path.of("profile.riffle"));
String provider = profile.getString("provider");
RiffleObject capabilities = profile.getObject("capabilities");
int contextWindow = capabilities.getInt("contextWindow");
boolean tools = capabilities.getBoolean("tools");
BigDecimal temperature = profile.getObject("model").getDecimal("temperature");
List<String> reasoning = capabilities.getArray("reasoning").values().stream()
.map(RiffleValue::asString)
.toList();
int retries = profile.find("retries").map(RiffleValue::asInt).orElse(3);
boolean pluginIsNull = profile.find("plugin").map(RiffleValue::isNull).orElse(false);
String canonical = Riffle.write(profile);RiffleValueis sealed:RiffleObject,RiffleArray(togetherRiffleContainer),RiffleString,RiffleInt,RiffleLong,RiffleDecimal,RiffleBoolean,RiffleNull.- Values are immutable and thread-safe. Maps keep insertion order; arrays keep element order.
- Equality includes the kind and ignores source locations; map order does not affect equality, array order does. Decimals compare by numeric value, so
1.0equals1.00.
Riffle.parseaccepts aString, aReader(which it does not close), or a UTF-8Path, and returns the root map.Riffle.writereturns the canonical document; parsing it yields an equal value. An array cannot be a root, so writing one is anIllegalArgumentException.- Canonical output is UTF-8 without a BOM, uses LF and four-space indentation, and drops comments, blank lines, and typed-array annotations. It is byte-exact; see the conformance suite.
get(key)for a required key,find(key)for an optional one,entries()for the map.get(index),size()andvalues()for arrays.RiffleObjectandRiffleArrayalso provide strict typed getters:getString,getInt,getLong,getDecimal,getBoolean,getObject, andgetArray. They are shorthand forget(key).asX()orget(index).asX()and have the same errors, paths, and source locations.
RiffleArray ports = root.getArray("ports");
int firstPort = ports.getInt(0); // no widening or narrowing
String name = root.getString("name"); // no parsing of strings as numbers
RiffleObject nested = root.getObject("nested");A missing key throws RiffleAccessException; find(key) is the optional-key API. A present @null is returned by get(key) as RiffleNull, never Java null, and strict typed getters reject it with a wrong-kind error. find("x") being empty and get("x").isNull() being true are different states.
RiffleJavaValues is an explicit bridge to ordinary Java collections and scalars. It does not change the strict RiffleValue accessors.
Map<String, Object> nativeProfile = RiffleJavaValues.toJava(profile);
String nativeProvider = (String) nativeProfile.get("provider");
boolean pluginPresent = nativeProfile.containsKey("plugin");
boolean pluginIsJavaNull = pluginPresent && nativeProfile.get("plugin") == null;
List<?> nativeReasoning = (List<?>) RiffleJavaValues.toJava(capabilities.getArray("reasoning"));
RiffleObject restored = RiffleJavaValues.fromJava(nativeProfile);| Riffle | Java |
|---|---|
| string | String |
| int | Integer |
| long | Long |
| decimal | BigDecimal |
| boolean | Boolean |
| null | Java null |
| map | unmodifiable, insertion-ordered Map<String, Object> |
| array | unmodifiable List<Object> |
Results are deep defensive copies. Unlike Map.copyOf and List.copyOf, they accept null values, so present-null remains distinguishable from a missing key. fromJava accepts only the types above, requires String map keys, rejects cycles and unsupported numeric subtypes, and enforces the same nesting bound. A round trip preserves the eight kinds and order, but source locations and paths are lost and cannot be recovered.
Value-level accessors are strict: each accepts exactly one kind, and no coercion happens.
| Conversion | Accepts |
|---|---|
asString() |
a string |
asInt() |
an int |
asLong() |
a long |
asDecimal() |
a decimal |
asBoolean() |
a boolean |
asObject(), asArray() |
a map or an array |
Each has a predicate that never throws and is true exactly when the conversion succeeds: isString(), isInt(), isLong(), isDecimal(), isBoolean(), isObject(), isArray(), isNull().
RiffleParseExceptionreports invalid documents. It carries a stableRiffleErrorcategory, a location, and a message of the formlocation: reason.RiffleAccessExceptionreports a missing key or a value of the wrong kind, with the key path and source location.- Messages never include scalar values, so secrets in configuration do not reach logs.
- Construction errors are
IllegalArgumentExceptions; I/O failures areIOExceptions. Malformed UTF-8 in a file is a parse error with categoryINVALID_UTF8.
RiffleObject.of(Map), RiffleArray.of(List), RiffleString.of(String), RiffleInt.of(int), RiffleLong.of(long), RiffleDecimal.of(BigDecimal), RiffleBoolean.of(boolean), RiffleNull.INSTANCE.
Conversions for durations, URIs, colors or enums belong in the application as functions over asString(). Throw new RiffleAccessException(value, reason) to report them in the same form as Riffle's own errors.
conformance/ contains language-neutral fixtures, a JSON manifest with typed expectations and expected canonical bytes, and a Java runner that discovers cases at runtime. It is the contract for future non-Java implementations; it does not imply that Go, Rust, or Python implementations already exist.
./mvnw test -Dtest=ConformanceTesteditors/sublime/ is a Sublime Text package: a
sublime-syntax definition for .riffle files that follows this specification, together
with a syntax test file. It is tooling, not part of the language definition.
These mappings are illustrative only. The language definition is in LANGUAGE_SPEC.md; host-language types are not normative, and a host with one integer type must still preserve the distinct int and long Riffle kinds.
| Riffle kind | Java (reference) | Go (illustrative) | Rust (illustrative) | Python (illustrative) |
|---|---|---|---|---|
| string | String |
string |
String |
str |
| int | int |
int32 |
i32 |
int with range check |
| long | long |
int64 |
i64 |
int with range check |
| decimal | BigDecimal |
decimal package | decimal crate | decimal.Decimal |
| boolean | boolean |
bool |
bool |
bool |
| null | RiffleNull |
typed nil sentinel | Option sentinel |
None in a typed wrapper |
| map | ordered Map |
ordered pair slice | IndexMap / vec |
insertion-ordered dict |
| array | ordered List |
[]T |
Vec<T> |
list |
Requires JDK 17+ and Maven 3.9+.
./mvnw clean verifyFormatting is enforced during verify by Spotless using Palantir Java Format; run
./mvnw spotless:apply after editing Java sources. The release profile adds signing and
publishing. Main sources have no runtime dependencies. Tests use JUnit 6 and AssertJ.
- Human-authored application configuration only; not a data interchange or protocol format.
- No implicit typing, no variable expansion, include, merge, substitution or computation.
- Comments, blank lines, original quoting, and typed-array annotations are not preserved by the canonical writer. Typed arrays are authoring sugar: their elements are written with explicit
@typemarkers. - Native conversions drop source metadata and do not provide POJO/record binding, reflection mapping, schemas, or application object construction.
Riffle.write(Path, …)truncates the file and then writes it, so an interrupted write can leave a partial document; write a temporary file and move it if that matters.- Version 0.1.0 is unreleased; the language and API may still change.
MIT, see LICENSE.