github.com/solo-io/cue@v0.4.7/pkg/tool/doc.go (about)

     1  // Code generated by cue get go. DO NOT EDIT.
     2  
     3  // Package tool defines statefull 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  //     	//
    45  //     	// Example:
    46  //     	//     mycmd [-n] names
    47  //     	$usage?: string
    48  //
    49  //     	// short is short description of what the command does.
    50  //     	$short?: string
    51  //
    52  //     	// long is a longer description that spans multiple lines and
    53  //     	// likely contain examples of usage of the command.
    54  //     	$long?: string
    55  //     }
    56  //
    57  //     // TODO:
    58  //     // - child commands?
    59  //
    60  //     // Tasks defines a hierarchy of tasks. A command completes if all tasks have
    61  //     // run to completion.
    62  //     Tasks: Task | {
    63  //     	[name=Name]: Tasks
    64  //     }
    65  //
    66  //     // #Name defines a valid task or command name.
    67  //     Name: =~#"^\PL([-](\PL|\PN))*$"#
    68  //
    69  //     // A Task defines a step in the execution of a command.
    70  //     Task: {
    71  //     	$type: "tool.Task" // legacy field 'kind' still supported for now.
    72  //
    73  //     	// kind indicates the operation to run. It must be of the form
    74  //     	// packagePath.Operation.
    75  //     	$id: =~#"\."#
    76  //
    77  //     	// $after can be used to specify a task is run after another one, when
    78  //     	// it does not otherwise refer to an output of that task.
    79  //     	$after?: Task | [...Task]
    80  //     }
    81  //
    82  //     // TODO: consider these options:
    83  //     //   $success: bool
    84  //     //   $runif: a.b.$success or $guard: a.b.$success
    85  //     // With this `$after: a.b` would just be a shorthand for `$guard: a.b.$success`.
    86  //
    87  package tool