tool

package
v0.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2023 License: Apache-2.0 Imports: 0 Imported by: 0

Documentation

Overview

Package tool defines stateful operation types for cue commands.

This package is only visible in cue files with a _tool.cue or _tool_test.cue ending.

CUE configuration files are not influenced by and do not influence anything outside the configuration itself: they are hermetic. Tools solve two problems: allow outside values such as environment variables, file or web contents, random generators etc. to influence configuration, and allow configuration to be actionable from within the tooling itself. Separating these concerns makes it clear to user when outside influences are in play and the tool definition can be strict about what is allowed.

Tools are defined in files ending with _tool.cue. These files have a top-level map, "command", which defines all the tools made available through the cue command.

The following definitions are for defining commands in tool files:

// A Command specifies a user-defined command.
//
// Descriptions are derived from the doc comment, if they are not provided
// structurally, using the following format:
//
//    // short description on one line
//    //
//    // Usage: <name> usage (optional)
//    //
//    // long description covering the remainder of the doc comment.
//
Command: {
	// Tasks specifies the things to run to complete a command. Tasks are
	// typically underspecified and completed by the particular internal
	// handler that is running them. Tasks can be a single task, or a full
	// hierarchy of tasks.
	//
	// Tasks that depend on the output of other tasks are run after such tasks.
	// Use `$after` if a task needs to run after another task but does not
	// otherwise depend on its output.
	Tasks

	// $usage summarizes how a command takes arguments.
	//
	// Example:
	//     mycmd [-n] names
	$usage?: string

	// $short is short description of what the command does.
	$short?: string

	// $long is a longer description that spans multiple lines and
	// likely contain examples of usage of the command.
	$long?: string
}

// TODO:
// - child commands?

// Tasks defines a hierarchy of tasks. A command completes if all tasks have
// run to completion.
Tasks: Task | {
	[name=Name]: Tasks
}

// #Name defines a valid task or command name.
Name: =~#"^\PL([-](\PL|\PN))*$"#

// A Task defines a step in the execution of a command.
Task: {
	$type: "tool.Task" // legacy field 'kind' still supported for now.

	// $id indicates the operation to run. It must be of the form
	// packagePath.Operation.
	$id: =~#"\."#

	// $after can be used to specify a task is run after another one, when
	// it does not otherwise refer to an output of that task.
	$after?: Task | [...Task]
}

// TODO: consider these options:
//   $success: bool
//   $runif: a.b.$success or $guard: a.b.$success
// With this `$after: a.b` would just be a shorthand for `$guard: a.b.$success`.

Directories

Path Synopsis
Package cli provides tasks dealing with a console.
Package cli provides tasks dealing with a console.
Package exec defines tasks for running commands.
Package exec defines tasks for running commands.
Package file provides file operations for cue tasks.
Package file provides file operations for cue tasks.
Package http provides tasks related to the HTTP protocol.
Package http provides tasks related to the HTTP protocol.
Package os defines tasks for retrieving os-related information.
Package os defines tasks for retrieving os-related information.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL