Module com.darkcollective.relix.lang.ast

Package com.darkcollective.relix.lang.ast

Class ScriptBuilders

java.lang.Object

com.darkcollective.relix.ast.AstBuilders

com.darkcollective.relix.lang.ast.ScriptBuilders

public abstract class ScriptBuilders
extends AstBuilders

The Script authoring surface — the statement-level half of the AST contract, for tests and embedders that assemble a whole script without the .relix grammar.

SemanticAnalyzer.analyze(Script, rootPath) is the engine's front door, so a caller who can build a Script needs no parser at all. These factories are how that is done readably, and ScriptBuilderCoverageTest fails the build if a new Statement or SourceConfig kind arrives without one.

It extends AstBuilders, so one extends ScriptBuilders — or a static import of this class — reaches the relational factories too:

Script script = script(
        source("Orders", csvSource("orders.csv", column("id", ScalarType.NUMBER))),
        assign("Open", select(cmp(attr("status"), ComparisonOperator.EQUAL, str("OPEN")),
                              rel("Orders"))),
        query("Open"));

The same rule as AstBuilders applies: a factory takes the record's own components in the record's own order, minus SourceLocation, which defaults to SourceLocation.UNKNOWN. Statements that carry an exported flag get a two-form treatment — the short factory is the un-exported common case, and an explicit overload takes the flag.

Constructor Summary

Constructors

Constructor	Description
ScriptBuilders()

Method Summary

