The words the language gives meaning to, and what each one may be given. More...

Classes
struct	EntryPort
	Every pipeline stage, in the order they read best in a listing. More...

struct	WordDoc
	What one word of the language does, as reference an editor can show. More...

Enumerations
enum class	StageArgument { kNone , kNumber , kExpression , kString , kOptionalString , kOptionalExpression , kSortKey , kFold , kDuration , kStream , kLog , kLogFormat }
	What a stage takes after its name. More...

enum class	WordRole { kStage , kBuiltin , kStatement , kDeclaration , kClause , kModifier , kSource , kPortModifier , kFieldModifier , kType , kConstant , kOperatorWord , kStatusCode , kLogLevel , kStatusField , kDurationUnit , kSymbol }
	Which table a word is documented in. More...

Functions
std::string	Canonical (std::string_view word)
	The lower-case form of a uniformly-cased word, or the word unchanged.

bool	IsShouted (std::string_view word)
	Whether the word, canonicalised, is written entirely in upper case.

absl::Span< const EntryPort >	EntryPorts ()
	The ports the entry flow has without declaring them, in declaration order.

absl::Span< const std::string_view >	Stages ()

std::optional< StageArgument >	StageTakes (std::string_view canonical_name)
	What a stage takes, or `nullopt` if the name is not a stage.

std::string_view	StageArgumentName (StageArgument argument)
	The spelling of a stage argument kind in the output formats.

const WordDoc *absl_nullable	StageDocumentation (std::string_view canonical_name)
	What a stage does, or `nullptr` where the name is not a stage.

const WordDoc *absl_nullable	BuiltinDocumentation (std::string_view canonical_name)
	What a built-in function does, or `nullptr` where the name is not one.

const WordDoc *absl_nullable	Documentation (WordRole role, std::string_view canonical_name)
	What one word of `role` does, or `nullptr` where that table has no entry.

absl::Span< const std::string_view >	OrderedSymbols ()
	Every punctuation mark and non-word operator the language gives meaning to, in the order a listing reads them.

const WordDoc *absl_nullable	AnyDocumentation (std::string_view canonical_name)
	What one word does under whichever role documents it, or `nullptr`.

absl::Span< const WordRole >	WordRoles ()
	Every role, for something walking all of them.

std::string_view	WordRoleName (WordRole role)
	The name a role travels under in `flow.vocabulary/v1`: `port_modifier`.

std::vector< std::string_view >	WordsOf (WordRole role)
	The words `role` documents, in the order a listing reads them.

const absl::flat_hash_set< std::string_view > &	BareStages ()
	The two stages that may be written without their leading `\|`.

const absl::flat_hash_set< std::string_view > &	ReducingStages ()
	The stages that read a whole stream and yield exactly one value.

const absl::flat_hash_set< std::string_view > &	PositionalStages ()
	The stages that choose which values of a stream to keep, or group them, rather than reshaping each one.

const absl::flat_hash_set< std::string_view > &	ParallelStages ()
	The stages a value may pass through several at a time.

const absl::flat_hash_set< std::string_view > &	Builtins ()
	The language's fixed function set. No user code, ever: a flow stays data.

absl::Span< const std::string_view >	OrderedBuiltins ()
	The fixed function set, in the order a listing reads it.

const absl::flat_hash_set< std::string_view > &	TypeNames ()
	The built-in port type names.

absl::Span< const std::string_view >	OrderedTypeNames ()
	The built-in port type names, in the order a listing reads them.

absl::Span< const int >	TypeParameters (std::string_view canonical_name)
	How many type parameters a built-in type may be given.

const absl::flat_hash_set< std::string_view > &	StatementWords ()
	Words that open a statement, and so are not read as a name there.

absl::Span< const std::string_view >	OrderedStatements ()
	The same, in the order they read: what a statement may begin with, most common first.

const absl::flat_hash_set< std::string_view > &	ClauseWords ()
	Words that stand inside a statement without opening one.

absl::Span< const std::string_view >	OrderedClauseWords ()
	The same, in the order they read.

const absl::flat_hash_set< std::string_view > &	DeclarationWords ()
	Words that declare something inside a flow.

