DataDSLModule

PackageReified.Data

`DataDSL`

Reified.DataDSL provides short names and the => and ?=> operators for data construction and editing. Every DSL name maps to an explicit Reified.Data or DataEdit function; each builds the same value the qualified name builds.

Literal and edit mappings

DataDSL	Explicit API	Result
`name => value`	`Data.assoc name value`	`DataField`
`name ?=> option`	`Data.optionalAssoc name option`	`DataField`
`nil`	`Data.Null`	`Data`
`num token`	`Data.number token`	`Data`
`data fields`	`Data.data fields`	`Data`
`fields value`	`Data.fields value`	`DataField list`
`set path value`	`DataEdit.set path value`	`DataEdit`
`replace path value`	`DataEdit.replace path value`	`DataEdit`
`remove path`	`DataEdit.remove path`	`DataEdit`
`append path value`	`DataEdit.append path value`	`DataEdit`
`prepend path value`	`DataEdit.prepend path value`	`DataEdit`
`insert path index value`	`DataEdit.insert path index value`	`DataEdit`
`rename path name`	`DataEdit.rename path name`	`DataEdit`
`update path function`	`DataEdit.update path function`	`DataEdit`
n/a	`Data.patch edits input`	changed `Data`

set makes the final path contain the value, adding a missing final object field when necessary. replace requires the target to exist, so a misspelled or unexpectedly absent path fails.

Matching and case-generation names

The matching and case-generation names also live in Reified.DataDSL. Without opening it, qualify them as Reified.DataDSL.at, Reified.DataDSL.containing, Reified.DataDSL.variant, and so on.

Area	Names
Paths	`at`, `absent`
Object patterns	`exactly`, `containing`
List patterns	`containingItems`, `inOrder`, `allItems`, `someItem`
General patterns	`any`, `anyText`, `anyNumber`, `oneOf`, `satisfying`
Matching	`matching`
Cases	`variant`, `variants`, `dimension`, `matrix`

Data.tryMatch is always qualified because it is not part of the DSL.

See DataDSL for a full example with and without the DSL open.

Summary

Name	Signature	Synopsis
Operations
(=>)	name => value	Associates a field name with an exact value or recursive data pattern.
(?=>)	name ?=> value	Associates a field name with an optional exact value, omitting None.
nil	nil	An explicit structured null used by literals and edits.
num	num	Constructs an exact number from a validated portable JSON number token.
data	data	Builds an object from ordered field instructions.
fields	fields	Returns exact field instructions for spreading an existing object literal.
set	set path value	Replaces a value or adds a missing final object field.
replace	replace path value	Replaces an existing value.
remove	remove	Removes an existing field or list item.
append	append path value	Appends an item to an existing list.
prepend	prepend path value	Prepends an item to an existing list.
insert	insert path index value	Inserts an item at a valid list insertion index.
rename	rename	Renames an existing object field without moving it.
update	update	Applies an ordinary function to an existing value.
variant	variant name edits	Declares one named variation from a baseline.
variants	variants variations baseline	Materializes named variations from one baseline.
dimension	dimension name variations	Declares one named dimension in a Cartesian matrix.
matrix	matrix dimensions baseline	Materializes a deterministic Cartesian matrix, limited to 256 cases.
exactly	exactly value	Creates an exact recursive pattern.
containing	containing fields	Creates a partial object pattern from required fields.
containingItems	containingItems values	Matches expected items as an unordered consumed subset.
inOrder	inOrder values	Matches expected items as an ordered subsequence.
allItems	allItems value	Requires every actual list item to satisfy a pattern.
someItem	someItem value	Requires at least one actual list item to satisfy a pattern.
any	any	Matches any present value.
anyText	anyText	Matches any text value.
anyNumber	anyNumber	Matches any number token.
oneOf	oneOf patterns	Matches when one supplied alternative matches.
satisfying	satisfying description predicate	Matches an ordinary predicate and uses its description in diagnostics.
at	at path expected	Requires a path to contain an exact value or recursive pattern.
absent	absent path	Requires a path to be absent.
matching	matching expectations actual	Checks expectations or raises DataMatchException.

Operations

kind:member

(=>)

name => value

Member

Associates a field name with an exact value or recursive data pattern.

Parameters

Name	Type	Description
name	string
value	^value

Returns

DataField

kind:member

(?=>)

name ?=> value

Member

Associates a field name with an optional exact value, omitting None.

Parameters

Name	Type	Description
name	string
value	^value option

Returns

DataField

kind:member

nil

Member

An explicit structured null used by literals and edits.

Returns

Data

kind:member

num

Member

Constructs an exact number from a validated portable JSON number token.

Returns

string -> Data

kind:member

data

Member

Builds an object from ordered field instructions.

Returns

DataField list -> Data

Verification Examples

data [ "name" => "Ada"; "active" => true ]
 // Data.Object [ "name", Data.Text "Ada"; "active", Data.Bool true ]

kind:member

fields

Member

Returns exact field instructions for spreading an existing object literal.

Returns

Data -> DataField list

kind:member

set

set path value

Member

