1// Copyright 2018 The CUE Authors
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15package tool
16
17// A Command specifies a user-defined command.
18//
19// Descriptions are derived from the doc comment, if they are not provided
20// structurally, using the following format:
21//
22// // short description on one line
23// //
24// // Usage: <name> usage (optional)
25// //
26// // long description covering the remainder of the doc comment.
27//
28Command: {
29 // Tasks specifies the things to run to complete a command. Tasks are
30 // typically underspecified and completed by the particular internal
31 // handler that is running them. Tasks can be a single task, or a full
32 // hierarchy of tasks.
33 //
34 // Tasks that depend on the output of other tasks are run after such tasks.
35 // Use `$after` if a task needs to run after another task but does not
36 // otherwise depend on its output.
37 Tasks
38
39 // $usage summarizes how a command takes arguments.
40 //
41 // Example:
42 // mycmd [-n] names
43 $usage?: string
44
45 // $short is short description of what the command does.
46 $short?: string
47
48 // $long is a longer description that spans multiple lines and
49 // likely contain examples of usage of the command.
50 $long?: string
51}
52
53// TODO:
54// - child commands?
55
56// Tasks defines a hierarchy of tasks. A command completes if all tasks have
57// run to completion.
58Tasks: Task | {
59 [name=Name]: Tasks
60}
61
62// #Name defines a valid task or command name.
63Name: =~#"^\PL([-](\PL|\PN))*$"#
64
65// A Task defines a step in the execution of a command.
66Task: {
67 $type: "tool.Task" // legacy field 'kind' still supported for now.
68
69 // $id indicates the operation to run. It must be of the form
70 // packagePath.Operation.
71 $id: =~#"\."#
72
73 // $after can be used to specify a task is run after another one, when
74 // it does not otherwise refer to an output of that task.
75 $after?: Task | [...Task]
76}
77
78// TODO: consider these options:
79// $success: bool
80// $runif: a.b.$success or $guard: a.b.$success
81// With this `$after: a.b` would just be a shorthand for `$guard: a.b.$success`.
View as plain text