Modifier and Type	Method	Description
static ArrayType	array(Type element)	An array type over element.
static AssignmentStatement	assign(boolean exported, String name, RelNode expression)	A view binding, exported or not.
static AssignmentStatement	assign(boolean exported, String name, InlineTable table)	An inline-table binding, exported or not.
static AssignmentStatement	assign(String name, RelNode expression)	Name := { <expression> }; — a view binding.
static AssignmentStatement	assign(String name, InlineTable table)	Name := [ … ]; — an inline-table binding.
static ColumnSpec	column(String name, ScalarType type)	An output column of a source schema.
static ColumnSpec	column(String name, ScalarType type, String path)	An output column bound to an extraction path.
static ColumnSpec	column(String name, Type type)	An output column of a nested type — a struct, or an array of anything.
static ConnectionDeclaration	connection(boolean exported, String name, String connectorType, Map<String,String> properties)	connection, exported or not.
static ConnectionDeclaration	connection(String name, DatabaseConnectionConfig config)	connection <name> from jdbc { url: … } — the JDBC shorthand the record itself offers, exported.
static ConnectionDeclaration	connection(String name, String connectorType, Map<String,String> properties)	connection <name> from <type> { … }.
static ConnectionTableSourceConfig	connectionTable(String connection, String table, ColumnSpec... columns)	from <connection>.<table>.
static ConnectionTableSourceConfig	connectionTable(String connection, String table, List<ColumnSpec> columns, List<ColumnReference> references)	from <connection>.<table> { references: { … } }.
static CsvFileSourceConfig	csvSource(String path, boolean hasHeader, List<ColumnSpec> columns)	from csv { … }, header row optional.
static CsvFileSourceConfig	csvSource(String path, boolean hasHeader, List<ColumnSpec> columns, List<ColumnReference> references)	from csv { …, references: { … } }.
static CsvFileSourceConfig	csvSource(String path, ColumnSpec... columns)	from csv { … } with a header row.
static CsvInlineTable	csvTable(List<String> headers, List<List<String>> rows)	A CSV inline table.
static DatabaseSourceConfig	databaseSource(String url, String table, ColumnSpec... columns)	from database { url: …, table: … }.
static DatabaseSourceConfig	databaseSource(String url, String table, List<ColumnSpec> columns, List<ColumnReference> references)	from database { …, references: { … } }.
static DefStatement	def(boolean exported, String name, List<ParameterDefinition> parameters, ScalarType returnType, Operand body)	A scalar def, exported or not.
static DefStatement	def(String name, List<ParameterDefinition> parameters, ScalarType returnType, Operand body)	def <name>(…): <type> = <operand> — a scalar function.
static DefRelationStatement	defRelation(boolean exported, String name, List<ParameterDefinition> parameters, RelNode body)	A relation def, exported or not.
static DefRelationStatement	defRelation(String name, List<ParameterDefinition> parameters, RelNode body)	def relation <name>(…) = { … } — a table-valued function.
static EndpointSpec	endpoint(String relationRef, List<String> columns)	An endpoint of a relate, with the default [0..*] bounds.
static EndpointSpec	endpoint(String relationRef, List<String> columns, long min, OptionalLong max)	An endpoint with explicit cardinality bounds.
static EnvStatement	env()	env with the default file and no active environment.
static EnvStatement	env(Optional<String> filePath, Optional<String> activeEnv)	env "<file>" [as <name>].
static StructType.Field	field(String name, Type type)	A struct field, for building a nested column type.
static GeneratorSourceConfig	generatorSource(String generatorName, Map<String,String> args)	from generator <name> { … }.
static HttpSourceConfig	httpSource(String url, ColumnSpec... columns)	from http { … } — a GET with no headers or extraction.
static HttpSourceConfig	httpSource(String url, HttpMethod method, Map<String,String> headers, Optional<ExtractSpec> extract, Optional<PaginateSpec> paginate, List<ColumnSpec> columns, Optional<String> body, Optional<AuthSpec> auth)	from http { … }, fully specified.
static ImportStatement	importAll(String sourcePath)	import "<path>" — a bulk import of everything the script declares.
static ImportStatement	importNames(ImportKind kind, List<String> names, String sourcePath)	A named import, e.g.
static JsonFileSourceConfig	jsonSource(String path)	from json { … } reading the whole document.
static JsonFileSourceConfig	jsonSource(String path, Optional<String> records)	from json { … } reading a records path.
static JsonFileSourceConfig	jsonSource(String path, Optional<String> records, List<ColumnReference> references)	from json { …, references: { … } }.
static MarkdownInlineTable	markdownTable(List<String> headers, List<List<String>> rows)	A markdown inline table — the pipe-delimited literal form.
static ParameterDefinition	param(String name, ScalarType type)	A function parameter, name: type.
static QueryStatement	query(RelNode expression)	query { <expression> }; — a query over an anonymous expression.
static QueryStatement	query(String name)	query { <Name> }; — a query naming an already-bound relation.
static ColumnReference	reference(String sourceColumn, String targetRelation, String targetColumn)	The single-column form of reference(List, String, List).
static ColumnReference	reference(List<String> sourceColumns, String targetRelation, List<String> targetColumns)	A foreign-key edge for a source's references: block, cols -> Target.cols — one edge of the schema graph a script declares.
static RelateStatement	relate(String name, EndpointSpec source, EndpointSpec target)	relate <name> … — one directed relationship edge of the schema graph.
static RelateStatement	relate(String name, Optional<String> inverseName, boolean symmetric, EndpointSpec source, EndpointSpec target)	relate, with an inverse name and/or symmetry.
static ParameterDefinition	relationParam(String name, ColumnDefinition... columns)	A relation parameter — name: RELATION(columns…) — for a table-valued def.
static Script	script(Statement... statements)	A script in the default namespace.
static Script	script(String namespace, Statement... statements)	A script declaring namespace <name>;.
static SourceDeclaration	source(boolean exported, String name, SourceConfig config)	source, exported or not.
static SourceDeclaration	source(String name, SourceConfig config)	source <name> from <config>.
static StructType	struct(StructType.Field... fields)	A struct type over the given fields.

Methods inherited from class com.darkcollective.relix.ast.AstBuilders

