Table of Contents

API Reference

This section is the generated reference for every public type in the three Invex.StructuredText packages, built from the XML documentation comments in the source code; the tables below list each type by package and namespace. Union records are Dunet discriminated unions: construct one of their nested variant records (for example new Step.RunStep { ... }).

Invex.StructuredText

NuGet. The core: StructuredTextWriter and the platform-agnostic expression API.

Invex.StructuredText

Type Kind Description
StructuredTextWriter Class An indentation-aware text writer for producing structured text such as YAML.

Invex.StructuredText.Expressions

Start with Tex: every way to create an expression is one of its members. See Expressions.

Type Kind Description
BoolCast Record Treats Operand as a boolean. Rendered transparently.
BoolContext Record A boolean-valued context path.
BoolExpr Abstract record An expression that evaluates to a boolean.
BoolFunction Record A function call that returns a boolean.
BoolLiteral Record A boolean literal.
ComparisonExpr Record A comparison between two values.
ComparisonOperator Enum The comparison operators.
Expr Abstract record The base type of the typed expression tree. Every node derives from one of the four result-typed roots: BoolExpr, StringExpr, NumberExpr or JsonExpr.
ExpressionPrinter Abstract class Renders typed expression trees (Expr) and Templates to platform syntax.
FunctionNames Static class Canonical names of the functions the core knows about. Printers map them to the platform's own names.
IContextPath Interface Implemented by nodes that reference a dotted context path such as a.b.c.
IndexAccessExpr Record Accesses element Index of Target.
InputRef Record An input (parameter) supplied when the run was started.
IRawExpr Interface Implemented by nodes that hold verbatim expression text.
JobOutputRef Record An output of another job that the current job depends on.
JobResultRef Record The result of another job that the current job depends on. Compare with ResultLiteral.
JsonContext Record A context path whose value is an object, an array or of unknown type.
JsonExpr Abstract record An expression whose value is an object, an array, or of a type not known statically.
JsonFunction Record A function call that returns an object, an array or a value of unknown type.
LogicalExpr Record An AND or OR over two or more conditions. Nested nodes with the same operator are flattened.
LogicalOperator Enum The logical operators.
MatrixRef Record The current value of a matrix dimension.
MemberAccessExpr Record Accesses Property of Target.
NotExpr Record The logical negation of Operand.
NullLiteral Record The null literal.
NumberCast Record Treats Operand as a number. Rendered transparently.
NumberContext Record A number-valued context path.
NumberExpr Abstract record An expression that evaluates to a number.
NumberLiteral Record A numeric literal, rendered with the invariant culture.
RawExpr Record Verbatim expression text, created by Raw. It is a condition, and converts implicitly to string, number and JSON expressions.
RawJson Record Verbatim expression text of an object, array or unknown type.
RawNumber Record Verbatim number-valued expression text.
RawString Record Verbatim string-valued expression text.
ReferenceExpr Abstract record A reference to a value every supported platform provides (a secret, variable, input, matrix value or output). Each platform's printer decides the syntax.
ResultLiteral Record A result value, rendered with the platform's own spelling.
RunResult Enum The possible results of a job or step.
SecretRef Record A secret.
StepOutputRef Record An output of an earlier step in the current job.
StringCast Record Treats Operand as a string. Rendered transparently.
StringContext Record A string-valued context path.
StringExpr Abstract record An expression that evaluates to a string.
StringFunction Record A function call that returns a string.
StringLiteral Record A string literal, rendered quoted and escaped.
Template Class A text value made of literal text and embedded expressions, such as a YAML scalar.
TemplatePart Record struct One part of a Template: either literal text or an embedded expression.
Tex Static class The starting point for writing expressions. Everything that creates an expression from scratch lives here: references (Secret, JobOutput, …), status checks (Success, …), functions (All, Format, …) and the escape hatch Raw. Platform packages add their own members, such as Tex.GitHub for the GitHub Actions contexts.
VariableRef Record A configuration variable defined outside the workflow.

Invex.StructuredText.GithubActions

NuGet. GitHub Actions workflow and Dependabot configuration generation.

Invex.StructuredText.GithubActions

