pkg/tool: generate package documentation
Fixes #39
Change-Id: I3acc6bd67a8012dd8a33819d153ee5c97342faa5
Reviewed-on: https://cue-review.googlesource.com/c/cue/+/1926
Reviewed-by: Marcel van Lohuizen <mpvl@google.com>
diff --git a/cmd/cue/cmd/cmd.go b/cmd/cue/cmd/cmd.go
index 6f72669..c041fbe 100644
--- a/cmd/cue/cmd/cmd.go
+++ b/cmd/cue/cmd/cmd.go
@@ -52,16 +52,16 @@
// usage gives a short usage pattern of the command.
// Example:
// fmt [-n] [-x] [packages]
- usage: Name | string
+ usage?: Name | string
// short gives a brief on-line description of the command.
// Example:
// reformat package sources
- short: "" | string
+ short?: string
// long gives a detailed description of the command, including a
// description of flags usage and examples.
- long: "" | string
+ long?: string
// A task defines a single action to be run as part of this command.
// Each task can have inputs and outputs, depending on the type
@@ -103,15 +103,15 @@
// value defines the possible values for this flag.
// The default is string. Users can define default values by
// using disjunctions.
- value: env[Name].value | VarValue
+ value: *env[Name].value | VarValue
// name, if set, allows var to be set with the command-line flag
// of the given name. null disables the command line flag.
- name: Name | null | string
+ name?: *Name | string
// short defines an abbreviated version of the flag.
// Disabled by default.
- short: null | string
+ short?: string
}
// populate flag with the default values for
@@ -129,18 +129,18 @@
//
env <Name>: {
// name defines the environment variable that sets this flag.
- name: "CUE_VAR_" + strings.Upper(Name) | string | null
+ name?: *"CUE_VAR_" + strings.Upper(Name) | string
// The value retrieved from the environment variable or null
// if not set.
- value: null | string | bytes
+ value?: string | bytes
}
env: { "\(k)": { value: v } | null for k, v in var }
}
Available tasks can be found in the package documentation at
- cuelang.org/pkg/tool.
+ https://godoc.org/cuelang.org/go/pkg/tool
More on tasks can be found in the tasks topic.
@@ -158,11 +158,11 @@
// Say hello!
command hello: {
// whom to say hello to
- var who: "World" | string
+ var who: *"World" | string
- task print: exec.Run({
+ task print: exec.Run & {
cmd: "echo Hello \(var.who)! Welcome to \(city)."
- })
+ }
}
EOF
@@ -185,27 +185,27 @@
command hello: {
var file: "out.txt" | string // save transcript to this file
- task ask: cli.Ask({
+ task ask: cli.Ask & {
prompt: "What is your name?"
response: string
- })
+ }
// starts after ask
- task echo: exec.Run({
+ task echo: exec.Run & {
cmd: ["echo", "Hello", task.ask.response + "!"]
stdout: string // capture stdout
- })
+ }
// starts after echo
- task write: file.Append({
+ task write: file.Append & {
filename: var.file
contents: task.echo.stdout
- })
+ }
// also starts after echo
- task print: cli.Print({
+ task print: cli.Print & {
contents: task.echo.stdout
- })
+ }
}
`,
diff --git a/pkg/tool/cli/cli.go b/pkg/tool/cli/cli.go
index 1a5fb26..4b41c09 100644
--- a/pkg/tool/cli/cli.go
+++ b/pkg/tool/cli/cli.go
@@ -12,9 +12,10 @@
// See the License for the specific language governing permissions and
// limitations under the License.
-// Package cli provides tasks dealing with a console.
package cli
+//go:generate go run gen.go
+
import (
"fmt"
diff --git a/pkg/tool/cli/doc.go b/pkg/tool/cli/doc.go
new file mode 100644
index 0000000..7199ea0
--- /dev/null
+++ b/pkg/tool/cli/doc.go
@@ -0,0 +1,15 @@
+// Code generated by cue get go. DO NOT EDIT.
+
+// Package cli provides tasks dealing with a console.
+//
+// These are the supported tasks:
+//
+// // Print sends text to the stdout of the current process.
+// Print: {
+// kind: "tool/cli.Print"
+//
+// // text is the text to be printed.
+// text: string
+// }
+//
+package cli
diff --git a/pkg/tool/cli/gen.go b/pkg/tool/cli/gen.go
new file mode 100644
index 0000000..4325b72
--- /dev/null
+++ b/pkg/tool/cli/gen.go
@@ -0,0 +1,46 @@
+// Copyright 2019 CUE Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// +build ignore
+
+package main
+
+// TODO: remove when we have a cuedoc server. Until then,
+// piggyback on godoc.org.
+
+import (
+ "bytes"
+ "fmt"
+ "io/ioutil"
+ "os"
+)
+
+const msg = `// Code generated by cue get go. DO NOT EDIT.
+
+// Package cli provides tasks dealing with a console.
+//
+// These are the supported tasks:
+// %s
+package cli
+`
+
+func main() {
+ f, _ := os.Create("doc.go")
+ defer f.Close()
+ b, _ := ioutil.ReadFile("cli.cue")
+ i := bytes.Index(b, []byte("package cli"))
+ b = b[i+len("package cli")+1:]
+ b = bytes.ReplaceAll(b, []byte("\n"), []byte("\n// "))
+ fmt.Fprintf(f, msg, string(b))
+}
diff --git a/pkg/tool/doc.go b/pkg/tool/doc.go
new file mode 100644
index 0000000..0ddc762
--- /dev/null
+++ b/pkg/tool/doc.go
@@ -0,0 +1,51 @@
+// Code generated by cue get go. DO NOT EDIT.
+
+// Package tool defines statefull 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.
+// Command: {
+// //
+// // 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: define flags and environment variables.
+//
+// // tasks specifies the list of things to do to run command. Tasks are
+// // typically underspecified and completed by the particular internal
+// // handler that is running them. Task de
+// tasks <name>: Task
+// }
+//
+// // A Task defines a step in the execution of a command.
+// Task: {
+// // kind indicates the operation to run. It must be of the form
+// // packagePath.Operation.
+// kind: =~#"\."#
+// }
+//
+package tool
diff --git a/pkg/tool/exec/doc.go b/pkg/tool/exec/doc.go
new file mode 100644
index 0000000..67632e0
--- /dev/null
+++ b/pkg/tool/exec/doc.go
@@ -0,0 +1,38 @@
+// Code generated by cue get go. DO NOT EDIT.
+
+// Package exec defines tasks for running commands.
+//
+// These are the supported tasks:
+//
+// // Run executes the given shell command.
+// Run: {
+// kind: "tool/exec.Run"
+//
+// // cmd is the command to run.
+// cmd: string | [string, ...string]
+//
+// // install is an optional command to install the binaries needed
+// // to run the command.
+// install?: string | [string, ...string]
+//
+// // env defines the environment variables to use for this system.
+// env <Key>: string
+//
+// // stdout captures the output from stdout if it is of type bytes or string.
+// // The default value of null indicates it is redirected to the stdout of the
+// // current process.
+// stdout: *null | string | bytes
+//
+// // stderr is like stdout, but for errors.
+// stderr: *null | string | bytes
+//
+// // stdin specifies the input for the process.
+// stdin?: string | bytes
+//
+// // success is set to true when the process terminates with with a zero exit
+// // code or false otherwise. The user can explicitly specify the value
+// // force a fatal error if the desired success code is not reached.
+// success: bool
+// }
+//
+package exec
diff --git a/pkg/tool/exec/exec.cue b/pkg/tool/exec/exec.cue
index 585bf4f..78efc4e 100644
--- a/pkg/tool/exec/exec.cue
+++ b/pkg/tool/exec/exec.cue
@@ -44,12 +44,3 @@
// force a fatal error if the desired success code is not reached.
success: bool
}
-
-/* TODO
-// Env collects the environment variables of the current process.
-Env: {
- kind: "tool/exec.Env"
-
- env <Name>: string | number
-}
-*/
diff --git a/pkg/tool/exec/exec.go b/pkg/tool/exec/exec.go
index 169508e..9b68797 100644
--- a/pkg/tool/exec/exec.go
+++ b/pkg/tool/exec/exec.go
@@ -12,9 +12,10 @@
// See the License for the specific language governing permissions and
// limitations under the License.
-// Package exec defines tasks for running commands.
package exec
+//go:generate go run gen.go
+
import (
"errors"
"fmt"
diff --git a/pkg/tool/exec/gen.go b/pkg/tool/exec/gen.go
new file mode 100644
index 0000000..c8bc071
--- /dev/null
+++ b/pkg/tool/exec/gen.go
@@ -0,0 +1,46 @@
+// Copyright 2019 CUE Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// +build ignore
+
+package main
+
+// TODO: remove when we have a cuedoc server. Until then,
+// piggyback on godoc.org.
+
+import (
+ "bytes"
+ "fmt"
+ "io/ioutil"
+ "os"
+)
+
+const msg = `// Code generated by cue get go. DO NOT EDIT.
+
+// Package exec defines tasks for running commands.
+//
+// These are the supported tasks:
+// %s
+package exec
+`
+
+func main() {
+ f, _ := os.Create("doc.go")
+ defer f.Close()
+ b, _ := ioutil.ReadFile("exec.cue")
+ i := bytes.Index(b, []byte("package exec"))
+ b = b[i+len("package exec")+1:]
+ b = bytes.ReplaceAll(b, []byte("\n"), []byte("\n// "))
+ fmt.Fprintf(f, msg, string(b))
+}
diff --git a/pkg/tool/file/doc.go b/pkg/tool/file/doc.go
new file mode 100644
index 0000000..e52615f
--- /dev/null
+++ b/pkg/tool/file/doc.go
@@ -0,0 +1,55 @@
+// Code generated by cue get go. DO NOT EDIT.
+
+// Package file provides file operations for cue tasks.
+//
+// These are the supported tasks:
+//
+// // Read reads the contents of a file.
+// Read: {
+// kind: "tool/file.Read"
+//
+// // filename names the file to read.
+// filename: !=""
+//
+// // contents is the read contents. If the contents are constraint to bytes
+// // (the default), the file is read as is. If it is constraint to a string,
+// // the contents are checked to be valid UTF-8.
+// contents: *bytes | string
+// }
+//
+// // Append writes contents to the given file.
+// Append: {
+// kind: "tool/file.Append"
+//
+// // filename names the file to append.
+// filename: !=""
+//
+// // permissions defines the permissions to use if the file does not yet exist.
+// permissions: int | *0o644
+//
+// // contents specifies the bytes to be written.
+// contents: bytes | string
+// }
+//
+// // Create writes contents to the given file.
+// Create: {
+// kind: "tool/file.Create"
+//
+// // filename names the file to write.
+// filename: !=""
+//
+// // permissions defines the permissions to use if the file does not yet exist.
+// permissions: int | *0o644
+//
+// // contents specifies the bytes to be written.
+// contents: bytes | string
+// }
+//
+// Glob: {
+// kind: "tool/file.Glob"
+//
+// glob: !=""
+// files: [...string]
+// }
+//
+package file
diff --git a/pkg/tool/file/file.go b/pkg/tool/file/file.go
index e5673cc..29bf6d9 100644
--- a/pkg/tool/file/file.go
+++ b/pkg/tool/file/file.go
@@ -12,9 +12,10 @@
// See the License for the specific language governing permissions and
// limitations under the License.
-// Package file provides file operations for cue tasks.
package file
+//go:generate go run gen.go
+
import (
"io/ioutil"
"os"
diff --git a/pkg/tool/file/gen.go b/pkg/tool/file/gen.go
new file mode 100644
index 0000000..a67f796
--- /dev/null
+++ b/pkg/tool/file/gen.go
@@ -0,0 +1,46 @@
+// Copyright 2019 CUE Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// +build ignore
+
+package main
+
+// TODO: remove when we have a cuedoc server. Until then,
+// piggyback on godoc.org.
+
+import (
+ "bytes"
+ "fmt"
+ "io/ioutil"
+ "os"
+)
+
+const msg = `// Code generated by cue get go. DO NOT EDIT.
+
+// Package file provides file operations for cue tasks.
+//
+// These are the supported tasks:
+// %s
+package file
+`
+
+func main() {
+ f, _ := os.Create("doc.go")
+ defer f.Close()
+ b, _ := ioutil.ReadFile("file.cue")
+ i := bytes.Index(b, []byte("package file"))
+ b = b[i+len("package file")+1:]
+ b = bytes.ReplaceAll(b, []byte("\n"), []byte("\n// "))
+ fmt.Fprintf(f, msg, string(b))
+}
diff --git a/pkg/tool/gen.go b/pkg/tool/gen.go
new file mode 100644
index 0000000..6c0ea21
--- /dev/null
+++ b/pkg/tool/gen.go
@@ -0,0 +1,61 @@
+// Copyright 2019 CUE Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// +build ignore
+
+package main
+
+// TODO: remove when we have a cuedoc server. Until then,
+// piggyback on godoc.org.
+
+import (
+ "bytes"
+ "fmt"
+ "io/ioutil"
+ "os"
+)
+
+const msg = `// Code generated by cue get go. DO NOT EDIT.
+
+// Package tool defines statefull 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:
+// %s
+package tool
+`
+
+func main() {
+ f, _ := os.Create("doc.go")
+ defer f.Close()
+ b, _ := ioutil.ReadFile("tool.cue")
+ i := bytes.Index(b, []byte("package tool"))
+ b = b[i+len("package tool")+1:]
+ b = bytes.ReplaceAll(b, []byte("\n"), []byte("\n// "))
+ fmt.Fprintf(f, msg, string(b))
+}
diff --git a/pkg/tool/generate.go b/pkg/tool/generate.go
new file mode 100644
index 0000000..ba77048
--- /dev/null
+++ b/pkg/tool/generate.go
@@ -0,0 +1,17 @@
+// Copyright 2019 CUE Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package tool
+
+//go:generate go run gen.go
diff --git a/pkg/tool/http/doc.go b/pkg/tool/http/doc.go
new file mode 100644
index 0000000..5827610
--- /dev/null
+++ b/pkg/tool/http/doc.go
@@ -0,0 +1,33 @@
+// Code generated by cue get go. DO NOT EDIT.
+
+// Package http provides tasks related to the HTTP protocol.
+//
+// These are the supported tasks:
+//
+// Get: Do & {method: "GET"}
+// Post: Do & {method: "POST"}
+// Put: Do & {method: "PUT"}
+// Delete: Do & {method: "DELETE"}
+//
+// Do: {
+// kind: "tool/http.Do"
+//
+// method: string
+// url: string // TODO: make url.URL type
+//
+// request: {
+// body: *bytes | string
+// header <Name>: string | [...string]
+// trailer <Name>: string | [...string]
+// }
+// response: {
+// status: string
+// statusCode: int
+//
+// body: *bytes | string
+// header <Name>: string | [...string]
+// trailer <Name>: string | [...string]
+// }
+// }
+//
+package http
diff --git a/pkg/tool/http/gen.go b/pkg/tool/http/gen.go
new file mode 100644
index 0000000..88c9752
--- /dev/null
+++ b/pkg/tool/http/gen.go
@@ -0,0 +1,46 @@
+// Copyright 2019 CUE Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// +build ignore
+
+package main
+
+// TODO: remove when we have a cuedoc server. Until then,
+// piggyback on godoc.org.
+
+import (
+ "bytes"
+ "fmt"
+ "io/ioutil"
+ "os"
+)
+
+const msg = `// Code generated by cue get go. DO NOT EDIT.
+
+// Package http provides tasks related to the HTTP protocol.
+//
+// These are the supported tasks:
+// %s
+package http
+`
+
+func main() {
+ f, _ := os.Create("doc.go")
+ defer f.Close()
+ b, _ := ioutil.ReadFile("http.cue")
+ i := bytes.Index(b, []byte("package http"))
+ b = b[i+len("package http")+1:]
+ b = bytes.ReplaceAll(b, []byte("\n"), []byte("\n// "))
+ fmt.Fprintf(f, msg, string(b))
+}
diff --git a/pkg/tool/http/http.go b/pkg/tool/http/http.go
index 86565b6..f43ff7c 100644
--- a/pkg/tool/http/http.go
+++ b/pkg/tool/http/http.go
@@ -12,9 +12,10 @@
// See the License for the specific language governing permissions and
// limitations under the License.
-// Package http provides tasks related to the HTTP protocol.
package http
+//go:generate go run gen.go
+
import (
"io"
"io/ioutil"
