From df148ee6b6133e0466f7964eec027f2e0349cdbe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Mart=C3=AD?= Date: Mon, 1 Aug 2022 10:31:11 +0100 Subject: [PATCH] pkg: reuse pkg/gen to generate package godocs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Instead of sprinkling copies of a tiny gen.go program to do so, reuse pkg/gen which already knows how to generate for each package. Each package has a different header, so we use doc.txt files in each. Note that pkg/gen/packages.txt did not include the tool package itself. We want to include it now to generate its godoc like the others, but we don't want to start registering its package as it's not possible to import it from CUE code today. We might want to change that in the future, but for now, teach the generator to skip registering the package to not change that detail. Beyond the deduplication of code, this is also slightly faster, as we have fewer go:generate programs to run: $ time go generate ./... real 0m10.926s user 0m42.121s sys 0m6.126s $ git switch pkg-tool-generate $ time go generate ./... real 0m5.909s user 0m14.437s sys 0m3.311s Signed-off-by: Daniel Martí Change-Id: I3a0ae6dbbe0766731655c4202b8c6059d1834a4e Reviewed-on: https://review.gerrithub.io/c/cue-lang/cue/+/541844 Reviewed-by: Roger Peppe TryBot-Result: CUEcueckoo Unity-Result: CUEcueckoo --- pkg/gen/gen.go | 65 ++++++++++++------ pkg/gen/packages.txt | 1 + pkg/tool/cli/cli.go | 3 - pkg/tool/cli/doc.go | 33 ---------- pkg/tool/cli/doc.txt | 3 + pkg/tool/cli/gen.go | 47 ------------- pkg/tool/cli/pkg.go | 30 +++++++++ pkg/tool/doc.txt | 18 +++++ pkg/tool/exec/doc.go | 43 ------------ pkg/tool/exec/doc.txt | 3 + pkg/tool/exec/exec.go | 3 - pkg/tool/exec/gen.go | 47 ------------- pkg/tool/exec/pkg.go | 40 +++++++++++ pkg/tool/file/doc.go | 128 ------------------------------------ pkg/tool/file/doc.txt | 3 + pkg/tool/file/file.go | 3 - pkg/tool/file/gen.go | 47 ------------- pkg/tool/file/pkg.go | 125 +++++++++++++++++++++++++++++++++++ pkg/tool/gen.go | 62 ----------------- pkg/tool/generate.go | 18 ----- pkg/tool/http/doc.go | 53 --------------- pkg/tool/http/doc.txt | 3 + pkg/tool/http/gen.go | 47 ------------- pkg/tool/http/http.go | 3 - pkg/tool/http/pkg.go | 50 ++++++++++++++ pkg/tool/os/doc.go | 48 -------------- pkg/tool/os/doc.txt | 3 + pkg/tool/os/env.go | 3 - pkg/tool/os/gen.go | 48 -------------- pkg/tool/os/pkg.go | 45 +++++++++++++ pkg/tool/{doc.go => pkg.go} | 2 +- 31 files changed, 371 insertions(+), 656 deletions(-) delete mode 100644 pkg/tool/cli/doc.go create mode 100644 pkg/tool/cli/doc.txt delete mode 100644 pkg/tool/cli/gen.go create mode 100644 pkg/tool/doc.txt delete mode 100644 pkg/tool/exec/doc.go create mode 100644 pkg/tool/exec/doc.txt delete mode 100644 pkg/tool/exec/gen.go delete mode 100644 pkg/tool/file/doc.go create mode 100644 pkg/tool/file/doc.txt delete mode 100644 pkg/tool/file/gen.go delete mode 100644 pkg/tool/gen.go delete mode 100644 pkg/tool/generate.go delete mode 100644 pkg/tool/http/doc.go create mode 100644 pkg/tool/http/doc.txt delete mode 100644 pkg/tool/http/gen.go delete mode 100644 pkg/tool/os/doc.go create mode 100644 pkg/tool/os/doc.txt delete mode 100644 pkg/tool/os/gen.go rename pkg/tool/{doc.go => pkg.go} (98%) diff --git a/pkg/gen/gen.go b/pkg/gen/gen.go index a6144b9b3..558742460 100644 --- a/pkg/gen/gen.go +++ b/pkg/gen/gen.go @@ -58,16 +58,23 @@ var packagesStr string var packages = strings.Fields(packagesStr) type headerParams struct { - GenFile string - GoPkg string - CUEPkg string + GoPkg string + CUEPkg string + + PackageDoc string + PackageDefs string } var header = template.Must(template.New("").Parse( `// Code generated by cuelang.org/go/pkg/gen. DO NOT EDIT. +{{if .PackageDoc}} +{{.PackageDoc -}} +// {{.PackageDefs}} +{{end -}} package {{.GoPkg}} +{{if .CUEPkg -}} import ( "cuelang.org/go/internal/core/adt" "cuelang.org/go/pkg/internal" @@ -78,7 +85,7 @@ func init() { } var _ = adt.TopKind // in case the adt package isn't used - +{{end}} `)) func main() { @@ -122,27 +129,47 @@ func generate(cuePkgPath string) error { fset: token.NewFileSet(), } - if err := header.Execute(g.w, headerParams{ - GenFile: genFile, - GoPkg: pkg.Name, - CUEPkg: cuePkgPath, - }); err != nil { - return err + params := headerParams{ + GoPkg: pkg.Name, + CUEPkg: cuePkgPath, + } + // As a special case, the "tool" package cannot be imported from CUE. + skipRegister := params.CUEPkg == "tool" + if skipRegister { + params.CUEPkg = "" } - fmt.Fprintf(g.w, "var pkg = &internal.Package{\nNative: []*internal.Builtin{") - g.first = true - for _, filename := range pkg.GoFiles { - if filename == genFile { - continue + if doc, err := os.ReadFile(filepath.Join(pkg.Dir, "doc.txt")); err == nil { + defs, err := os.ReadFile(filepath.Join(pkg.Dir, pkg.Name+".cue")) + if err != nil { + return err } - g.processGo(filepath.Join(pkg.Dir, filename)) + i := bytes.Index(defs, []byte("package "+pkg.Name)) + defs = defs[i+len("package "+pkg.Name)+1:] + defs = bytes.ReplaceAll(defs, []byte("\n"), []byte("\n// ")) + params.PackageDoc = string(doc) + params.PackageDefs = string(defs) } - fmt.Fprintf(g.w, "},\n") - if err := g.processCUE(); err != nil { + + if err := header.Execute(g.w, params); err != nil { return err } - fmt.Fprintf(g.w, "}\n") + + if !skipRegister { + fmt.Fprintf(g.w, "var pkg = &internal.Package{\nNative: []*internal.Builtin{") + g.first = true + for _, filename := range pkg.GoFiles { + if filename == genFile { + continue + } + g.processGo(filepath.Join(pkg.Dir, filename)) + } + fmt.Fprintf(g.w, "},\n") + if err := g.processCUE(); err != nil { + return err + } + fmt.Fprintf(g.w, "}\n") + } b, err := format.Source(g.w.Bytes()) if err != nil { diff --git a/pkg/gen/packages.txt b/pkg/gen/packages.txt index 4ac48bad2..e46a4404e 100644 --- a/pkg/gen/packages.txt +++ b/pkg/gen/packages.txt @@ -17,6 +17,7 @@ crypto/sha512 crypto/md5 crypto/sha1 crypto/hmac +tool tool/os tool/cli tool/exec diff --git a/pkg/tool/cli/cli.go b/pkg/tool/cli/cli.go index 97ed5645a..3efd7ab17 100644 --- a/pkg/tool/cli/cli.go +++ b/pkg/tool/cli/cli.go @@ -14,9 +14,6 @@ package cli -//go:generate go run gen.go -//go:generate gofmt -s -w . - import ( "bufio" "fmt" diff --git a/pkg/tool/cli/doc.go b/pkg/tool/cli/doc.go deleted file mode 100644 index a0fb3e1b7..000000000 --- a/pkg/tool/cli/doc.go +++ /dev/null @@ -1,33 +0,0 @@ -// 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: { -// $id: *"tool/cli.Print" | "print" // for backwards compatibility -// -// // text is the text to be printed. -// text: string -// } -// -// // Ask prompts the current console with a message and waits for input. -// // -// // Example: -// // task: ask: cli.Ask({ -// // prompt: "Are you okay?" -// // response: bool -// // }) -// Ask: { -// $id: "tool/cli.Ask" -// -// // prompt sends this message to the output. -// prompt: string -// -// // response holds the user's response. If it is a boolean expression it -// // will interpret the answer using textual yes/ no. -// response: string | bool -// } -// -package cli diff --git a/pkg/tool/cli/doc.txt b/pkg/tool/cli/doc.txt new file mode 100644 index 000000000..e79722eab --- /dev/null +++ b/pkg/tool/cli/doc.txt @@ -0,0 +1,3 @@ +// Package cli provides tasks dealing with a console. +// +// These are the supported tasks: diff --git a/pkg/tool/cli/gen.go b/pkg/tool/cli/gen.go deleted file mode 100644 index 78bde7a39..000000000 --- a/pkg/tool/cli/gen.go +++ /dev/null @@ -1,47 +0,0 @@ -// 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. - -//go:build ignore -// +build ignore - -package main - -// TODO: remove when we have a cuedoc server. Until then, -// piggyback on pkg.go.dev. - -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/cli/pkg.go b/pkg/tool/cli/pkg.go index d1c433c9a..2283d8f56 100644 --- a/pkg/tool/cli/pkg.go +++ b/pkg/tool/cli/pkg.go @@ -1,5 +1,35 @@ // Code generated by cuelang.org/go/pkg/gen. 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: { +// $id: *"tool/cli.Print" | "print" // for backwards compatibility +// +// // text is the text to be printed. +// text: string +// } +// +// // Ask prompts the current console with a message and waits for input. +// // +// // Example: +// // task: ask: cli.Ask({ +// // prompt: "Are you okay?" +// // response: bool +// // }) +// Ask: { +// $id: "tool/cli.Ask" +// +// // prompt sends this message to the output. +// prompt: string +// +// // response holds the user's response. If it is a boolean expression it +// // will interpret the answer using textual yes/ no. +// response: string | bool +// } +// package cli import ( diff --git a/pkg/tool/doc.txt b/pkg/tool/doc.txt new file mode 100644 index 000000000..3e861399e --- /dev/null +++ b/pkg/tool/doc.txt @@ -0,0 +1,18 @@ +// 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: diff --git a/pkg/tool/exec/doc.go b/pkg/tool/exec/doc.go deleted file mode 100644 index ef4e88a73..000000000 --- a/pkg/tool/exec/doc.go +++ /dev/null @@ -1,43 +0,0 @@ -// 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: { -// $id: *"tool/exec.Run" | "exec" // exec for backwards compatibility -// -// // cmd is the command to run. -// cmd: string | [string, ...string] -// -// // dir specifies the working directory of the command. -// // The default is the current working directory. -// dir?: string -// -// // env defines the environment variables to use for this system. -// // If the value is a list, the entries mus be of the form key=value, -// // where the last value takes precendence in the case of multiple -// // occurrances of the same key. -// env: [string]: 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. If stdin is null, the stdin -// // of the current process is redirected to this command (the default). -// // If it is of typ bytes or string, that input will be used instead. -// stdin: *null | 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/doc.txt b/pkg/tool/exec/doc.txt new file mode 100644 index 000000000..1ddb6652d --- /dev/null +++ b/pkg/tool/exec/doc.txt @@ -0,0 +1,3 @@ +// Package exec defines tasks for running commands. +// +// These are the supported tasks: diff --git a/pkg/tool/exec/exec.go b/pkg/tool/exec/exec.go index 2145f14ca..2559b1c34 100644 --- a/pkg/tool/exec/exec.go +++ b/pkg/tool/exec/exec.go @@ -14,9 +14,6 @@ package exec -//go:generate go run gen.go -//go:generate gofmt -s -w . - import ( "fmt" "os/exec" diff --git a/pkg/tool/exec/gen.go b/pkg/tool/exec/gen.go deleted file mode 100644 index aae44bf7c..000000000 --- a/pkg/tool/exec/gen.go +++ /dev/null @@ -1,47 +0,0 @@ -// 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. - -//go:build ignore -// +build ignore - -package main - -// TODO: remove when we have a cuedoc server. Until then, -// piggyback on pkg.go.dev. - -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/exec/pkg.go b/pkg/tool/exec/pkg.go index 48596611e..08ee3e935 100644 --- a/pkg/tool/exec/pkg.go +++ b/pkg/tool/exec/pkg.go @@ -1,5 +1,45 @@ // Code generated by cuelang.org/go/pkg/gen. DO NOT EDIT. +// Package exec defines tasks for running commands. +// +// These are the supported tasks: +// +// // Run executes the given shell command. +// Run: { +// $id: *"tool/exec.Run" | "exec" // exec for backwards compatibility +// +// // cmd is the command to run. +// cmd: string | [string, ...string] +// +// // dir specifies the working directory of the command. +// // The default is the current working directory. +// dir?: string +// +// // env defines the environment variables to use for this system. +// // If the value is a list, the entries mus be of the form key=value, +// // where the last value takes precendence in the case of multiple +// // occurrances of the same key. +// env: [string]: 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. If stdin is null, the stdin +// // of the current process is redirected to this command (the default). +// // If it is of typ bytes or string, that input will be used instead. +// stdin: *null | 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 import ( diff --git a/pkg/tool/file/doc.go b/pkg/tool/file/doc.go deleted file mode 100644 index 3807aac1b..000000000 --- a/pkg/tool/file/doc.go +++ /dev/null @@ -1,128 +0,0 @@ -// 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: { -// $id: "tool/file.Read" -// -// // filename names the file to read. -// // -// // Relative names are taken relative to the current working directory. -// // Slashes are converted to the native OS path separator. -// 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: { -// $id: "tool/file.Append" -// -// // filename names the file to append. -// // -// // Relative names are taken relative to the current working directory. -// // Slashes are converted to the native OS path separator. -// filename: !="" -// -// // permissions defines the permissions to use if the file does not yet exist. -// permissions: int | *0o666 -// -// // contents specifies the bytes to be written. -// contents: bytes | string -// } -// -// // Create writes contents to the given file. -// Create: { -// $id: "tool/file.Create" -// -// // filename names the file to write. -// // -// // Relative names are taken relative to the current working directory. -// // Slashes are converted to the native OS path separator. -// filename: !="" -// -// // permissions defines the permissions to use if the file does not yet exist. -// permissions: int | *0o666 -// -// // contents specifies the bytes to be written. -// contents: bytes | string -// } -// -// // Glob returns a list of files. -// Glob: { -// $id: "tool/file.Glob" -// -// // glob specifies the pattern to match files with. -// // -// // A relative pattern is taken relative to the current working directory. -// // Slashes are converted to the native OS path separator. -// glob: !="" -// files: [...string] -// } -// -// // Mkdir creates a directory at the specified path. -// Mkdir: { -// $id: "tool/file.Mkdir" -// -// // The directory path to create. -// // If path is already a directory, Mkdir does nothing. -// // If path already exists and is not a directory, Mkdir will return an error. -// path: string -// -// // When true any necessary parents are created as well. -// createParents: bool | *false -// -// // Directory mode and permission bits (before umask). -// permissions: int | *0o755 -// } -// -// // MkdirAll creates a directory at the specified path along with any necessary -// // parents. -// // If path is already a directory, MkdirAll does nothing. -// // If path already exists and is not a directory, MkdirAll will return an error. -// MkdirAll: Mkdir & { -// createParents: true -// } -// -// // MkdirTemp creates a new temporary directory in the directory dir and sets -// // the pathname of the new directory in path. -// // It is the caller's responsibility to remove the directory when it is no -// // longer needed. -// MkdirTemp: { -// $id: "tool/file.MkdirTemp" -// -// // The temporary directory is created in the directory specified by dir. -// // If dir is the empty string, MkdirTemp uses the default directory for -// // temporary files. -// dir: string | *"" -// -// // The directory name is generated by adding a random string to the end of pattern. -// // If pattern includes a "*", the random string replaces the last "*" instead. -// pattern: string | *"" -// -// // The absolute path of the created directory. -// path: string -// } -// -// // RemoveAll removes path and any children it contains. -// // It removes everything it can but returns the first error it encounters. -// RemoveAll: { -// $id: "tool/file.RemoveAll" -// -// // The path to remove. -// // If the path does not exist, RemoveAll does nothing. -// path: string -// -// // success contains the status of the removal. -// // If path was removed success is set to true. -// // If path didn't exists success is set to false. -// success: bool -// } -// -package file diff --git a/pkg/tool/file/doc.txt b/pkg/tool/file/doc.txt new file mode 100644 index 000000000..cc0026fbd --- /dev/null +++ b/pkg/tool/file/doc.txt @@ -0,0 +1,3 @@ +// Package file provides file operations for cue tasks. +// +// These are the supported tasks: diff --git a/pkg/tool/file/file.go b/pkg/tool/file/file.go index 5f865f47b..740dcbb36 100644 --- a/pkg/tool/file/file.go +++ b/pkg/tool/file/file.go @@ -14,9 +14,6 @@ package file -//go:generate go run gen.go -//go:generate gofmt -s -w . - import ( "io/ioutil" "os" diff --git a/pkg/tool/file/gen.go b/pkg/tool/file/gen.go deleted file mode 100644 index b43cb779d..000000000 --- a/pkg/tool/file/gen.go +++ /dev/null @@ -1,47 +0,0 @@ -// 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. - -//go:build ignore -// +build ignore - -package main - -// TODO: remove when we have a cuedoc server. Until then, -// piggyback on pkg.go.dev. - -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/file/pkg.go b/pkg/tool/file/pkg.go index f32b26cab..c89944b47 100644 --- a/pkg/tool/file/pkg.go +++ b/pkg/tool/file/pkg.go @@ -1,5 +1,130 @@ // Code generated by cuelang.org/go/pkg/gen. DO NOT EDIT. +// Package file provides file operations for cue tasks. +// +// These are the supported tasks: +// +// // Read reads the contents of a file. +// Read: { +// $id: "tool/file.Read" +// +// // filename names the file to read. +// // +// // Relative names are taken relative to the current working directory. +// // Slashes are converted to the native OS path separator. +// 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: { +// $id: "tool/file.Append" +// +// // filename names the file to append. +// // +// // Relative names are taken relative to the current working directory. +// // Slashes are converted to the native OS path separator. +// filename: !="" +// +// // permissions defines the permissions to use if the file does not yet exist. +// permissions: int | *0o666 +// +// // contents specifies the bytes to be written. +// contents: bytes | string +// } +// +// // Create writes contents to the given file. +// Create: { +// $id: "tool/file.Create" +// +// // filename names the file to write. +// // +// // Relative names are taken relative to the current working directory. +// // Slashes are converted to the native OS path separator. +// filename: !="" +// +// // permissions defines the permissions to use if the file does not yet exist. +// permissions: int | *0o666 +// +// // contents specifies the bytes to be written. +// contents: bytes | string +// } +// +// // Glob returns a list of files. +// Glob: { +// $id: "tool/file.Glob" +// +// // glob specifies the pattern to match files with. +// // +// // A relative pattern is taken relative to the current working directory. +// // Slashes are converted to the native OS path separator. +// glob: !="" +// files: [...string] +// } +// +// // Mkdir creates a directory at the specified path. +// Mkdir: { +// $id: "tool/file.Mkdir" +// +// // The directory path to create. +// // If path is already a directory, Mkdir does nothing. +// // If path already exists and is not a directory, Mkdir will return an error. +// path: string +// +// // When true any necessary parents are created as well. +// createParents: bool | *false +// +// // Directory mode and permission bits (before umask). +// permissions: int | *0o755 +// } +// +// // MkdirAll creates a directory at the specified path along with any necessary +// // parents. +// // If path is already a directory, MkdirAll does nothing. +// // If path already exists and is not a directory, MkdirAll will return an error. +// MkdirAll: Mkdir & { +// createParents: true +// } +// +// // MkdirTemp creates a new temporary directory in the directory dir and sets +// // the pathname of the new directory in path. +// // It is the caller's responsibility to remove the directory when it is no +// // longer needed. +// MkdirTemp: { +// $id: "tool/file.MkdirTemp" +// +// // The temporary directory is created in the directory specified by dir. +// // If dir is the empty string, MkdirTemp uses the default directory for +// // temporary files. +// dir: string | *"" +// +// // The directory name is generated by adding a random string to the end of pattern. +// // If pattern includes a "*", the random string replaces the last "*" instead. +// pattern: string | *"" +// +// // The absolute path of the created directory. +// path: string +// } +// +// // RemoveAll removes path and any children it contains. +// // It removes everything it can but returns the first error it encounters. +// RemoveAll: { +// $id: "tool/file.RemoveAll" +// +// // The path to remove. +// // If the path does not exist, RemoveAll does nothing. +// path: string +// +// // success contains the status of the removal. +// // If path was removed success is set to true. +// // If path didn't exists success is set to false. +// success: bool +// } +// package file import ( diff --git a/pkg/tool/gen.go b/pkg/tool/gen.go deleted file mode 100644 index 84fd22925..000000000 --- a/pkg/tool/gen.go +++ /dev/null @@ -1,62 +0,0 @@ -// 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. - -//go:build ignore -// +build ignore - -package main - -// TODO: remove when we have a cuedoc server. Until then, -// piggyback on pkg.go.dev. - -import ( - "bytes" - "fmt" - "io/ioutil" - "os" -) - -const msg = `// Code generated by cue get go. DO NOT EDIT. - -// 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: -// %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 deleted file mode 100644 index 0e16bb7e0..000000000 --- a/pkg/tool/generate.go +++ /dev/null @@ -1,18 +0,0 @@ -// 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 -//go:generate go fmt diff --git a/pkg/tool/http/doc.go b/pkg/tool/http/doc.go deleted file mode 100644 index 0884f0fa1..000000000 --- a/pkg/tool/http/doc.go +++ /dev/null @@ -1,53 +0,0 @@ -// 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: { -// $id: *"tool/http.Do" | "http" // http for backwards compatibility -// -// method: string -// url: string // TODO: make url.URL type -// -// tls: { -// // Whether the server certificate must be validated. -// verify: *true | bool -// // PEM encoded certificate(s) to validate the server certificate. -// // If not set the CA bundle of the system is used. -// caCert?: bytes | string -// } -// -// request: { -// body?: bytes | string -// header: [string]: string | [...string] -// trailer: [string]: string | [...string] -// } -// response: { -// status: string -// statusCode: int -// -// body: *bytes | string -// header: [string]: string | [...string] -// trailer: [string]: string | [...string] -// } -// } -// -// // TODO: support serving once we have the cue serve command. -// // Serve: { -// // port: int -// // -// // cert: string -// // key: string -// // -// // handle: [Pattern=string]: Message & { -// // pattern: Pattern -// // } -// // } -// -package http diff --git a/pkg/tool/http/doc.txt b/pkg/tool/http/doc.txt new file mode 100644 index 000000000..e5b65b6e8 --- /dev/null +++ b/pkg/tool/http/doc.txt @@ -0,0 +1,3 @@ +// Package http provides tasks related to the HTTP protocol. +// +// These are the supported tasks: diff --git a/pkg/tool/http/gen.go b/pkg/tool/http/gen.go deleted file mode 100644 index c86e9829e..000000000 --- a/pkg/tool/http/gen.go +++ /dev/null @@ -1,47 +0,0 @@ -// 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. - -//go:build ignore -// +build ignore - -package main - -// TODO: remove when we have a cuedoc server. Until then, -// piggyback on pkg.go.dev. - -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 f30ec6c57..10b5c0439 100644 --- a/pkg/tool/http/http.go +++ b/pkg/tool/http/http.go @@ -14,9 +14,6 @@ package http -//go:generate go run gen.go -//go:generate gofmt -s -w . - import ( "bytes" "crypto/tls" diff --git a/pkg/tool/http/pkg.go b/pkg/tool/http/pkg.go index e66bdcf25..4440dbbfa 100644 --- a/pkg/tool/http/pkg.go +++ b/pkg/tool/http/pkg.go @@ -1,5 +1,55 @@ // Code generated by cuelang.org/go/pkg/gen. 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: { +// $id: *"tool/http.Do" | "http" // http for backwards compatibility +// +// method: string +// url: string // TODO: make url.URL type +// +// tls: { +// // Whether the server certificate must be validated. +// verify: *true | bool +// // PEM encoded certificate(s) to validate the server certificate. +// // If not set the CA bundle of the system is used. +// caCert?: bytes | string +// } +// +// request: { +// body?: bytes | string +// header: [string]: string | [...string] +// trailer: [string]: string | [...string] +// } +// response: { +// status: string +// statusCode: int +// +// body: *bytes | string +// header: [string]: string | [...string] +// trailer: [string]: string | [...string] +// } +// } +// +// // TODO: support serving once we have the cue serve command. +// // Serve: { +// // port: int +// // +// // cert: string +// // key: string +// // +// // handle: [Pattern=string]: Message & { +// // pattern: Pattern +// // } +// // } +// package http import ( diff --git a/pkg/tool/os/doc.go b/pkg/tool/os/doc.go deleted file mode 100644 index b4a66c188..000000000 --- a/pkg/tool/os/doc.go +++ /dev/null @@ -1,48 +0,0 @@ -// Code generated by cue get go. DO NOT EDIT. - -// Package os defines tasks for retrieving os-related information. -// -// CUE definitions: -// -// // A Value are all possible values allowed in flags. -// // A null value unsets an environment variable. -// Value: bool | number | *string | null -// -// // Name indicates a valid flag name. -// Name: !="" & !~"^[$]" -// -// // Setenv defines a set of command line flags, the values of which will be set -// // at run time. The doc comment of the flag is presented to the user in help. -// // -// // To define a shorthand, define the shorthand as a new flag referring to -// // the flag of which it is a shorthand. -// Setenv: { -// $id: "tool/os.Setenv" -// -// {[Name]: Value} -// } -// -// // Getenv gets and parses the specific command line variables. -// Getenv: { -// $id: "tool/os.Getenv" -// -// {[Name]: Value} -// } -// -// // Environ populates a struct with all environment variables. -// Environ: { -// $id: "tool/os.Environ" -// -// // A map of all populated values. -// // Individual entries may be specified ahead of time to enable -// // validation and parsing. Values that are marked as required -// // will fail the task if they are not found. -// {[Name]: Value} -// } -// -// // Clearenv clears all environment variables. -// Clearenv: { -// $id: "tool/os.Clearenv" -// } -// -package os diff --git a/pkg/tool/os/doc.txt b/pkg/tool/os/doc.txt new file mode 100644 index 000000000..fa48dc82e --- /dev/null +++ b/pkg/tool/os/doc.txt @@ -0,0 +1,3 @@ +// Package os defines tasks for retrieving os-related information. +// +// CUE definitions: diff --git a/pkg/tool/os/env.go b/pkg/tool/os/env.go index 0d0a535f0..e17af299a 100644 --- a/pkg/tool/os/env.go +++ b/pkg/tool/os/env.go @@ -14,9 +14,6 @@ package os -//go:generate go run gen.go -//go:generate gofmt -s -w . - import ( "os" "strings" diff --git a/pkg/tool/os/gen.go b/pkg/tool/os/gen.go deleted file mode 100644 index d4afcc491..000000000 --- a/pkg/tool/os/gen.go +++ /dev/null @@ -1,48 +0,0 @@ -// 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. - -//go:build ignore -// +build ignore - -package main - -// TODO: remove when we have a cuedoc server. Until then, -// piggyback on pkg.go.dev. - -import ( - "bytes" - "fmt" - "io/ioutil" - "os" -) - -const msg = `// Code generated by cue get go. DO NOT EDIT. - -// Package os defines tasks for retrieving os-related information. -// -// CUE definitions: -// %s -package os -` - -func main() { - f, _ := os.Create("doc.go") - defer f.Close() - b, _ := ioutil.ReadFile("os.cue") - i := bytes.Index(b, []byte("package os")) - b = b[i+len("package os")+1:] - b = bytes.ReplaceAll(b, []byte("\n"), []byte("\n// ")) - b = bytes.ReplaceAll(b, []byte("\t"), []byte(" ")) - fmt.Fprintf(f, msg, string(b)) -} diff --git a/pkg/tool/os/pkg.go b/pkg/tool/os/pkg.go index 382d0bc3c..1c522a86e 100644 --- a/pkg/tool/os/pkg.go +++ b/pkg/tool/os/pkg.go @@ -1,5 +1,50 @@ // Code generated by cuelang.org/go/pkg/gen. DO NOT EDIT. +// Package os defines tasks for retrieving os-related information. +// +// CUE definitions: +// +// // A Value are all possible values allowed in flags. +// // A null value unsets an environment variable. +// Value: bool | number | *string | null +// +// // Name indicates a valid flag name. +// Name: !="" & !~"^[$]" +// +// // Setenv defines a set of command line flags, the values of which will be set +// // at run time. The doc comment of the flag is presented to the user in help. +// // +// // To define a shorthand, define the shorthand as a new flag referring to +// // the flag of which it is a shorthand. +// Setenv: { +// $id: "tool/os.Setenv" +// +// {[Name]: Value} +// } +// +// // Getenv gets and parses the specific command line variables. +// Getenv: { +// $id: "tool/os.Getenv" +// +// {[Name]: Value} +// } +// +// // Environ populates a struct with all environment variables. +// Environ: { +// $id: "tool/os.Environ" +// +// // A map of all populated values. +// // Individual entries may be specified ahead of time to enable +// // validation and parsing. Values that are marked as required +// // will fail the task if they are not found. +// {[Name]: Value} +// } +// +// // Clearenv clears all environment variables. +// Clearenv: { +// $id: "tool/os.Clearenv" +// } +// package os import ( diff --git a/pkg/tool/doc.go b/pkg/tool/pkg.go similarity index 98% rename from pkg/tool/doc.go rename to pkg/tool/pkg.go index c8f6a5a08..96d451b1c 100644 --- a/pkg/tool/doc.go +++ b/pkg/tool/pkg.go @@ -1,4 +1,4 @@ -// Code generated by cue get go. DO NOT EDIT. +// Code generated by cuelang.org/go/pkg/gen. DO NOT EDIT. // Package tool defines stateful operation types for cue commands. // -- 2.51.2