Type Kind Description
DependabotConfigWriter Class Serializes a DependabotConfig model to Dependabot v2 configuration YAML (.github/dependabot.yml).
GithubActionWriter Class Serializes a GithubAction model to GitHub Actions workflow YAML. Expressions embedded in the model are rendered with GithubExpressionPrinter.
GitHubContexts Class The GitHub Actions contexts, reached through Tex.GitHub. Generated from Contexts/github.contexts; nested contexts such as Tex.GitHub.Event.PullRequest are GitHubContexts…Context classes.
GithubExpressionPrinter Class Renders typed expressions (Expr) and Templates to GitHub Actions expression syntax: infix operators (==, &&, !), single-quoted string literals, and ${{ … }} around expressions embedded in text.
TexGitHubExtensions Static class Adds the GitHub Actions contexts to Tex.

Invex.StructuredText.GithubActions.GithubActionModel

Type Kind Description
Concurrency Record Concurrency settings (concurrency) that ensure only one run (or queued run) sharing the same group executes at a time, at either workflow or job level.
Container Record A Docker container that a job runs in (container) or that hosts a service (services).
Credentials Record Credentials for a private container registry (credentials), passed to docker login.
Environment Record The deployment environment a job targets (environment).
GithubAction Record The root model of a GitHub Actions workflow file (.github/workflows/*.yml).
Job Record A job within a workflow: a set of steps that execute on the same runner.
Matrix Record A matrix of variable combinations to run a job with (strategy.matrix).
On Union record A workflow trigger event (on).
Permissions Union record GITHUB_TOKEN permissions at workflow or job level (permissions).
PermissionsEvent Record Per-scope GITHUB_TOKEN permission levels.
PermissionsLevel Enum The access level granted to a GITHUB_TOKEN permission scope.
RunsOn Record The runner selection for a job (runs-on).
Snapshot Record Runner image snapshot settings for a job (snapshot), used to capture the runner state as a custom image after the job completes.
Step Union record A single step within a job.
Strategy Record The execution strategy for a job (strategy), defining a matrix of variations to run.
WorkflowDispatchInput Union record A typed input for the workflow_dispatch trigger.

Invex.StructuredText.GithubActions.DependabotConfigModel.Model

Type Kind Description
BranchNameSeparator Enum Branch name separator.
CommitMessageInclude Enum Commit message include option.
DependabotAllow Record Allow rule for Dependabot updates.
DependabotCommitMessage Record Commit message preferences for Dependabot.
DependabotConfig Record GitHub Dependabot v2 configuration.
DependabotCooldown Record Cooldown configuration for dependency updates.
DependabotGroup Union record Group configuration for dependencies.
DependabotIgnore Record Ignore rule for Dependabot updates.
DependabotMultiEcosystemGroup Record Multi-ecosystem group configuration that spans multiple package ecosystems.
DependabotPullRequestBranchName Record Pull request branch name preferences.
DependabotRegistries Union record Registries to use for an update configuration: a list of registry names or * for all.
DependabotRegistry Record Private package registry configuration.
DependabotSchedule Record Schedule preferences for Dependabot updates.
DependabotUpdate Record Package ecosystem configuration for Dependabot updates.
DependabotVersions Union record Versions to ignore: a single version string or a list of version strings.
DependencyType Enum Dependency type for allow/ignore rules.
GroupAppliesTo Enum Specifies whether the rules in the group apply to version updates or security updates.
GroupBy Enum Configure how dependencies are grouped.
GroupDependencyType Enum Dependency type for groups.
GroupUpdateType Enum Semantic versioning update type.
InsecureExternalCodeExecution Enum Allow or deny code execution in manifest files.
PackageEcosystem Enum Package ecosystem values for Dependabot.
RebaseStrategy Enum Rebase strategy for Dependabot.
RegistryType Enum Registry type for Dependabot.
ScheduleDay Enum Schedule day for Dependabot updates.
ScheduleInterval Enum Schedule interval for Dependabot updates.
SemverUpdateType Enum Semantic version update type.
VersioningStrategy Enum How to update manifest version requirements.

Invex.StructuredText.AzureDevopsPipelines

NuGet. Azure DevOps Pipelines YAML generation.

Invex.StructuredText.AzureDevopsPipelines

Type Kind Description
DevopsAgentVariables Class Agent.* predefined variables.
DevopsBuildVariables Class Build.* predefined variables.
DevopsContexts Class Azure DevOps predefined variables and run-time expressions, reached through Tex.DevOps. Each variable is a Variable reference: $(Build.BuildId) in a template and variables['Build.BuildId'] in a condition.
DevopsExpressionPrinter Class Renders typed expressions (Expr) and Templates to Azure DevOps syntax. Operators are functions (and(...), or(...), not(...), eq(...), …) and status checks are succeeded(), failed(), canceled() and always().
DevopsPipelineWriter Class Serializes a DevopsPipeline model to Azure Pipelines YAML. Expressions embedded in the model are rendered with DevopsExpressionPrinter.
DevopsRuntimeExpr Record Marks an expression to be evaluated at run time. Embedded in a Template, it renders as $[ … ] instead of the compile-time ${{ … }}. Create one with Tex.DevOps.Runtime(…).
DevopsSystemVariables Class System.* predefined variables.
TexDevopsExtensions Static class Adds the Azure DevOps predefined variables and run-time expressions to Tex.

Invex.StructuredText.AzureDevopsPipelines.DevopsPipelineModel.Jobs

Type Kind Description
DeploymentEnvironment Union record Deployment environment specification.
DeploymentHook Record Deployment lifecycle hook containing steps.
DeploymentStrategy Union record Deployment strategy for a deployment job.
ExplicitResources Record Explicit resource references for a job.
Job Union record A job represents a unit of work which can be assigned to a single agent or server.
JobContainer Union record Container resource for a job.
JobStrategy Record Execution strategy for a job.

Invex.StructuredText.AzureDevopsPipelines.DevopsPipelineModel.Pipeline

Type Kind Description
DevopsPipeline Union record A pipeline is one or more stages that describe a CI/CD process.

Invex.StructuredText.AzureDevopsPipelines.DevopsPipelineModel.Resources

Type Kind Description
BuildResource Record Build resource definition.
ContainerResource Record Container image resource definition.
ContainerResourceTrigger Record Container resource trigger definition.
PackageResource Record Package resource definition.
PipelineResource Record Pipeline resource definition.
PipelineResourceTrigger Record Pipeline resource trigger definition.
RepositoryResource Record Repository resource definition.
Resources Record Resources specifies builds, repositories, pipelines, and other resources used by the pipeline.
WebhookFilter Record Webhook filter definition.
WebhookResource Record Webhook resource definition.

Invex.StructuredText.AzureDevopsPipelines.DevopsPipelineModel.Stages

Type Kind Description
Stage Union record A stage is a collection of related jobs.

Invex.StructuredText.AzureDevopsPipelines.DevopsPipelineModel.Steps

Type Kind Description
SettableVariables Record Restrictions on which variables can be set from a step.
Step Union record Steps are a linear sequence of operations that make up a job.
StepTarget Union record Environment in which to run a step.

Invex.StructuredText.AzureDevopsPipelines.DevopsPipelineModel.Supporting

Type Kind Description
Extends Record Extends a template.
IncludeExcludeFilters Record Include and exclude filters for branches, paths, or tags.
Parameter Record Pipeline template parameter definition.
Pool Union record Specifies which pool to use for a job of the pipeline.
Schedule Record Scheduled trigger (cron).
Workspace Record Workspace options on the agent.

Invex.StructuredText.AzureDevopsPipelines.DevopsPipelineModel.Triggers

Type Kind Description
Pr Union record A pull request trigger specifies which branches cause a pull request build to run.
Trigger Union record A push trigger specifies which branches cause a continuous integration build to run.

Invex.StructuredText.AzureDevopsPipelines.DevopsPipelineModel.Variables

Type Kind Description
Variable Union record A variable definition that can be a named variable, variable group, or template reference.
Variables Union record Define variables using name/value pairs or variable lists.

Typical flow

Build a model, write it with the platform writer, then read the text from the writer's StructuredTextWriter:

var writer = new GithubActionWriter();           // or DependabotConfigWriter / DevopsPipelineWriter
writer.Write(workflow);                          // DependabotConfigWriter uses WriteConfig(config)

File.WriteAllText(".github/workflows/ci.yml", writer.TextWriter.ToString());

For concepts and guides, start with the Introduction.