agg, agg, aggOf, allocation, and, antiJoin, argAgg, argAgg, arith, arrayOf, asc, asOfJoin, asOfJoin, attr, attrs, bool, closure, closure, closure, closure, cluster, cmp, cols, composition, condition, constraint, cover, cover, date, desc, difference, distinct, division, downsample, downsample, downsample, downsample, duration, elementOf, emptyOf, emptyRel, field, fixpoint, fullJoin, func, groupBy, groupByKeys, intersection, intervalJoin, iterate, join, key, key, lateral, leftJoin, like, limit, limit, naturalJoin, not, notElementOf, notLike, nullPred, num, optimize, optimize, or, outerUnion, pairwiseUniversal, path, path, path, pivot, produceBound, product, project, projected, projected, recRef, rel, rel, rename, rename, renamePair, reservoirSample, reservoirSample, rightJoin, rounds, sample, sample, select, semiJoin, sessionize, sessionize, set, solve, sort, sortKey, str, structOf, symmetricDifference, time, timestamp, topK, topK, trace, trace, trace, tree, tree, tvf, unary, union, unionAll, unitRel, universal, unnest, unnest, unnest, unpivot, untilConverged, untilStable, why, window

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

ScriptBuilders

public ScriptBuilders()

Method Details

script

public static Script script(Statement... statements)

A script in the default namespace.

script

public static Script script(String namespace,
 Statement... statements)

A script declaring namespace <name>;.

env

public static EnvStatement env()

env with the default file and no active environment.

env

public static EnvStatement env(Optional<String> filePath,
 Optional<String> activeEnv)

env "<file>" [as <name>].

importAll

public static ImportStatement importAll(String sourcePath)

import "<path>" — a bulk import of everything the script declares.

importNames

public static ImportStatement importNames(ImportKind kind,
 List<String> names,
 String sourcePath)

A named import, e.g. import relation Orders from "orders.relix".

connection

public static ConnectionDeclaration connection(String name,
 String connectorType,
 Map<String,String> properties)

connection <name> from <type> { … }.

connection

public static ConnectionDeclaration connection(String name,
 DatabaseConnectionConfig config)

connection <name> from jdbc { url: … } — the JDBC shorthand the record itself offers, exported.

connection

public static ConnectionDeclaration connection(boolean exported,
 String name,
 String connectorType,
 Map<String,String> properties)

connection, exported or not.

source

public static SourceDeclaration source(String name,
 SourceConfig config)

source <name> from <config>.

source

public static SourceDeclaration source(boolean exported,
 String name,
 SourceConfig config)

source, exported or not.

relate

public static RelateStatement relate(String name,
 EndpointSpec source,
 EndpointSpec target)

relate <name> … — one directed relationship edge of the schema graph.

relate

public static RelateStatement relate(String name,
 Optional<String> inverseName,
 boolean symmetric,
 EndpointSpec source,
 EndpointSpec target)

relate, with an inverse name and/or symmetry.

endpoint

public static EndpointSpec endpoint(String relationRef,
 List<String> columns)

An endpoint of a relate, with the default [0..*] bounds.

endpoint

public static EndpointSpec endpoint(String relationRef,
 List<String> columns,
 long min,
 OptionalLong max)

An endpoint with explicit cardinality bounds.

assign

public static AssignmentStatement assign(String name,
 RelNode expression)

Name := { <expression> }; — a view binding.

assign

public static AssignmentStatement assign(boolean exported,
 String name,
 RelNode expression)

A view binding, exported or not.

assign

public static AssignmentStatement assign(String name,
 InlineTable table)

Name := [ … ]; — an inline-table binding.

assign

public static AssignmentStatement assign(boolean exported,
 String name,
 InlineTable table)

An inline-table binding, exported or not.

def

public static DefStatement def(String name,
 List<ParameterDefinition> parameters,
 ScalarType returnType,
 Operand body)

def <name>(…): <type> = <operand> — a scalar function.

def

public static DefStatement def(boolean exported,
 String name,
 List<ParameterDefinition> parameters,
 ScalarType returnType,
 Operand body)

A scalar def, exported or not.

defRelation

public static DefRelationStatement defRelation(String name,
 List<ParameterDefinition> parameters,
 RelNode body)

def relation <name>(…) = { … } — a table-valued function.

defRelation

public static DefRelationStatement defRelation(boolean exported,
 String name,
 List<ParameterDefinition> parameters,
 RelNode body)

A relation def, exported or not.

query

public static QueryStatement query(String name)

query { <Name> }; — a query naming an already-bound relation.

query

public static QueryStatement query(RelNode expression)

query { <expression> }; — a query over an anonymous expression.

param

public static ParameterDefinition param(String name,
 ScalarType type)