absl::Span< const std::string_view >	OrderedDeclarations ()
	The declarations in the order they are written in a flow.

const absl::flat_hash_set< std::string_view > &	ModifierWords ()
	Words that may follow a call's closing parenthesis.

absl::Span< const std::string_view >	OrderedModifiers ()
	The modifiers in the order they read after a call, `forward headers` being the one that is two words.

const absl::flat_hash_set< std::string_view > &	SourceWords ()
	Words that open a pipeline source rather than naming one: `status`, `zip`.

const absl::flat_hash_set< std::string_view > &	PortModifierWords ()
	What a port says about itself after its type: `stream`, `required`.

absl::Span< const std::string_view >	OrderedPortModifiers ()
	The same, in the order a port writes them.

const absl::flat_hash_set< std::string_view > &	FieldModifierWords ()
	What a `struct` field says about itself after its type.

absl::Span< const std::string_view >	OrderedFieldModifiers ()
	The same, in the order a field writes them, which is the order they are required to be written in.

absl::Span< const std::string_view >	LogLevels ()
	The severities a `log` or `logf` may name, quietest first.

bool	IsLogLevel (std::string_view word)
	Whether a word names a log level, in either case.

absl::Span< const std::string_view >	StatusCodes ()
	Abseil's canonical status codes, lower case, which is what `fail` names.

bool	IsStatusCode (std::string_view word)
	Whether a word names a canonical status code, in either case.

const absl::flat_hash_set< std::string_view > &	StatusFields ()
	The fields of a status record: what reading an outcome gives.

absl::Span< const std::string_view >	OrderedStatusFields ()
	The same, in the order a status record is written and read.

const absl::flat_hash_set< std::string_view > &	ConstantWords ()
	Literals that are words: `true`, `false`, `null`, `it`.

const absl::flat_hash_set< std::string_view > &	OperatorWords ()
	Operators that are words: `and`, `or`, `not`.

absl::Span< const std::string_view >	DurationUnits ()
	Duration suffixes a number may carry, shortest unit first.

std::optional< double >	DurationUnitSeconds (std::string_view unit)
	The seconds one of that unit is, or `nullopt` if it is not a unit.

Detailed Description

The words the language gives meaning to, and what each one may be given.

Every frontend reads this table; static grammar files are generated from it.

There are no reserved words: a word is only significant where the grammar puts it, which is why these are sets to be consulted at a position rather than a list of keywords the lexer could stamp on sight.

Enumeration Type Documentation

◆ StageArgument

enum class a11::flow::vocabulary::StageArgument

strong

What a stage takes after its name.

Enumerator
kNone	Nothing: `\| collect`, `\| count`.
kNumber	A whole number of values: `\| first 3`.
kExpression	An expression, with `it` bound to the value in hand: `\| where it.ok`.
kString	A string, required: `\| strformat "took {}"`.
kOptionalString	A string, optional: `\| join`, `\| join ", "`.
kOptionalExpression	An expression, optional, with `it` bound: `\| sum`, `\| sum it.price`.
kSortKey	An optional `by` key with `it` bound, and an optional `desc`: `\| sort`, `\| sort by it.score desc`.
kFold	A literal to start from, a name for what is carried, and the expression that folds one value into it: `\| fold 0 as total, total + it`.
kDuration	A length of time: `\| timeout 30s`, `\| pace 100ms`.
kStream	Another stream to read after this one: `\| then other`.
kLog	An optional level word and an optional expression, with `it` bound to the value in hand: `\| log`, `\| log warning it.error`.
kLogFormat	An optional level word, a format string, and the values to fill it with, with `it` bound to the value in hand: `\| logf "took %s" it.elapsed`.

◆ WordRole

enum class a11::flow::vocabulary::WordRole

strong

Which table a word is documented in.

One role per word set rather than one table keyed by the word, for the reason [StageDocumentation] and [BuiltinDocumentation] are already two functions: a word means different things in different positions, and a single table would have to pick one. default says what a header falls back to, what a field falls back to, and – as a function – what to use instead of an empty value; number is a type, a field of a status record, and a function. Which one a position means is the highlighter's judgement ([SemanticKind]), so whatever asks here has already been told.

