mvdan.cc
1// Code generated by cuelang.org/go/pkg/gen. DO NOT EDIT.
2
3// Package tool defines stateful operation types for cue commands.
4//
5// This package is only visible in cue files with a _tool.cue or _tool_test.cue
6// ending.
7//
8// CUE configuration files are not influenced by and do not influence anything
9// outside the configuration itself: they are hermetic. Tools solve
10// two problems: allow outside values such as environment variables,
11// file or web contents, random generators etc. to influence configuration,
12// and allow configuration to be actionable from within the tooling itself.
13// Separating these concerns makes it clear to user when outside influences are
14// in play and the tool definition can be strict about what is allowed.
15//
16// Tools are defined in files ending with _tool.cue. These files have a
17// top-level map, "command", which defines all the tools made available through
18// the cue command.
19//
20// The following definitions are for defining commands in tool files:
21//
22// // A Command specifies a user-defined command.
23// //
24// // Descriptions are derived from the doc comment, if they are not provided
25// // structurally, using the following format:
26// //
27// // // short description on one line
28// // //
29// // // Usage: <name> usage (optional)
30// // //
31// // // long description covering the remainder of the doc comment.
32// //
33// Command: {
34// // Tasks specifies the things to run to complete a command. Tasks are
35// // typically underspecified and completed by the particular internal
36// // handler that is running them. Tasks can be a single task, or a full
37// // hierarchy of tasks.
38// //
39// // Tasks that depend on the output of other tasks are run after such tasks.
40// // Use `$after` if a task needs to run after another task but does not
41// // otherwise depend on its output.
42// Tasks
43//
44// // $usage summarizes how a command takes arguments.
45// //
46// // Example:
47// // mycmd [-n] names
48// $usage?: string
49//
50// // $short is short description of what the command does.
51// $short?: string
52//
53// // $long is a longer description that spans multiple lines and
54// // likely contain examples of usage of the command.
55// $long?: string
56// }
57//
58// // TODO:
59// // - child commands?
60//
61// // Tasks defines a hierarchy of tasks. A command completes if all tasks have
62// // run to completion.
63// Tasks: Task | {
64// [name=Name]: Tasks
65// }
66//
67// // #Name defines a valid task or command name.
68// Name: =~#"^\PL([-](\PL|\PN))*$"#
69//
70// // A Task defines a step in the execution of a command.
71// Task: {
72// // $id indicates the operation to run. Do not use this field directly;
73// // instead unify with a task imported from one of the tool packages.
74// $id: =~#"\."#
75//
76// // $after can be used to specify a task is run after another one,
77// // when it does not otherwise refer to an output of that task.
78// $after?: Task | [...Task]
79// }
80//
81// // TODO: consider these options:
82// // $success: bool
83// // $runif: a.b.$success or $guard: a.b.$success
84// // With this `$after: a.b` would just be a shorthand for `$guard: a.b.$success`.
85package tool