A function parameter, name: type.

relationParam

public static ParameterDefinition relationParam(String name,
 ColumnDefinition... columns)

A relation parameter — name: RELATION(columns…) — for a table-valued def.

column

public static ColumnSpec column(String name,
 ScalarType type)

An output column of a source schema.

column

public static ColumnSpec column(String name,
 Type type)

An output column of a nested type — a struct, or an array of anything.

Separate from the ScalarType overload rather than replacing it, so the common case still reads column("id", ScalarType.NUMBER) without a cast.

field

public static StructType.Field field(String name,
 Type type)

A struct field, for building a nested column type.

struct

public static StructType struct(StructType.Field... fields)

A struct type over the given fields.

array

public static ArrayType array(Type element)

An array type over element.

column

public static ColumnSpec column(String name,
 ScalarType type,
 String path)

An output column bound to an extraction path.

markdownTable

public static MarkdownInlineTable markdownTable(List<String> headers,
 List<List<String>> rows)

A markdown inline table — the pipe-delimited literal form.

csvTable

public static CsvInlineTable csvTable(List<String> headers,
 List<List<String>> rows)

A CSV inline table.

csvSource

public static CsvFileSourceConfig csvSource(String path,
 ColumnSpec... columns)

from csv { … } with a header row.

csvSource

public static CsvFileSourceConfig csvSource(String path,
 boolean hasHeader,
 List<ColumnSpec> columns)

from csv { … }, header row optional.

jsonSource

public static JsonFileSourceConfig jsonSource(String path)

from json { … } reading the whole document.

jsonSource

public static JsonFileSourceConfig jsonSource(String path,
 Optional<String> records)

from json { … } reading a records path.

databaseSource

public static DatabaseSourceConfig databaseSource(String url,
 String table,
 ColumnSpec... columns)

from database { url: …, table: … }.

connectionTable

public static ConnectionTableSourceConfig connectionTable(String connection,
 String table,
 ColumnSpec... columns)

from <connection>.<table>.

reference

public static ColumnReference reference(List<String> sourceColumns,
 String targetRelation,
 List<String> targetColumns)

A foreign-key edge for a source's references: block, cols -> Target.cols — one edge of the schema graph a script declares.

Parameters:

sourceColumns - this source's columns; never empty

targetRelation - the relation the edge points at

targetColumns - the target's columns, paired with sourceColumns

Returns:

the reference

reference

public static ColumnReference reference(String sourceColumn,
 String targetRelation,
 String targetColumn)

The single-column form of reference(List, String, List).

csvSource

public static CsvFileSourceConfig csvSource(String path,
 boolean hasHeader,
 List<ColumnSpec> columns,
 List<ColumnReference> references)

from csv { …, references: { … } }.

The three configurations that can carry a references: block each take one, so the schema graph a script declares is expressible from here. Without them the component existed on the record and on no factory, which is how it came to be dropped by the printer with a full round-trip corpus in place.

databaseSource

public static DatabaseSourceConfig databaseSource(String url,
 String table,
 List<ColumnSpec> columns,
 List<ColumnReference> references)

from database { …, references: { … } }.

connectionTable

public static ConnectionTableSourceConfig connectionTable(String connection,
 String table,
 List<ColumnSpec> columns,
 List<ColumnReference> references)

from <connection>.<table> { references: { … } }.

jsonSource

public static JsonFileSourceConfig jsonSource(String path,
 Optional<String> records,
 List<ColumnReference> references)

from json { …, references: { … } }.

httpSource

public static HttpSourceConfig httpSource(String url,
 ColumnSpec... columns)

from http { … } — a GET with no headers or extraction.

httpSource

public static HttpSourceConfig httpSource(String url,
 HttpMethod method,
 Map<String,String> headers,
 Optional<ExtractSpec> extract,
 Optional<PaginateSpec> paginate,
 List<ColumnSpec> columns,
 Optional<String> body,
 Optional<AuthSpec> auth)

from http { … }, fully specified.

generatorSource

public static GeneratorSourceConfig generatorSource(String generatorName,
 Map<String,String> args)

from generator <name> { … }.