A word genuinely in two sets – stream is a declaration word and a port modifier – has one [WordDoc] referenced from both tables rather than two texts that drift.

Enumerator
kStage	A pipeline stage: `\| first 3`. Same table as [StageDocumentation].
kBuiltin	A built-in function, where it is called. Same table as [BuiltinDocumentation].
kStatement	A word that opens a statement: `run`, `let`, `for`. [StatementWords].
kDeclaration	A word that declares something: `flow`, `in`, `header`. [DeclarationWords].
kClause	A word that continues a statement: `else`, `parallel`. [ClauseWords].
kModifier	A word that may follow a call's `)`: `via`, `timeout`. [ModifierWords].
kSource	A word that opens a pipeline source rather than naming one: `status`, `zip`. [SourceWords].
kPortModifier	What a port says about itself after its type. [PortModifierWords].
kFieldModifier	What a `struct` field says about itself after its type. [FieldModifierWords].
kType	A built-in port type name. [TypeNames].
kConstant	A literal that is a word: `true`, `it`. [ConstantWords].
kOperatorWord	An operator that is a word: `and`, `not`. [OperatorWords].
kStatusCode	One of Abseil's canonical status codes. [StatusCodes].
kLogLevel	The severity a `log` or `logf` may name. [LogLevels].
kStatusField	A field of a status record, read after a `.`. [StatusFields].
kDurationUnit	A duration suffix: `ms`, `h`. [DurationUnits].
kSymbol	Punctuation and the operators that are not words, keyed by the symbol itself: `\|`, `->`, `==`, `{`. [OrderedSymbols].

Function Documentation

◆ AnyDocumentation()

const WordDoc *absl_nullable a11::flow::vocabulary::AnyDocumentation ( std::string_view canonical_name )

What one word does under whichever role documents it, or nullptr.

For a caller that has a word and no position: a word set lists a word that another set documents, which is deliberate rather than a gap. stream is in [OrderedDeclarations] because a port declaration is where it is offered, and is documented as the port modifier it is. A hover knows the position and asks [Documentation] for the role that position means; a listing does not, and asks this.

◆ BareStages()

const absl::flat_hash_set< std::string_view > & a11::flow::vocabulary::BareStages ( )

The two stages that may be written without their leading |.

history then asked and hits where it.ok read as words joining two things rather than as a transformation applied to a stream. Both take an operand, which is what tells the stage from a port of the same name.

◆ BuiltinDocumentation()

const WordDoc *absl_nullable a11::flow::vocabulary::BuiltinDocumentation ( std::string_view canonical_name )

What a built-in function does, or nullptr where the name is not one.

A word that is both a stage and a function has an entry in each table, because they do different things: | text re-writes every value of a stream and text(x) re-writes one value. Which one a position means is the highlighter's judgement ([SemanticKind]), so whatever asks here has already been told.

◆ Builtins()

const absl::flat_hash_set< std::string_view > & a11::flow::vocabulary::Builtins ( )

The language's fixed function set. No user code, ever: a flow stays data.

◆ Canonical()

std::string a11::flow::vocabulary::Canonical ( std::string_view word )

The lower-case form of a uniformly-cased word, or the word unchanged.

FOR and for are the keyword; For is a name. The rule is the compiler's (a11.flow.lexer.canonical), and applying it in one place is what keeps every surface agreeing about it.

◆ ClauseWords()

const absl::flat_hash_set< std::string_view > & a11::flow::vocabulary::ClauseWords ( )

Words that stand inside a statement without opening one.

else continues an if, and parallel and max say how wide a loop runs. They are keywords where the grammar puts them and nowhere else, which is why they are not in [StatementWords]: a word there is one that stops being a name at the head of a statement, and none of these ever stands there. They are here so that everything colouring a flow colours them, which is what a list living only in the parser cost.

◆ ConstantWords()

const absl::flat_hash_set< std::string_view > & a11::flow::vocabulary::ConstantWords ( )

Literals that are words: true, false, null, it.

◆ DeclarationWords()

const absl::flat_hash_set< std::string_view > & a11::flow::vocabulary::DeclarationWords ( )

Words that declare something inside a flow.

◆ Documentation()