Replaces a value or adds a missing final object field.

Parameters

Name	Type	Description
path	string
value	^a

Returns

DataEdit

kind:member

replace

replace path value

Member

Replaces an existing value.

Parameters

Name	Type	Description
path	string
value	^a

Returns

DataEdit

kind:member

remove

Member

Removes an existing field or list item.

Returns

string -> DataEdit

kind:member

append

append path value

Member

Appends an item to an existing list.

Parameters

Name	Type	Description
path	string
value	^a

Returns

DataEdit

kind:member

prepend

prepend path value

Member

Prepends an item to an existing list.

Parameters

Name	Type	Description
path	string
value	^a

Returns

DataEdit

kind:member

insert

insert path index value

Member

Inserts an item at a valid list insertion index.

Parameters

Name	Type	Description
path	string
index	int
value	^a

Returns

DataEdit

kind:member

rename

Member

Renames an existing object field without moving it.

Returns

string -> string -> DataEdit

kind:member

update

Member

Applies an ordinary function to an existing value.

Returns

string -> (Data -> Data) -> DataEdit

kind:member

variant

variant name edits

Member

Declares one named variation from a baseline.

Parameters

Name	Type	Description
name	string
edits	DataEdit list

Returns

DataVariation

kind:member

variants

variants variations baseline

Member

Materializes named variations from one baseline.

Parameters

Name	Type	Description
variations	DataVariation list
baseline	Data

Returns

DataCase list

Verification Examples

variants [ variant "inactive" [ replace "active" false ] ] (data [ "active" => true ])
 // [ { Name = "inactive"; Value = data [ "active" => false ] } ]

kind:member

dimension

dimension name variations

Member

Declares one named dimension in a Cartesian matrix.

Parameters

Name	Type	Description
name	string
variations	DataVariation list

Returns

DataDimension

kind:member

matrix

matrix dimensions baseline

Member

Materializes a deterministic Cartesian matrix, limited to 256 cases.

Parameters

Name	Type	Description
dimensions	DataDimension list
baseline	Data

Returns

DataCase list

Verification Examples

open Reified.DataDSL
 let baseline = data [ "active" => true ]
 matrix [ dimension "status" [ variant "active" []; variant "inactive" [ replace "active" false ] ] ] baseline
 // cases named "status: active" and "status: inactive"

kind:member

exactly

exactly value

Member

Creates an exact recursive pattern.

Parameters

Name	Type	Description
value	^a

Returns

DataPattern

kind:member

containing

containing fields

Member

Creates a partial object pattern from required fields.

Parameters

Name	Type	Description
fields	DataField list

Returns

DataPattern

Verification Examples

Data.tryMatch [ at "" (containing [ "id" => 42 ]) ] (data [ "id" => 42; "extra" => true ])
 // Ok ()

kind:member

containingItems

containingItems values

Member

Matches expected items as an unordered consumed subset.

Parameters

Name	Type	Description
values	^a list

Returns

DataPattern

Verification Examples

open Reified.DataDSL
 let actual = data [ "items" => [ "Ada"; "Grace"; "Mallory" ] ]
 Data.tryMatch [ at "items" (containingItems [ "Ada"; "Grace" ]) ] actual
 // Ok () when both values occur, in either order

kind:member

inOrder

inOrder values

Member

Matches expected items as an ordered subsequence.

Parameters

Name	Type	Description
values	^a list

Returns

DataPattern

kind:member

allItems

allItems value

Member

Requires every actual list item to satisfy a pattern.

Parameters

Name	Type	Description
value	^a

Returns

DataPattern

kind:member

someItem

someItem value

Member

Requires at least one actual list item to satisfy a pattern.

Parameters

Name	Type	Description
value	^a

Returns

DataPattern

kind:member

any

Member

Matches any present value.

Returns

DataPattern

kind:member

anyText

Member

Matches any text value.

Returns

DataPattern

kind:member

anyNumber

Member

Matches any number token.

Returns

DataPattern

kind:member

oneOf

oneOf patterns

Member

Matches when one supplied alternative matches.

Parameters

Name	Type	Description
patterns	DataPattern list

Returns

DataPattern

kind:member

satisfying

satisfying description predicate

Member

Matches an ordinary predicate and uses its description in diagnostics.

Parameters

Name	Type	Description
description	string
predicate	Data -> bool

Returns

DataPattern

kind:member

at

at path expected

Member

Requires a path to contain an exact value or recursive pattern.

Parameters

Name	Type	Description
path	string
expected	^a

Returns

DataExpectation

kind:member

absent

absent path

Member

Requires a path to be absent.

Parameters

Name	Type	Description
path	string

Returns

DataExpectation

kind:member

matching

matching expectations actual

Member

Checks expectations or raises DataMatchException.

Parameters

Name	Type	Description
expectations	DataExpectation list
actual	Data

Returns

unit

Verification Examples

open Reified.DataDSL
 let actual = data [ "user" => data [ "name" => "Ada" ] ]
 matching [ at "user.name" "Ada"; absent "error" ] actual
 // returns unit when both expectations hold; otherwise raises DataMatchException