From ee0ce4b2e9ba07bf04eeed6276930a2d218563c9 Mon Sep 17 00:00:00 2001 From: Bart Spaans Date: Tue, 14 Nov 2017 14:50:40 +0000 Subject: [PATCH] Use escape-core markdown generator on the EscapePlan struct --- .gitignore | 1 + docs/escape-plan.md | 115 ------ docs/generate_cmd_docs.go | 144 +++++-- scripts/build.sh | 3 +- .../github.com/ankyra/escape-core/README.md | 7 +- vendor/github.com/ankyra/escape-core/build.sh | 4 +- vendor/github.com/ankyra/escape-core/core.go | 2 +- .../ankyra/escape-core/dependency.go | 3 +- .../ankyra/escape-core/dependency_config.go | 11 + .../ankyra/escape-core/docs/generate_pages.go | 134 ++++++ .../escape-core/docs/generate_stdlib_docs.go | 7 +- .../docs/generated/dependencies.md | 21 + .../escape-core/docs/generated/downloads.md | 27 ++ .../escape-core/docs/generated/errands.md | 30 ++ .../generated/input-and-output-variables.md | 33 ++ .../docs/generated/providers-and-consumers.md | 15 + .../docs/{ => generated}/stdlib.md | 48 +-- .../escape-core/docs/generated/templates.md | 24 ++ .../escape-core/docs/scripting_language.md | 382 ------------------ .../ankyra/escape-core/download_config.go | 44 +- .../github.com/ankyra/escape-core/errand.go | 38 +- .../ankyra/escape-core/release.json | 44 +- .../ankyra/escape-core/templates/templates.go | 26 +- vendor/github.com/ankyra/escape-core/test.sh | 2 +- .../ankyra/escape-core/variables/variable.go | 65 ++- 25 files changed, 623 insertions(+), 607 deletions(-) delete mode 100644 docs/escape-plan.md create mode 100644 vendor/github.com/ankyra/escape-core/docs/generate_pages.go create mode 100644 vendor/github.com/ankyra/escape-core/docs/generated/dependencies.md create mode 100644 vendor/github.com/ankyra/escape-core/docs/generated/downloads.md create mode 100644 vendor/github.com/ankyra/escape-core/docs/generated/errands.md create mode 100644 vendor/github.com/ankyra/escape-core/docs/generated/input-and-output-variables.md create mode 100644 vendor/github.com/ankyra/escape-core/docs/generated/providers-and-consumers.md rename vendor/github.com/ankyra/escape-core/docs/{ => generated}/stdlib.md (100%) create mode 100644 vendor/github.com/ankyra/escape-core/docs/generated/templates.md delete mode 100644 vendor/github.com/ankyra/escape-core/docs/scripting_language.md diff --git a/.gitignore b/.gitignore index 0b9b202..689cbb6 100644 --- a/.gitignore +++ b/.gitignore @@ -10,6 +10,7 @@ lock.json manifest.json deps/ docs/cmd/ +docs/generated/ model/runners/build/testdata/*.json model/runners/deploy/testdata/ model/runners/deploy/testdata/*.json diff --git a/docs/escape-plan.md b/docs/escape-plan.md deleted file mode 100644 index 7f2181f..0000000 --- a/docs/escape-plan.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -date: 2017-11-11 00:00:00 -title: "The Escape Plan" -slug: escape-plan -type: "docs" -toc: true ---- - -The Escape Plan describes a package. - -Field | Type | Description -------|------|------------- -|name|`string`|The build name. Format: /[a-zA-Z]+[a-zA-Z0-9-]*/ -||| -|version|`string`|The version. Either specify the full version or use the '@' symbol to let Escape pick the next version at build time. Format: /[0-9]+(\.[0-9]+)*(\.@)?/ -|||Examples: -|||Build version 1.5: version: 1.5 -|||Build the next minor release in the 1.* series: version: 1.@ -|||Build the next path release in the 1.1.* series: version: 1.1.@ -||| -|description|`string`|An (optional) description for this release. -||| -|logo|`string`| -||| -|extends|`[string]` [Extensions](/docs/extensions/) | -||| -|depends|`[string]` [Dependencies](/docs/dependencies/) |Dependencies. Reference dependencies by their full release ID or use the '@' symbol to resolve versions at build time. -|||Examples: -|||Reference the full release ID to pin to a particular version: depends: [archive-example-v0.1] -|||To always get the latest version of a particular release: depends: [archive-example-latest] -|||Or: depends: [archive-example-@] -|||To resolve the latest minor release: depends: [archive-example-v0.@] -|||To resolve the latest path release: depends: [archive-example-v0.1.@] -||| -|consumes|`[string]` [Consumers](/docs/providers-and-consumers/) |The release can consume zero or more providers from the environment its deployed in. -||| -|build_consumes|`[string]` [Consumers](/docs/providers-and-consumers/) |The release can consume zero or more providers at build time. -||| -|deploy_consumes|`[string]` [Consumers](/docs/providers-and-consumers/) |The release can consume zero or more providers at deploy time. -||| -|provides|`[string]` [Consumers](/docs/providers-and-consumers/) |The release can provide zero or more providers for other releases to consume at deployment time. -||| -|inputs|`[string]` [Variables](/docs/input-and-output-variables/) |Input variables. -|||Examples: -|||inputs: - string_input -|||- id: full_string description: "A nice description" friendly: "Friendly variable display name" type: string -|||- id: int type: int -|||- id: choice_string type: string default: first items: - first - second -|||Escape script can be used in the default field to reference values from other dependencies: -|||inputs: - id: example default: $dependency.outputs.output_variable -|||Supported types are "string" (default), "int", "list" and the special types: "version", "project", "environment" and "deployment" which are automatically populated by Escape. -||| -|build_inputs|`[string]` [Variables](/docs/input-and-output-variables/) | -||| -|deploy_inputs|`[string]` [Variables](/docs/input-and-output-variables/) | -||| -|outputs|`[string]` [Variables](/docs/input-and-output-variables/) |Output variables (see input variables for documentation) -||| -|metadata|`{}` |Metadata key value pairs. -|||Escape script can be used as values, but note that the metadata is compiled at build time, so dependency inputs and outputs can't be referenced. -|||Example: -|||metadata: author: Fictional Character co_author: $dependency.metadata.author -||| -|includes|`[]string` |The files to includes in this release. The files don't have to exist at build time. Globbing patterns are supported. -||| -|errands|[Errands](/docs/errands/) |Errands. -|||Errands are scripts that can be run against the deployment of this release. The scripts receive the deployment's inputs and outputs as environment variables. -|||Examples: -|||errands: my-errand: description: "Run this errand to do something special" script: bin/my_errand.sh inputs: - extra_input -|||For information on the syntax of the input variables see the "inputs" field. -||| -|downloads|[Downloads](/docs/downloads/) | -||| -|templates|[Templates](/docs/templates/) | -||| -|build_templates|[Templates](/docs/templates/) | -||| -|deploy_templates|[Templates](/docs/templates/) | -||| -|path|`string`| -||| -|pre_build|`string`|A script to run before the build. -|||The script has access to the input variables (prepended with INPUT_) in the environment. -|||Examples: -|||Given the escape plan: -|||inputs: - test_input pre_build: pre_build.sh -|||We can get the value of the input variable in pre_build.sh: -|||echo $INPUT_test_input -||| -|build|`string`| -||| -|post_build|`string`|A script to run after the build. -|||The script has access to the input variables (prepended with INPUT_) and output variables (prepended with OUTPUT_) in the environment. -|||Examples: -|||Given the escape plan: -|||inputs: - test_input outputs: - test_output post_build: post_build.sh -|||We can get the value of the variables in post_build.sh: -|||echo $INPUT_test_input $OUTPUT_test_output -||| -|test|`string`| -||| -|pre_deploy|`string`| -||| -|deploy|`string`| -||| -|post_deploy|`string`| -||| -|smoke|`string`| -||| -|pre_destroy|`string`| -||| -|destroy|`string`| -||| -|post_destroy|`string`| -||| diff --git a/docs/generate_cmd_docs.go b/docs/generate_cmd_docs.go index 696d387..f276191 100644 --- a/docs/generate_cmd_docs.go +++ b/docs/generate_cmd_docs.go @@ -2,14 +2,17 @@ package main import ( "fmt" + "go/ast" + "go/parser" + "go/token" "io/ioutil" "log" + "os" "path" "path/filepath" "strings" "github.com/ankyra/escape/cmd" - "github.com/ankyra/escape/model/escape_plan" "github.com/spf13/cobra/doc" ) @@ -66,44 +69,125 @@ var typeLinks = map[string]string{ "Templates": "templates", } -func GeneratePlanDocs() { - result := planHeader - for _, field := range escape_plan.Fields { - typ := "" - types, ok := typeMap[field] - if !ok { - typ = "`string`" +type Page struct { + Name string + Slug string + SrcFile string + StructName string +} + +var Pages = map[string]Page{ + "escape plan": Page{"The Escape Plan", "escape-plan", "model/escape_plan/escape_plan.go", "EscapePlan"}, +} + +const PageHeader = `--- +date: 2017-11-11 00:00:00 +title: "%s" +slug: %s +type: "docs" +toc: true +--- + +%s + +Field | Type | Description +------|------|------------- +%s +` + +func GetYamlFieldFromTag(tag string) string { + for _, s := range strings.Split(tag, " ") { + s = strings.Trim(s, "`") + if strings.HasPrefix(s, "yaml:\"") { + s = s[6 : len(s)-1] + parts := strings.Split(s, ",") + return parts[0] } - for _, t := range types { - typLink, ok := typeLinks[t] - if ok { - typ += "[" + t + "](/docs/" + typLink + "/) " - } else { - typ += "`" + t + "` " + } + return "" +} + +func ParseType(expr ast.Expr) string { + switch t := expr.(type) { + case *ast.Ident: + return t.Name + case *ast.SelectorExpr: + return ParseType(t.X) + "." + t.Sel.String() // probably wrong + case *ast.ArrayType: + return "[" + ParseType(t.Elt) + "]" + case *ast.StarExpr: + return ParseType(t.X) + case *ast.MapType: + return "{" + ParseType(t.Key) + ":" + ParseType(t.Value) + "}" + case *ast.InterfaceType: + return "any" + default: + fmt.Printf("%T\n", t) + panic("type not supported in documentation: ") + } + return "" +} + +func StructTable(page Page, topLevelDoc string, s *ast.TypeSpec) string { + structType := s.Type.(*ast.StructType) + result := "" + for _, field := range structType.Fields.List { + tag := GetYamlFieldFromTag(field.Tag.Value) + typ := ParseType(field.Type) + result += "|" + tag + "|`" + typ + "`|" + doc := strings.TrimSpace(field.Doc.Text()) + if doc != "" { + for _, line := range strings.Split(doc, "\n") { + if strings.HasPrefix(line, "#") { + line = line[1:] + } + line = strings.TrimSpace(line) + if line == "" { + result += "\n|||" + } else { + result += line + " " + } } } - desc := string(escape_plan.GetDoc(field)) - desc = strings.TrimSpace(desc) - result += "|" + field + "|" + typ + "|" - for _, line := range strings.Split(desc, "\n") { - if strings.HasPrefix(line, "#") { - line = line[1:] - } - line = strings.TrimSpace(line) - if line == "" { - result += "\n|||" - } else { - result += line + " " + result += "\n" + } + return fmt.Sprintf(PageHeader, page.Name, page.Slug, topLevelDoc, result) +} + +func GenerateStructDocs(f *ast.File, page Page) string { + for _, decl := range f.Decls { + if gen, ok := decl.(*ast.GenDecl); ok && gen.Tok == token.TYPE { + for _, spec := range gen.Specs { + if s, ok := spec.(*ast.TypeSpec); ok { + switch s.Type.(type) { + case *ast.StructType: + if s.Name.String() == page.StructName { + return StructTable(page, gen.Doc.Text(), s) + } + } + } } } - result += "\n" } - if err := ioutil.WriteFile("./docs/escape-plan.md", []byte(result), 0644); err != nil { - panic(err) + return "" +} + +func GeneratePages() { + for _, page := range Pages { + fset := token.NewFileSet() + f, err := parser.ParseFile(fset, page.SrcFile, nil, parser.ParseComments) + if err != nil { + panic(err) + } + str := GenerateStructDocs(f, page) + filename := "docs/generated/" + page.Slug + ".md" + fmt.Println("Writing ", filename) + ioutil.WriteFile(filename, []byte(str), 0644) } } func main() { + os.Mkdir("docs/generated/", 0755) filePrepender := func(filename string) string { name := filepath.Base(filename) base := strings.TrimSuffix(name, path.Ext(name)) @@ -118,5 +202,5 @@ func main() { if err != nil { log.Fatal(err) } - GeneratePlanDocs() + GeneratePages() } diff --git a/scripts/build.sh b/scripts/build.sh index db9a49f..866af36 100755 --- a/scripts/build.sh +++ b/scripts/build.sh @@ -3,6 +3,7 @@ set -euf -o pipefail rm -rf docs/cmd/ +rm -rf docs/generated/ rm -rf vendor/github.com/ankyra/escape-core cp -r deps/_/escape-core/ vendor/github.com/ankyra/escape-core rm -rf vendor/github.com/ankyra/escape-core/vendor/ @@ -19,5 +20,5 @@ docker run --rm \ golang:1.9.0 bash -c "go build -v -o escape && mkdir -p docs/cmd && go run docs/generate_cmd_docs.go" docker cp src:/go/src/github.com/ankyra/escape/escape escape docker cp src:/go/src/github.com/ankyra/escape/docs/cmd docs/cmd -docker cp src:/go/src/github.com/ankyra/escape/docs/escape-plan.md docs/escape-plan.md +docker cp src:/go/src/github.com/ankyra/escape/docs/generated docs/generated docker rm src diff --git a/vendor/github.com/ankyra/escape-core/README.md b/vendor/github.com/ankyra/escape-core/README.md index 6f37320..ae6944f 100644 --- a/vendor/github.com/ankyra/escape-core/README.md +++ b/vendor/github.com/ankyra/escape-core/README.md @@ -1,9 +1,10 @@ # Escape Core -Core library containing datastructures for working with Release Metadata, State -and the Escape Scripting Language. +[![Build status](https://circleci.com/gh/ankyra/escape-core.svg?style=shield&circle-token=d7df85c68526fa4db52bf41ba48a05c52ae8f31d)](https://circleci.com/gh/ankyra/escape-core) [![Documentation](https://godoc.org/github.com/ankyra/escape-core?status.svg)](http://godoc.org/github.com/ankyra/escape-core) -Please see https://escape.ankyra.io for the full documentation. +Core library containing datastructures for working with Release Metadata, State and the Escape Scripting Language. + +Please see https://escape.ankyra.io/ for the full documentation. ## License diff --git a/vendor/github.com/ankyra/escape-core/build.sh b/vendor/github.com/ankyra/escape-core/build.sh index c3fc7fa..7f355a6 100755 --- a/vendor/github.com/ankyra/escape-core/build.sh +++ b/vendor/github.com/ankyra/escape-core/build.sh @@ -2,6 +2,7 @@ set -euf -o pipefail +rm -rf docs/generated/ docker rm src || true docker create -v /go/src/github.com/ankyra/ --name src golang:1.9.0 /bin/true docker cp "$PWD" src:/go/src/github.com/ankyra/tmp @@ -11,6 +12,7 @@ docker run --rm --volumes-from src \ docker run --rm \ --volumes-from src \ -w /go/src/github.com/ankyra/escape-core \ - golang:1.9.0 bash -c "go build && go run docs/generate_stdlib_docs.go" + golang:1.9.0 bash -c "go build && go run docs/generate_stdlib_docs.go && go run docs/generate_pages.go" +docker cp 'src:/go/src/github.com/ankyra/escape-core/docs/generated' docs/ docker rm src diff --git a/vendor/github.com/ankyra/escape-core/core.go b/vendor/github.com/ankyra/escape-core/core.go index 42ceec8..d0af596 100644 --- a/vendor/github.com/ankyra/escape-core/core.go +++ b/vendor/github.com/ankyra/escape-core/core.go @@ -1,4 +1,4 @@ package core const CurrentApiVersion = 8 -const CoreVersion = "0.8.22" +const CoreVersion = "0.8.25" diff --git a/vendor/github.com/ankyra/escape-core/dependency.go b/vendor/github.com/ankyra/escape-core/dependency.go index 608b2f2..62f4766 100644 --- a/vendor/github.com/ankyra/escape-core/dependency.go +++ b/vendor/github.com/ankyra/escape-core/dependency.go @@ -17,8 +17,9 @@ limitations under the License. package core import ( - "github.com/ankyra/escape-core/parsers" "strings" + + "github.com/ankyra/escape-core/parsers" ) type Dependency struct { diff --git a/vendor/github.com/ankyra/escape-core/dependency_config.go b/vendor/github.com/ankyra/escape-core/dependency_config.go index 83d7179..b2730d9 100644 --- a/vendor/github.com/ankyra/escape-core/dependency_config.go +++ b/vendor/github.com/ankyra/escape-core/dependency_config.go @@ -20,7 +20,18 @@ import ( "fmt" ) +// Dependencies are configured in the (`depends`)[/docs/escape-plan/#depends] +// field of the Escape plan. +// type DependencyConfig struct { + // The release id is required and is resolved at *build* time and then + // persisted in the release metadata ensuring that deployments always use + // the same versions. + // + // Examples: + // - To always use the latest version: `my-organisation/my-dependency-latest` + // - To always use version 0.1.1: `my-organisation/my-dependency-v0.1.1` + // - To always use the latest version in the 0.1 series: `my-organisation/my-dependency-v0.1.@` ReleaseId string `json:"release_id" yaml:"release_id"` BuildMapping map[string]interface{} `json:"build_mapping" yaml:"build_mapping"` DeployMapping map[string]interface{} `json:"deploy_mapping" yaml:"deploy_mapping"` diff --git a/vendor/github.com/ankyra/escape-core/docs/generate_pages.go b/vendor/github.com/ankyra/escape-core/docs/generate_pages.go new file mode 100644 index 0000000..f884bf3 --- /dev/null +++ b/vendor/github.com/ankyra/escape-core/docs/generate_pages.go @@ -0,0 +1,134 @@ +package main + +import ( + "fmt" + "go/ast" + "go/parser" + "go/token" + "io/ioutil" + "os" + "strings" +) + +type Page struct { + Name string + Slug string + SrcFile string + StructName string +} + +var Pages = map[string]Page{ + "consumer": Page{"Consumers", "providers-and-consumers", "consumer.go", "ConsumerConfig"}, + "depends": Page{"Dependencies", "dependencies", "dependency_config.go", "DependencyConfig"}, + "downloads": Page{"Downloads", "downloads", "download_config.go", "DownloadConfig"}, + "errands": Page{"Errands", "errands", "errand.go", "Errand"}, + "templates": Page{"Templates", "templates", "templates/templates.go", "Template"}, + "variables": Page{"Input and Output Variables", "input-and-output-variables", "variables/variable.go", "Variable"}, +} + +const PageHeader = `--- +date: 2017-11-11 00:00:00 +title: "%s" +slug: %s +type: "docs" +toc: true +--- + +%s + +Field | Type | Description +------|------|------------- +%s +` + +func GetJsonFieldFromTag(tag string) string { + for _, s := range strings.Split(tag, " ") { + s = strings.Trim(s, "`") + if strings.HasPrefix(s, "json:\"") { + s = s[6 : len(s)-1] + parts := strings.Split(s, ",") + return parts[0] + } + } + return "" +} + +func ParseType(expr ast.Expr) string { + switch t := expr.(type) { + case *ast.Ident: + return t.Name + case *ast.SelectorExpr: + return ParseType(t.X) + "." + t.Sel.String() // probably wrong + case *ast.ArrayType: + return "[" + ParseType(t.Elt) + "]" + case *ast.StarExpr: + return ParseType(t.X) + case *ast.MapType: + return "{" + ParseType(t.Key) + ":" + ParseType(t.Value) + "}" + case *ast.InterfaceType: + return "any" + default: + fmt.Printf("%T\n", t) + panic("type not supported in documentation: ") + } + return "" +} + +func StructTable(page Page, topLevelDoc string, s *ast.TypeSpec) string { + structType := s.Type.(*ast.StructType) + result := "" + for _, field := range structType.Fields.List { + tag := GetJsonFieldFromTag(field.Tag.Value) + typ := ParseType(field.Type) + result += "|" + tag + "|`" + typ + "`|" + doc := strings.TrimSpace(field.Doc.Text()) + if doc != "" { + for _, line := range strings.Split(doc, "\n") { + if strings.HasPrefix(line, "#") { + line = line[1:] + } + line = strings.TrimSpace(line) + if line == "" { + result += "\n|||" + } else { + result += line + " " + } + } + } + result += "\n" + } + return fmt.Sprintf(PageHeader, page.Name, page.Slug, topLevelDoc, result) +} + +func GenerateStructDocs(f *ast.File, page Page) string { + for _, decl := range f.Decls { + if gen, ok := decl.(*ast.GenDecl); ok && gen.Tok == token.TYPE { + for _, spec := range gen.Specs { + if s, ok := spec.(*ast.TypeSpec); ok { + switch s.Type.(type) { + case *ast.StructType: + if s.Name.String() == page.StructName { + return StructTable(page, gen.Doc.Text(), s) + } + } + } + } + } + } + return "" +} + +func main() { + os.Mkdir("docs/generated/", 0755) + for _, page := range Pages { + fset := token.NewFileSet() + f, err := parser.ParseFile(fset, page.SrcFile, nil, parser.ParseComments) + if err != nil { + panic(err) + } + str := GenerateStructDocs(f, page) + filename := "docs/generated/" + page.Slug + ".md" + fmt.Println("Writing ", filename) + ioutil.WriteFile(filename, []byte(str), 0644) + } +} diff --git a/vendor/github.com/ankyra/escape-core/docs/generate_stdlib_docs.go b/vendor/github.com/ankyra/escape-core/docs/generate_stdlib_docs.go index fe0df16..47a74d0 100644 --- a/vendor/github.com/ankyra/escape-core/docs/generate_stdlib_docs.go +++ b/vendor/github.com/ankyra/escape-core/docs/generate_stdlib_docs.go @@ -2,8 +2,10 @@ package main import ( "fmt" - "github.com/ankyra/escape-core/script" "io/ioutil" + "os" + + "github.com/ankyra/escape-core/script" ) type Type struct { @@ -59,5 +61,6 @@ Standard library functions for the [Escape Scripting Language](../scripting-lang s = fmt.Sprintf("%s## %s\n\n%s\n\n", s, sig, doc) } } - ioutil.WriteFile("docs/stdlib.md", []byte(s), 0644) + os.Mkdir("docs/generated/", 0755) + ioutil.WriteFile("docs/generated/stdlib.md", []byte(s), 0644) } diff --git a/vendor/github.com/ankyra/escape-core/docs/generated/dependencies.md b/vendor/github.com/ankyra/escape-core/docs/generated/dependencies.md new file mode 100644 index 0000000..a68a803 --- /dev/null +++ b/vendor/github.com/ankyra/escape-core/docs/generated/dependencies.md @@ -0,0 +1,21 @@ +--- +date: 2017-11-11 00:00:00 +title: "Dependencies" +slug: dependencies +type: "docs" +toc: true +--- + +Dependencies are configured in the (`depends`)[/docs/escape-plan/#depends] +field of the Escape plan. + + +Field | Type | Description +------|------|------------- +|release_id|`string`|The release id is required and is resolved at *build* time and then persisted in the release metadata ensuring that deployments always use the same versions. +|||Examples: - To always use the latest version: `my-organisation/my-dependency-latest` - To always use version 0.1.1: `my-organisation/my-dependency-v0.1.1` - To always use the latest version in the 0.1 series: `my-organisation/my-dependency-v0.1.@` +|build_mapping|`{string:any}`| +|deploy_mapping|`{string:any}`| +|consumes|`{string:string}`| +|scopes|`[string]`| + diff --git a/vendor/github.com/ankyra/escape-core/docs/generated/downloads.md b/vendor/github.com/ankyra/escape-core/docs/generated/downloads.md new file mode 100644 index 0000000..9b40040 --- /dev/null +++ b/vendor/github.com/ankyra/escape-core/docs/generated/downloads.md @@ -0,0 +1,27 @@ +--- +date: 2017-11-11 00:00:00 +title: "Downloads" +slug: downloads +type: "docs" +toc: true +--- + +Downloading files at build or deployment time is one of those common tasks +that Escape tries to cover. + +Downloads are configured in the Escape Plan under the +(`downloads`)[/docs/escape-plan/#downloads] field. + + +Field | Type | Description +------|------|------------- +|url|`string`|The URL to download from. This field is required. +|||Example: `https://www.google.com/` +|dest|`string`|The destination path. +|overwrite|`bool`|Overwrite the destination path if it already exists. +|if_not_exists|`[string]`|Only perform this download if none of the paths in this list exist. Supports glob patterns (for example: `"*.zip"`) +|unpack|`bool`|Should Escape try and unpack the destination path after download? Supported extensions: `.zip`, `.tgz`, `.tar.gz`, `.tar`. +|platform|`string`|Only perform this download if the platform matches this value. Can be used to do platform dependent builds. +|arch|`string`|Only perform this download if the architecture matches this string. Can be used to do architecture dependent builds. +|scopes|`[string]`|A list of scopes (`build`, `deploy`) that defines during which stage(s) this download should be performed. + diff --git a/vendor/github.com/ankyra/escape-core/docs/generated/errands.md b/vendor/github.com/ankyra/escape-core/docs/generated/errands.md new file mode 100644 index 0000000..307652a --- /dev/null +++ b/vendor/github.com/ankyra/escape-core/docs/generated/errands.md @@ -0,0 +1,30 @@ +--- +date: 2017-11-11 00:00:00 +title: "Errands" +slug: errands +type: "docs" +toc: true +--- + +Errands are an Escape mechanism that make it easy to run operational and +publication tasks against deployed packages. They can be used to implement +backup procedures, user management, scalability controls, binary +publications, etc. Errands are a good idea whenever a task needs to be aware +of Environments. + +Errands are configured in the Escape Plan under the +(`errands`)[/docs/escape-plan/#errands] field. + +You can inspect and run Errands using the (`escape +errands`)[/docs/escape_errands/] command. + + +Field | Type | Description +------|------|------------- +|name|`string`|The name of the errand. This field is required. +|description|`string`|An optional description of the errand. +|script|`string`|The location of the script performing the actual work. +|||The script has access to the deployment inputs and outputs as enviroment variables. For example: an input with `"id": "input_variable"` will be accessible as `INPUT_input_variable`; and an output with `"id": "output_variable"` as `OUTPUT_output_variable`. +|||For example: `my-scripts/backup.sh` +|inputs|`[variables.Variable]`|A list of (Variables)[/docs/input-and-output-variables/]. The values will be made available to the `script` (along with the regular deployment inputs and outputs) as environment variables. For example: a variable with `"id": "input_variable"` will be accessible as environment variable `INPUT_input_variable` + diff --git a/vendor/github.com/ankyra/escape-core/docs/generated/input-and-output-variables.md b/vendor/github.com/ankyra/escape-core/docs/generated/input-and-output-variables.md new file mode 100644 index 0000000..b00c31b --- /dev/null +++ b/vendor/github.com/ankyra/escape-core/docs/generated/input-and-output-variables.md @@ -0,0 +1,33 @@ +--- +date: 2017-11-11 00:00:00 +title: "Input and Output Variables" +slug: input-and-output-variables +type: "docs" +toc: true +--- + +Variables can be used to defined inputs and outputs for the build and +deployment stages. They can also be used to make [Errands](/docs/errands/) +configurable. + +Variables are strongly typed, which is checked at both build and deploy +time. A task can't succeed if the required variables have not been +configured correctly. + + +Field | Type | Description +------|------|------------- +|id|`string`|A unique name for this variable. Required field. +|type|`string`|The variable type. Before executing any steps Escape will make sure that all the values match the types that are set on the variables. +|||One of: `string`, `list`, `integer`, `bool`. +|||Default: `string` +|default|`any`|A default value for this variable. This value will be used if no value has been specified by the user. +|description|`string`|A description of the variable. +|friendly|`string`|A friendly name for this variable for presentational purposes only. +|visible|`bool`|Control whether or not this variable should be visible when deploying interactively. In other words: should the user be asked to input this value? It only really makes sense to set this to `true` if there a `default` is set. +|options|`{string:any}`|Options that put more constraints on the type. +|sensitive|`bool`|Is this sensitive data? +|items|`any`|If set, this should contain all the valid values for this variable. +|eval_before_dependencies|`bool`|Should the variables be evaluated before the dependencies are deployed? +|scopes|`[string]`|A list of scopes (`build`, `deploy`) that defines during which stage(s) this variable should be active. You wouldn't usually use this field directly, but use something like [`build_inputs`](/docs/escape-plan/#build_inputs) or [`deploy_inputs`](/docs/escape-plan/#deploy_inputs), which usually express intent better. + diff --git a/vendor/github.com/ankyra/escape-core/docs/generated/providers-and-consumers.md b/vendor/github.com/ankyra/escape-core/docs/generated/providers-and-consumers.md new file mode 100644 index 0000000..b091668 --- /dev/null +++ b/vendor/github.com/ankyra/escape-core/docs/generated/providers-and-consumers.md @@ -0,0 +1,15 @@ +--- +date: 2017-11-11 00:00:00 +title: "Consumers" +slug: providers-and-consumers +type: "docs" +toc: true +--- + + + +Field | Type | Description +------|------|------------- +|name|`string`| +|scopes|`[string]`| + diff --git a/vendor/github.com/ankyra/escape-core/docs/stdlib.md b/vendor/github.com/ankyra/escape-core/docs/generated/stdlib.md similarity index 100% rename from vendor/github.com/ankyra/escape-core/docs/stdlib.md rename to vendor/github.com/ankyra/escape-core/docs/generated/stdlib.md index 07dc30d..2ab35ac 100644 --- a/vendor/github.com/ankyra/escape-core/docs/stdlib.md +++ b/vendor/github.com/ankyra/escape-core/docs/generated/stdlib.md @@ -63,14 +63,34 @@ Slice a list. Usually accessed implicitly using slice syntax (eg. `list[0:5]`) Replace returns a copy of the string s with the first n non-overlapping instances of old replaced by new. If old is empty, it matches at the beginning of the string and after each UTF-8 sequence, yielding up to k+1 replacements for a k-rune string. If n < 0, there is no limit on the number of replacements. -## lower(v :: string) +## track_patch_version() -Returns a copy of the string v with all Unicode characters mapped to their lower case +Track patch version + +## concat(v1 :: string, v2 :: string, ...) + +Concatate stringable arguments + +## upper(v :: string) + +Returns a copy of the string v with all Unicode characters mapped to their upper case + +## title(v :: string) + +Returns a copy of the string v with all Unicode characters mapped to their title case ## read_file() Read the contents of a file +## track_version() + +Track version + +## base64_decode() + +Decode string from base64 + ## track_major_version() Track major version @@ -79,39 +99,19 @@ Track major version Track minor version -## track_version() +## lower(v :: string) -Track version +Returns a copy of the string v with all Unicode characters mapped to their lower case ## split(sep :: string) Split slices s into all substrings separated by sep and returns a slice of the substrings between those separators. If sep is empty, Split splits after each UTF-8 sequence. -## title(v :: string) - -Returns a copy of the string v with all Unicode characters mapped to their title case - ## base64_encode() Encode string to base64 -## upper(v :: string) - -Returns a copy of the string v with all Unicode characters mapped to their upper case - -## base64_decode() - -Decode string from base64 - ## trim() Returns a slice of the string s, with all leading and trailing white space removed, as defined by Unicode. -## track_patch_version() - -Track patch version - -## concat(v1 :: string, v2 :: string, ...) - -Concatate stringable arguments - diff --git a/vendor/github.com/ankyra/escape-core/docs/generated/templates.md b/vendor/github.com/ankyra/escape-core/docs/generated/templates.md new file mode 100644 index 0000000..73e4fd2 --- /dev/null +++ b/vendor/github.com/ankyra/escape-core/docs/generated/templates.md @@ -0,0 +1,24 @@ +--- +date: 2017-11-11 00:00:00 +title: "Templates" +slug: templates +type: "docs" +toc: true +--- + +Escape provides the Mustache templating language and integrates it with the +package's (Variables)[/docs/input-and-output-variables/], making for a quick +and easy way to render files at either build or deploy time. + +Templates are configured in the Escape Plan under the +(`templates`)[/docs/escape-plan/#templates] field. + + +Field | Type | Description +------|------|------------- +|file|`string`|The file containing the template. This field is required. +|target|`string`|The target location for the rendered template. If the source location specified in `file` has the `.tpl` extension this `target` will default to source location minus that extension. +|||For example: if `file` is `"hello.txt.tpl"` then the default value for target will be `"hello.txt"` +|scopes|`[string]`|A list of scopes (`build`, `deploy`) that defines during which stage(s) the template should be rendered. +|mapping|`{string:any}`|This mapping can be used to relate template variables to Escape variables. + diff --git a/vendor/github.com/ankyra/escape-core/docs/scripting_language.md b/vendor/github.com/ankyra/escape-core/docs/scripting_language.md deleted file mode 100644 index fbb02b7..0000000 --- a/vendor/github.com/ankyra/escape-core/docs/scripting_language.md +++ /dev/null @@ -1,382 +0,0 @@ ---- -title: "Scripting Language" -slug: scripting-language -type: "docs" -toc: true ---- - -The scripting language is a tiny language that is meant to help with wiring up -inputs and outputs. It is by no means a fully fledged language and it's not its -goal to become one either. More complicated logic should be pushed into the -build scripts, where it can be properly tested. - - -# Examples - -## Using provider outputs as defaults - -If we have this provider: - -``` -id: aws -version: 0.1.@ -provides: -- aws - -outputs: -- id: default_zone - default: us-east -``` - -We can use its `default_zone` output variable as an input for our unit: - -``` -id: my-unit -version: 0.1.@ - -consumes: -- aws - -inputs: -- id: zone - default: $aws.outputs.default_zone -``` - -## Propagating Dependency Metadata - -``` -id: my-unit -version: 0.1.@ - -depends: -- my-dependency as dep - -metadata: - author: $dep.metadata.author - some_other_key: $dep.metadata.some_other_key -``` - -## Configuring dependencies - -``` -id: my-unit -version: 0.1.@ - -inputs: -- input_variable - -depends: -- id: my-dependency - mapping: - dependency_input_variable: $this.inputs.input_variable -``` - -Note that this is only necessary if you want to rename or modify the inputs to -the dependency, as the parent's inputs are mapped to the dependency by default. - -## Exposing inputs as outputs - -``` -id: my-unit -version: 0.1.@ - -inputs: -- input_variable - -outputs: -- id: output_variable - default: $this.inputs.input_variable -``` - -This can be a handy pattern for providers, where the user selects or enters -something and the unit provides it to the environment: - -``` -id: my-provider -version: 0.1.@ - -provides: -- zone - -inputs: -- id: zone - description: Please select a zone. - items: - - europe-west1-b - - europe-west1-c - - europe-west1-d - -outputs: -- id: zone - default: $this.inputs.zone -``` - -## Tracking a Dependency's Version - -If we have a dependency: - -``` -id: my-dependency -version: 0.1.@ -``` -We can use the same versioning scheme in the parent: - -``` -id: my-project/my-application -depends: -- my-dependency as dep -version: $dep.version.track_minor_version() -``` - -Which is short for this beauty: - -``` -version: $dep.version.split(".")[:2].join(".").concat(".@") -``` - -Also see: `track_major_version`, `track_minor_version`, `track_patch_version` -in the [Standard Library Reference](../scripting-language-stdlib/) - - -## Configuring Templates - -``` -id: my-project/my-application -version: 0.1.@ -inputs: -- input_variable - -templates: -- file: template.txt.tpl - mapping: - title: $this.inputs.input_variable -``` - -# Syntax - -## Literals - -At the moment only integer and string literals are supported: - -``` -123 --123 -"string value" -``` - -## Dictionary lookups - -A dictionary lookup is performed using the `.` operator. Lookups in `$`, the -global context, are a special case where the `.` should be skipped: - -``` -$this.inputs.input_variable -``` - -## Indexing and slicing - -Indexing a list uses familiar syntax: - -``` -$this.inputs.list_input[0] -``` - -And slicing is also supported: - -``` -$this.inputs.list_input[0:2] -$this.inputs.list_input[1:] -$this.inputs.list_input[:-1] -``` - -## Function calls - -A function is usually called on an object: - -``` -$this.inputs.variable.upper() -$this.inputs.variable.split(",") -``` - -Functions can also be called directly (although the manner in which this is -done is likely to change), which can be handy when you don't have a reference -to an object: - -``` -$__upper("my string") -$__split("my:string", ":") -$__timestamp() -``` - -For a full overview of supported functions see the [Standard Library -Reference](../scripting-language-stdlib/). - - -# Context - -`$this` always refers to the current unit and whether we're compiling the -Escape plan, building or deploying, the following fields will always be -available: - -``` -$this.id # e.g. "project/unit-v1.0.0" -$this.name # e.g. "unit" -$this.release # e.g. "unit-v1.0.0" -$this.versionless_release # e.g. "project/unit" -$this.version # e.g. "1.0.0" - -$this.branch # e.g. "master" -$this.revision # e.g. "abcdefff12312312312123" -$this.repository # e.g. "github.com/ankyra/escape-core" -``` - -These variables are generally used in templates; we could tag virtual machines, -docker images or Kubernetes deployments with this information for example. - -Besides these variables, we also have access to: - -``` -$this.description # e.g. "Escape plan description" -$this.metadata.key # e.g. "Escape plan metadata value" -``` - -This is also true for all of our dependencies. Given: - -``` -id: unit -version: 0.1.@ -depends: -- my-dependency-latest as dep -``` - -We can: - -``` -$dep.id -$dep.name -$dep.release -``` - -etc. - -## Stateful Context - -When we're building or deploying we also have access to the state. - -``` -$this.inputs # e.g. {"input_variable": "value"} -$this.outputs # e.g. {"output_variable": "value"} -$this.project # e.g. "project" -$this.environment # e.g. "ci" -$this.deployment # e.g. "my-deployment" -``` - -Note that the project variable does not refer to the unit's project, but to the -state's project. This will probably change, because it's confusing. - -Again, these variables are also available for our dependencies (unless we're -evaluating variables and `eval_before_dependencies` is set to true). - -``` -$deps.inputs -$deps.outputs -$deps.project # same as $this.project -$deps.environment # same as $this.environment -$deps.deployment # e.g. "my-project/dependency" -``` - -# Enabled Fields - -The language is only enabled in a few fields of the Escape plan so that common -tasks can be handled. - -## Version - -The version field can be scripted to enabled custom versioning schemes and -dependency version tracking. No state information will be available in the -context when this field is compiled, so (dependency) inputs and outputs can't -be referenced. - -Examples: - -Follow a dependency one-to-one: - -``` -version: $dep.version -``` - -Follow a minor version: - -``` -version: $dep.version.track_minor_version() -``` - -## Metadata - -The metadata field can be scripted to propagate metadata from dependencies. No -state information will be available in the context when this field is compiled, -so (dependency) inputs and outputs can't be referenced. - -``` -metadata: - website: $dep.metadata.website -``` - -## Variables - -Most importantly the language can be used in variable definition blocks. Both -the `default` and the `items` field can be scripted. - -``` -inputs: -- id: input_variable - default: $this.version - -outputs: -- id: output_variable - default: $this.inputs.input_variable -``` - -The `inputs` field is a special case, because it generally won't have access to -the full state, because most input variables are evaluated before its -dependencies are run. This can however be configured using the -`eval_before_dependencies` setting, which gives it access to dependency -outputs: - -``` -inputs: -- id: input_variable - default: $dep.outputs.image - eval_before_dependencies: false -``` - -## Template Mapping - -The values in the `mapping` field of a template are evaluated in a stateful -context, which gives full access to inputs and outputs: - -``` -templates: -- file: kubespec.yml.tpl - mapping: - image: $dep.outputs.docker_image -``` - -## Dependency Mapping - -The values in the `mapping` field of a dependency can be scripted: - -``` -inputs: -- input_variable - -depends: -- id: my-dependency-latest - mapping: - image: $this.inputs.input_variable -``` - - -# See also - -* [Standard Library Reference](../scripting-language-stdlib/) diff --git a/vendor/github.com/ankyra/escape-core/download_config.go b/vendor/github.com/ankyra/escape-core/download_config.go index 7cd281d..7f1ee81 100644 --- a/vendor/github.com/ankyra/escape-core/download_config.go +++ b/vendor/github.com/ankyra/escape-core/download_config.go @@ -21,15 +21,43 @@ import ( "net/url" ) +// Downloading files at build or deployment time is one of those common tasks +// that Escape tries to cover. +// +// Downloads are configured in the Escape Plan under the +// (`downloads`)[/docs/escape-plan/#downloads] field. +// type DownloadConfig struct { - URL string `json:"url"` - Dest string `json:"dest"` - OverwriteExistingDest bool `json:"overwrite" yaml:"overwrite"` - IfNotExists []string `json:"if_not_exists" yaml:"if_not_exists"` - Unpack bool `json:"unpack"` - Platform string `json:"platform"` - Arch string `json:"arch"` - Scopes []string `json:"scopes" yaml:"scopes"` + // The URL to download from. This field is required. + // + // Example: `https://www.google.com/` + URL string `json:"url"` + + // The destination path. + Dest string `json:"dest"` + + // Overwrite the destination path if it already exists. + OverwriteExistingDest bool `json:"overwrite" yaml:"overwrite"` + + // Only perform this download if none of the paths in this list exist. + // Supports glob patterns (for example: `"*.zip"`) + IfNotExists []string `json:"if_not_exists" yaml:"if_not_exists"` + + // Should Escape try and unpack the destination path after download? + // Supported extensions: `.zip`, `.tgz`, `.tar.gz`, `.tar`. + Unpack bool `json:"unpack"` + + // Only perform this download if the platform matches this value. + // Can be used to do platform dependent builds. + Platform string `json:"platform"` + + // Only perform this download if the architecture matches this string. + // Can be used to do architecture dependent builds. + Arch string `json:"arch"` + + // A list of scopes (`build`, `deploy`) that defines during which stage(s) + // this download should be performed. + Scopes []string `json:"scopes" yaml:"scopes"` } func NewDownloadConfig(url string) *DownloadConfig { diff --git a/vendor/github.com/ankyra/escape-core/errand.go b/vendor/github.com/ankyra/escape-core/errand.go index def5ecd..c36c4cc 100644 --- a/vendor/github.com/ankyra/escape-core/errand.go +++ b/vendor/github.com/ankyra/escape-core/errand.go @@ -23,11 +23,41 @@ import ( "github.com/ankyra/escape-core/variables" ) +// Errands are an Escape mechanism that make it easy to run operational and +// publication tasks against deployed packages. They can be used to implement +// backup procedures, user management, scalability controls, binary +// publications, etc. Errands are a good idea whenever a task needs to be aware +// of Environments. +// +// Errands are configured in the Escape Plan under the +// (`errands`)[/docs/escape-plan/#errands] field. +// +// You can inspect and run Errands using the (`escape +// errands`)[/docs/escape_errands/] command. +// type Errand struct { - Name string `json:"name"` - Description string `json:"description"` - Script string `json:"script"` - Inputs []*variables.Variable `json:"inputs"` + // The name of the errand. This field is required. + Name string `json:"name"` + + // An optional description of the errand. + Description string `json:"description"` + + // The location of the script performing the actual work. + // + // The script has access to the deployment inputs and outputs as enviroment + // variables. For example: an input with `"id": "input_variable"` will be + // accessible as `INPUT_input_variable`; and an output with `"id": + // "output_variable"` as `OUTPUT_output_variable`. + // + // For example: `my-scripts/backup.sh` + Script string `json:"script"` + + // A list of (Variables)[/docs/input-and-output-variables/]. The values + // will be made available to the `script` (along with the regular + // deployment inputs and outputs) as environment variables. For example: a + // variable with `"id": "input_variable"` will be accessible as environment + // variable `INPUT_input_variable` + Inputs []*variables.Variable `json:"inputs"` } func NewErrand(name, script, description string) *Errand { diff --git a/vendor/github.com/ankyra/escape-core/release.json b/vendor/github.com/ankyra/escape-core/release.json index 4de388f..d61d3ca 100644 --- a/vendor/github.com/ankyra/escape-core/release.json +++ b/vendor/github.com/ankyra/escape-core/release.json @@ -1,27 +1,33 @@ { "api_version": 8, - "built_with_core_version": "0.8.0", - "built_with_escape_version": "0.19.0", + "built_with_core_version": "0.8.22", + "built_with_escape_version": "0.19.5", "description": "Core library containing datastructures for working with Release Metadata, State and the Escape Scripting Language.\nPlease see https://escape.ankyra.io for the full documentation.", "files": { "LICENSE": "2a944942e1496af1886903d274dedb13", - "README.md": "ad73b9029c0b11da5ed490238805c502", - "build.sh": "b6d3c274085e09f3c6e19160ca767301", + "README.md": "157ef9ed335beff9ccd5d85185921004", + "build.sh": "f90bc77595918535d7e064b202aa6997", "consumer.go": "c81742d72604e3512d69017eb07cc7ec", "consumer_test.go": "3ff946e134efa5165c73db7476ffbbb4", - "core.go": "d436cb0d6226a744ec2202fc7a2faced", + "core.go": "907d668ed81296a5853570e82528f063", "core.go.tpl": "4099a7b2c6c7798799ea2819f8cf5c27", - "dependency.go": "c2fad1fb08026574389ca4ed44be50e1", - "dependency_config.go": "9ab20039859c0b7f6bd2e90e2e1a06a6", + "dependency.go": "b97d96c09ee4862bab159c058c25d545", + "dependency_config.go": "c880e59aca14c599ec5d68ef0a763a4f", "dependency_config_test.go": "86bdbfe3d8f37329845277e69ecee32c", "dependency_test.go": "141917507d043eed403cfc1493cf32fd", "diff.go": "d26a23ae2e9a3fe2d3e98358b9ae4cef", "diff_test.go": "b8ba4f49d00eec3b6668a02f96115825", - "docs/generate_stdlib_docs.go": "15e02f0835b07edb0ecd7e60d6d3f040", - "docs/scripting_language.md": "79ffa91ba9dad432b9c3810b474036d8", - "docs/stdlib.md": "339408b92f1beb216826054e74d6a44b", - "download_config.go": "18861e9a54cd25755edb582ce260fdb3", - "errand.go": "22d56084cdd5088790a285196cf909b6", + "docs/generate_pages.go": "b862db7033fc6d329e108a9c0fbc6ac0", + "docs/generate_stdlib_docs.go": "672a40c6b105e634e880d5447d5b30f0", + "docs/generated/dependencies.md": "18c99a538a4288cee8b8c06039e2b16d", + "docs/generated/downloads.md": "ba6502b591062da33ba4c7f9f690fdb3", + "docs/generated/errands.md": "4c04cce179029b6e3ec6e3c08215c6da", + "docs/generated/input-and-output-variables.md": "aa41042edf77c3916408aec44f9c9995", + "docs/generated/providers-and-consumers.md": "5ce151135ff1227ccb729a1e61c62745", + "docs/generated/stdlib.md": "67513088f93530f3070a97adc1040c74", + "docs/generated/templates.md": "a8589fea8c4b3678e1d73da9496c793b", + "download_config.go": "e7bc55c664eda6853ab0b8a6b5ed961c", + "errand.go": "eb2246ba3efaf820823ac2608fa6910f", "errand_test.go": "2024729f8621ada8cd3699ec18d5d934", "metadata.go": "5ed0d016e1fef97e5bbba22efefc9c9b", "metadata_test.go": "d10f1eaf62e994e8d931a7449b625c16", @@ -44,8 +50,6 @@ "script/parser_test.go": "df394ebf74087d2f7ac45b18396261cf", "script/script.go": "dab208818ad187ca5b639f126d3df95e", "script/type.go": "c4dbdef86741d5936047b7f98c8e57db", - "state/.deployment.go.swp": "f2fa23b5e877a355053c657a5d1f5009", - "state/.deployment_test.go.swp": "3fff2b3eb20dd0c6a88c6713a4434b67", "state/dag.go": "33fb72ffea5d64fcfed307a2560d52f0", "state/dag_test.go": "585e69f67cba945c4f9a7c03b150397b", "state/deployment.go": "0e530457c73e7babe7ae0bdc1c94bb1e", @@ -61,10 +65,10 @@ "state/status_test.go": "5b66f665d38e572b9da2a4a28519d5d1", "state/testdata/project.json": "6a60c9206d05ae6ead95fc07efcbd174", "state/testdata/project_script.json": "11012c64310f65b862d917df6007f1d4", - "templates/templates.go": "d6437140272fd021068af2e17e209165", + "templates/templates.go": "a8f72f7632fe3add8af5edf7ad666b39", "templates/templates_test.go": "fae5a964597f811a079dd5eb35574404", "templates/testdata/helloworld.mustache": "73106d5bfa7b0736ebcf86b8ba7d0820", - "test.sh": "e507ac0c3d2aa7d897f5360a80f13079", + "test.sh": "d958d2697b1268c1975c2cd12bc66bf0", "util/errors.go": "bfe0c2898e5502afae76b9b8bca85e63", "util/log_consumer.go": "0c48f3364ce07040b0c0221a715a9554", "util/log_entry.go": "90c518ce0d4eee951880d06170ef03c9", @@ -72,7 +76,7 @@ "util/path.go": "b256d866ccb2c4a155282f1e56c65105", "util/process.go": "cef1e12dfcdd4a59c464239e70209275", "util/value.go": "7bc9d4f0435b94d3cfa646e04dafbcf9", - "variables/variable.go": "ec09b6495a2cf90ae1bc399073b0d614", + "variables/variable.go": "caaf0cc3ae882761bbb30f7eb04bf8a9", "variables/variable_test.go": "c771e4af61350db4ca30aa53a262681b", "variables/variable_types/bool.go": "86a7d62e5c0fa851ed6998df3b3c3d4c", "variables/variable_types/bool_test.go": "313fb37e9f9461b132bf7141d7cba66d", @@ -133,13 +137,13 @@ "name": "escape-core", "repository": "git@github.com:ankyra/escape-core.git", "branch": "master", - "git_revision": "3ae6770558f7698c39859dc131078c2bcc36c47c", - "revision_message": "Add GetRootDeploymentStage to Deployment", + "git_revision": "92acecf1bf98b97a0f642e982d339445bbab9932", + "revision_message": "Add documentation to DependencyConfig, DownloadConfig, Errand, Template and Variable structs.", "revision_author": "Bart Spaans \u003cbart.spaans@gmail.com\u003e", "metadata": { "release_metadata_api_version": "8" }, - "version": "0.8.22", + "version": "0.8.25", "consumes": [], "downloads": null, "depends": [], diff --git a/vendor/github.com/ankyra/escape-core/templates/templates.go b/vendor/github.com/ankyra/escape-core/templates/templates.go index 4fe4852..ce45437 100644 --- a/vendor/github.com/ankyra/escape-core/templates/templates.go +++ b/vendor/github.com/ankyra/escape-core/templates/templates.go @@ -25,10 +25,30 @@ import ( "github.com/cbroglie/mustache" ) +// Escape provides the Mustache templating language and integrates it with the +// package's (Variables)[/docs/input-and-output-variables/], making for a quick +// and easy way to render files at either build or deploy time. +// +// Templates are configured in the Escape Plan under the +// (`templates`)[/docs/escape-plan/#templates] field. +// type Template struct { - File string `json:"file"` - Target string `json:"target"` - Scopes []string `json:"scopes"` + // The file containing the template. This field is required. + File string `json:"file"` + + // The target location for the rendered template. If the source location + // specified in `file` has the `.tpl` extension this `target` will default + // to source location minus that extension. + // + // For example: if `file` is `"hello.txt.tpl"` then the default value for + // target will be `"hello.txt"` + Target string `json:"target"` + + // A list of scopes (`build`, `deploy`) that defines during which stage(s) + // the template should be rendered. + Scopes []string `json:"scopes"` + + // This mapping can be used to relate template variables to Escape variables. Mapping map[string]interface{} `json:"mapping"` } diff --git a/vendor/github.com/ankyra/escape-core/test.sh b/vendor/github.com/ankyra/escape-core/test.sh index 09cd1fc..1a3a34b 100755 --- a/vendor/github.com/ankyra/escape-core/test.sh +++ b/vendor/github.com/ankyra/escape-core/test.sh @@ -11,5 +11,5 @@ docker run --rm --volumes-from src \ docker run --rm \ --volumes-from src \ -w /go/src/github.com/ankyra/escape-core \ - golang:1.9.0 bash -c "go test -cover -v \$(/usr/local/go/bin/go list ./... )" + golang:1.9.0 bash -c "go test -cover -v \$(/usr/local/go/bin/go list ./... | grep -v docs )" diff --git a/vendor/github.com/ankyra/escape-core/variables/variable.go b/vendor/github.com/ankyra/escape-core/variables/variable.go index c175d7c..d665e0c 100644 --- a/vendor/github.com/ankyra/escape-core/variables/variable.go +++ b/vendor/github.com/ankyra/escape-core/variables/variable.go @@ -28,18 +28,61 @@ import ( "gopkg.in/yaml.v2" ) +// Variables can be used to defined inputs and outputs for the build and +// deployment stages. They can also be used to make [Errands](/docs/errands/) +// configurable. +// +// Variables are strongly typed, which is checked at both build and deploy +// time. A task can't succeed if the required variables have not been +// configured correctly. +// type Variable struct { - Id string `json:"id"` - Type string `json:"type"` - Default interface{} `json:"default,omitempty"` - Description string `json:"description,omitempty"` - Friendly string `json:"friendly,omitempty"` - Visible bool `json:"visible"` - Options map[string]interface{} `json:"options,omitempty"` - Sensitive bool `json:"sensitive,omitempty"` - Items interface{} `json:"items"` - EvalBeforeDependencies bool `json:"eval_before_dependencies,omitempty"` - Scopes []string `json:"scopes"` + // A unique name for this variable. Required field. + Id string `json:"id"` + + // The variable type. Before executing any steps Escape will make sure that + // all the values match the types that are set on the variables. + // + // One of: `string`, `list`, `integer`, `bool`. + // + // Default: `string` + Type string `json:"type"` + + // A default value for this variable. This value will be used if no value + // has been specified by the user. + Default interface{} `json:"default,omitempty"` + + // A description of the variable. + Description string `json:"description,omitempty"` + + // A friendly name for this variable for presentational purposes only. + Friendly string `json:"friendly,omitempty"` + + // Control whether or not this variable should be visible when deploying + // interactively. In other words: should the user be asked to input this + // value? It only really makes sense to set this to `true` if there a + // `default` is set. + Visible bool `json:"visible"` + + // Options that put more constraints on the type. + Options map[string]interface{} `json:"options,omitempty"` + + // Is this sensitive data? + Sensitive bool `json:"sensitive,omitempty"` + + // If set, this should contain all the valid values for this variable. + Items interface{} `json:"items"` + + // Should the variables be evaluated before the dependencies are deployed? + EvalBeforeDependencies bool `json:"eval_before_dependencies,omitempty"` + + // A list of scopes (`build`, `deploy`) that defines during which stage(s) + // this variable should be active. You wouldn't usually use this field + // directly, but use something like + // [`build_inputs`](/docs/escape-plan/#build_inputs) or + // [`deploy_inputs`](/docs/escape-plan/#deploy_inputs), which usually + // express intent better. + Scopes []string `json:"scopes"` } type UntypedVariable map[interface{}]interface{}