const WordDoc *absl_nullable a11::flow::vocabulary::Documentation	(	WordRole	role,
		std::string_view	canonical_name
	)

What one word of role does, or nullptr where that table has no entry.

The word is the canonical form for every role but [WordRole::kSymbol], where it is the punctuation as written.

◆ DurationUnits()

absl::Span< const std::string_view > a11::flow::vocabulary::DurationUnits ( )

Duration suffixes a number may carry, shortest unit first.

◆ DurationUnitSeconds()

std::optional< double > a11::flow::vocabulary::DurationUnitSeconds ( std::string_view unit )

The seconds one of that unit is, or nullopt if it is not a unit.

◆ EntryPorts()

absl::Span< const EntryPort > a11::flow::vocabulary::EntryPorts ( )

The ports the entry flow has without declaring them, in declaration order.

One table, read by the resolver that installs them, by completion so they are offered, and by anything documenting what a program may expect.

◆ FieldModifierWords()

const absl::flat_hash_set< std::string_view > & a11::flow::vocabulary::FieldModifierWords ( )

What a struct field says about itself after its type.

A superset of [PortModifierWords] in spirit rather than in fact – a field is never a stream, and a port never has a default – so the two tables are kept apart and each position consults its own.

◆ IsLogLevel()

bool a11::flow::vocabulary::IsLogLevel ( std::string_view word )

Whether a word names a log level, in either case.

◆ IsShouted()

bool a11::flow::vocabulary::IsShouted ( std::string_view word )

Whether the word, canonicalised, is written entirely in upper case.

◆ IsStatusCode()

bool a11::flow::vocabulary::IsStatusCode ( std::string_view word )

Whether a word names a canonical status code, in either case.

◆ LogLevels()

absl::Span< const std::string_view > a11::flow::vocabulary::LogLevels ( )

The severities a log or logf may name, quietest first.

The same five names A11's own log carries on a chunk, so what a flow writes and what a consumer filters on are one vocabulary rather than two.

◆ ModifierWords()

const absl::flat_hash_set< std::string_view > & a11::flow::vocabulary::ModifierWords ( )

Words that may follow a call's closing parenthesis.

◆ OperatorWords()

const absl::flat_hash_set< std::string_view > & a11::flow::vocabulary::OperatorWords ( )

Operators that are words: and, or, not.

◆ OrderedBuiltins()

absl::Span< const std::string_view > a11::flow::vocabulary::OrderedBuiltins ( )

The fixed function set, in the order a listing reads it.

◆ OrderedClauseWords()

absl::Span< const std::string_view > a11::flow::vocabulary::OrderedClauseWords ( )

The same, in the order they read.

◆ OrderedDeclarations()

absl::Span< const std::string_view > a11::flow::vocabulary::OrderedDeclarations ( )

The declarations in the order they are written in a flow.

◆ OrderedFieldModifiers()

absl::Span< const std::string_view > a11::flow::vocabulary::OrderedFieldModifiers ( )

The same, in the order a field writes them, which is the order they are required to be written in.

◆ OrderedModifiers()

absl::Span< const std::string_view > a11::flow::vocabulary::OrderedModifiers ( )

The modifiers in the order they read after a call, forward headers being the one that is two words.

[ModifierWords] is these split on the space, so a modifier added here is a modifier everywhere.

◆ OrderedPortModifiers()

absl::Span< const std::string_view > a11::flow::vocabulary::OrderedPortModifiers ( )

The same, in the order a port writes them.

◆ OrderedStatements()

absl::Span< const std::string_view > a11::flow::vocabulary::OrderedStatements ( )

The same, in the order they read: what a statement may begin with, most common first.

What something offering them at a caret writes down the list.

◆ OrderedStatusFields()

absl::Span< const std::string_view > a11::flow::vocabulary::OrderedStatusFields ( )

The same, in the order a status record is written and read.

◆ OrderedSymbols()

absl::Span< const std::string_view > a11::flow::vocabulary::OrderedSymbols ( )

Every punctuation mark and non-word operator the language gives meaning to, in the order a listing reads them.

Keeping these here lets editor help explain their semantics, not just their token kinds.

◆ OrderedTypeNames()

absl::Span< const std::string_view > a11::flow::vocabulary::OrderedTypeNames ( )

The built-in port type names, in the order a listing reads them.

◆ ParallelStages()

const absl::flat_hash_set< std::string_view > & a11::flow::vocabulary::ParallelStages ( )

The stages a value may pass through several at a time.

parallel n says how many, and only these accept it: a stage that gathers values or depends on their order has nothing to run concurrently, and one that reshapes each value on its own has everything. What comes after still sees the original order – see [syntax::Stage::ordered].

◆ PortModifierWords()

const absl::flat_hash_set< std::string_view > & a11::flow::vocabulary::PortModifierWords ( )

What a port says about itself after its type: stream, required.

◆ PositionalStages()

const absl::flat_hash_set< std::string_view > & a11::flow::vocabulary::PositionalStages ( )

The stages that choose which values of a stream to keep, or group them, rather than reshaping each one.

These say nothing about a single value.

◆ ReducingStages()

const absl::flat_hash_set< std::string_view > & a11::flow::vocabulary::ReducingStages ( )

The stages that read a whole stream and yield exactly one value.

Their arithmetic is what makes some sequences impossible rather than merely odd: after one of these there is a single value, so | drop 2 yields nothing and | count is 1 however long the stream was.

◆ SourceWords()

const absl::flat_hash_set< std::string_view > & a11::flow::vocabulary::SourceWords ( )

Words that open a pipeline source rather than naming one: status, zip.

◆ StageArgumentName()

std::string_view a11::flow::vocabulary::StageArgumentName ( StageArgument argument )

The spelling of a stage argument kind in the output formats.

◆ StageDocumentation()

const WordDoc *absl_nullable a11::flow::vocabulary::StageDocumentation ( std::string_view canonical_name )

What a stage does, or nullptr where the name is not a stage.

Every stage in [Stages] has an entry, which FlowVocabulary.EveryWordIs Documented pins: a stage added to the grammar without reference text is a hole a test finds rather than one a reader finds.

◆ Stages()

absl::Span< const std::string_view > a11::flow::vocabulary::Stages ( )

◆ StageTakes()

std::optional< StageArgument > a11::flow::vocabulary::StageTakes ( std::string_view canonical_name )

What a stage takes, or nullopt if the name is not a stage.

◆ StatementWords()

const absl::flat_hash_set< std::string_view > & a11::flow::vocabulary::StatementWords ( )

Words that open a statement, and so are not read as a name there.

◆ StatusCodes()

absl::Span< const std::string_view > a11::flow::vocabulary::StatusCodes ( )

Abseil's canonical status codes, lower case, which is what fail names.

◆ StatusFields()

const absl::flat_hash_set< std::string_view > & a11::flow::vocabulary::StatusFields ( )

The fields of a status record: what reading an outcome gives.

◆ TypeNames()

const absl::flat_hash_set< std::string_view > & a11::flow::vocabulary::TypeNames ( )

The built-in port type names.

Not the whole of what may stand where a type does: a port may name a type by the tag a serialisation registry knows it by (a11.sdk.AudioBuffer), say what a generic one holds (list[a11.NodeFragment]), or quote a mimetype.

◆ TypeParameters()

absl::Span< const int > a11::flow::vocabulary::TypeParameters ( std::string_view canonical_name )

How many type parameters a built-in type may be given.

Empty means none are allowed. A list says what it holds, an object what it maps; a tag is already concrete.

◆ WordRoleName()

std::string_view a11::flow::vocabulary::WordRoleName ( WordRole role )

The name a role travels under in flow.vocabulary/v1: port_modifier.

The same spelling as that envelope's word-list keys, so the documentation of a set and the set itself are found under names a reader can put together.

◆ WordRoles()

absl::Span< const WordRole > a11::flow::vocabulary::WordRoles ( )

Every role, for something walking all of them.

◆ WordsOf()

std::vector< std::string_view > a11::flow::vocabulary::WordsOf ( WordRole role )

The words role documents, in the order a listing reads them.

The ordered word list the role covers, which is what something writing every entry out walks. [WordRole::kSymbol] gives [OrderedSymbols], and the roles whose words are only ever a set give them sorted.

Classes

Enumerations

Functions