From 1b5a431ec5d80193f21841f8d6885c935b9f3227 Mon Sep 17 00:00:00 2001 From: Jahvon Dockery Date: Tue, 24 Dec 2024 15:54:39 -0500 Subject: [PATCH] docs: add more details to schema and cli --- cmd/internal/store.go | 13 ++++++----- docs/_sidebar.md | 1 + docs/cli/README.md | 2 +- docs/cli/flow_store.md | 12 ++++++---- docs/cli/flow_store_clear.md | 4 ++-- docs/cli/flow_store_get.md | 4 ++-- docs/cli/flow_store_set.md | 4 ++-- docs/guide/_sidebar.md | 3 +++ docs/schemas/flowfile_schema.json | 4 ++-- docs/types/flowfile.md | 4 ++-- types/executable/executable.gen.go | 30 +++++++++++++++++++++++-- types/executable/executable_schema.yaml | 22 ++++++++++++++++-- 12 files changed, 79 insertions(+), 24 deletions(-) diff --git a/cmd/internal/store.go b/cmd/internal/store.go index 7c48989..09fb5bf 100644 --- a/cmd/internal/store.go +++ b/cmd/internal/store.go @@ -16,8 +16,11 @@ import ( func RegisterStoreCmd(ctx *context.Context, rootCmd *cobra.Command) { subCmd := &cobra.Command{ Use: "store", - Short: "Manage the data store.", - Args: cobra.NoArgs, + Short: "Manage the data store for persisting key-value data.", + Long: "Manage the flow data store - a key-value store that persists data within and across executable runs. " + + "Values set outside executables persist globally, while values set within executables persist only for " + + "that execution scope.", + Args: cobra.NoArgs, } registerStoreSetCmd(ctx, subCmd) registerStoreGetCmd(ctx, subCmd) @@ -28,7 +31,7 @@ func RegisterStoreCmd(ctx *context.Context, rootCmd *cobra.Command) { func registerStoreSetCmd(ctx *context.Context, rootCmd *cobra.Command) { subCmd := &cobra.Command{ Use: "set KEY [VALUE]", - Short: "Set a key-value pair in the data store.", + Short: "Set a key-value pair in the store.", Long: dataStoreDescription + "This will overwrite any existing value for the key.", Args: cobra.MinimumNArgs(1), Run: func(cmd *cobra.Command, args []string) { @@ -89,7 +92,7 @@ func registerStoreGetCmd(ctx *context.Context, rootCmd *cobra.Command) { subCmd := &cobra.Command{ Use: "get KEY", Aliases: []string{"view"}, - Short: "Get a value from the data store.", + Short: "Get a value from the store by its key.", Long: dataStoreDescription + "This will retrieve the value for the given key.", Args: cobra.ExactArgs(1), Run: func(cmd *cobra.Command, args []string) { @@ -125,7 +128,7 @@ func registerStoreClearCmd(ctx *context.Context, rootCmd *cobra.Command) { subCmd := &cobra.Command{ Use: "clear", Aliases: []string{"reset"}, - Short: "Clear the data store.", + Short: "Clear data from the store. Use --full to remove all stored data.", Long: dataStoreDescription + "This will remove all keys and values from the data store.", Args: cobra.NoArgs, Run: func(cmd *cobra.Command, args []string) { diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 7fb0991..e32bd87 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -10,6 +10,7 @@ - [Executables](guide/executable.md "Managing executables") - [Templating](guide/templating.md "Using flowfile templates") - [Managing state](guide/state.md "Managing executable state") + - [Conditional execution](guide/conditional.md "Conditional execution") - Reference diff --git a/docs/cli/README.md b/docs/cli/README.md index 4aee135..fbe05df 100644 --- a/docs/cli/README.md +++ b/docs/cli/README.md @@ -24,7 +24,7 @@ See github.com/jahvon/flow for more information. * [flow library](flow_library.md) - View and manage your library of workspaces and executables. * [flow logs](flow_logs.md) - List and view logs for previous flow executions. * [flow secret](flow_secret.md) - Manage flow secrets. -* [flow store](flow_store.md) - Manage the data store. +* [flow store](flow_store.md) - Manage the data store for persisting key-value data. * [flow sync](flow_sync.md) - Scan workspaces and update flow cache. * [flow template](flow_template.md) - Manage flowfile templates. * [flow workspace](flow_workspace.md) - Manage flow workspaces. diff --git a/docs/cli/flow_store.md b/docs/cli/flow_store.md index daaf7c7..4728bff 100644 --- a/docs/cli/flow_store.md +++ b/docs/cli/flow_store.md @@ -1,6 +1,10 @@ ## flow store -Manage the data store. +Manage the data store for persisting key-value data. + +### Synopsis + +Manage the flow data store - a key-value store that persists data within and across executable runs. Values set outside executables persist globally, while values set within executables persist only for that execution scope. ### Options @@ -19,7 +23,7 @@ Manage the data store. ### SEE ALSO * [flow](flow.md) - flow is a command line interface designed to make managing and running development workflows easier. -* [flow store clear](flow_store_clear.md) - Clear the data store. -* [flow store get](flow_store_get.md) - Get a value from the data store. -* [flow store set](flow_store_set.md) - Set a key-value pair in the data store. +* [flow store clear](flow_store_clear.md) - Clear data from the store. Use --full to remove all stored data. +* [flow store get](flow_store_get.md) - Get a value from the store by its key. +* [flow store set](flow_store_set.md) - Set a key-value pair in the store. diff --git a/docs/cli/flow_store_clear.md b/docs/cli/flow_store_clear.md index 653247d..2b2e37f 100644 --- a/docs/cli/flow_store_clear.md +++ b/docs/cli/flow_store_clear.md @@ -1,6 +1,6 @@ ## flow store clear -Clear the data store. +Clear data from the store. Use --full to remove all stored data. ### Synopsis @@ -29,5 +29,5 @@ flow store clear [flags] ### SEE ALSO -* [flow store](flow_store.md) - Manage the data store. +* [flow store](flow_store.md) - Manage the data store for persisting key-value data. diff --git a/docs/cli/flow_store_get.md b/docs/cli/flow_store_get.md index c9d0ec3..06f09fe 100644 --- a/docs/cli/flow_store_get.md +++ b/docs/cli/flow_store_get.md @@ -1,6 +1,6 @@ ## flow store get -Get a value from the data store. +Get a value from the store by its key. ### Synopsis @@ -28,5 +28,5 @@ flow store get KEY [flags] ### SEE ALSO -* [flow store](flow_store.md) - Manage the data store. +* [flow store](flow_store.md) - Manage the data store for persisting key-value data. diff --git a/docs/cli/flow_store_set.md b/docs/cli/flow_store_set.md index 8d942b8..dd041fb 100644 --- a/docs/cli/flow_store_set.md +++ b/docs/cli/flow_store_set.md @@ -1,6 +1,6 @@ ## flow store set -Set a key-value pair in the data store. +Set a key-value pair in the store. ### Synopsis @@ -28,5 +28,5 @@ flow store set KEY [VALUE] [flags] ### SEE ALSO -* [flow store](flow_store.md) - Manage the data store. +* [flow store](flow_store.md) - Manage the data store for persisting key-value data. diff --git a/docs/guide/_sidebar.md b/docs/guide/_sidebar.md index 5c39a70..f40e8b5 100644 --- a/docs/guide/_sidebar.md +++ b/docs/guide/_sidebar.md @@ -8,3 +8,6 @@ - [Workspaces](workspace.md "Managing workspaces") - [Executables](executable.md "Managing executables") - [Templating](templating.md "Using flowfile templates") + - [Managing state](guide/state.md "Managing executable state") + - [Conditional execution](guide/conditional.md "Conditional execution") + diff --git a/docs/schemas/flowfile_schema.json b/docs/schemas/flowfile_schema.json index 5332090..b1d794c 100644 --- a/docs/schemas/flowfile_schema.json +++ b/docs/schemas/flowfile_schema.json @@ -248,7 +248,7 @@ "default": "" }, "if": { - "description": "A condition to determine if the executable should be run.", + "description": "An expression that determines whether the executable should run, using the Expr language syntax. \nThe expression is evaluated at runtime and must resolve to a boolean value. \n\nThe expression has access to OS/architecture information (os, arch), environment variables (env), stored data \n(store), and context information (ctx) like workspace and paths. \n\nFor example, `os == \"darwin\"` will only run on macOS, `len(store[\"feature\"]) \u003e 0` will run if a value exists \nin the store, and `env[\"CI\"] == \"true\"` will run in CI environments. \nSee the [Expr documentation](https://expr-lang.org/docs/language-definition) for more information.\n", "type": "string", "default": "" }, @@ -481,7 +481,7 @@ "default": "" }, "if": { - "description": "A condition to determine if the executable should be run.", + "description": "An expression that determines whether the executable should run, using the Expr language syntax. \nThe expression is evaluated at runtime and must resolve to a boolean value. \n\nThe expression has access to OS/architecture information (os, arch), environment variables (env), stored data \n(store), and context information (ctx) like workspace and paths. \n\nFor example, `os == \"darwin\"` will only run on macOS, `len(store[\"feature\"]) \u003e 0` will run if a value exists \nin the store, and `env[\"CI\"] == \"true\"` will run in CI environments. \nSee the [Expr documentation](https://expr-lang.org/docs/language-definition) for more information.\n", "type": "string", "default": "" }, diff --git a/docs/types/flowfile.md b/docs/types/flowfile.md index a014662..9954564 100644 --- a/docs/types/flowfile.md +++ b/docs/types/flowfile.md @@ -206,7 +206,7 @@ Configuration for a parallel executable. | ----- | ----------- | ---- | ------- | :--------: | | `args` | Arguments to pass to the executable. | `array` (`string`) | [] | | | `cmd` | The command to execute. One of `cmd` or `ref` must be set. | `string` | | | -| `if` | A condition to determine if the executable should be run. | `string` | | | +| `if` | An expression that determines whether the executable should run, using the Expr language syntax. The expression is evaluated at runtime and must resolve to a boolean value. The expression has access to OS/architecture information (os, arch), environment variables (env), stored data (store), and context information (ctx) like workspace and paths. For example, `os == "darwin"` will only run on macOS, `len(store["feature"]) > 0` will run if a value exists in the store, and `env["CI"] == "true"` will run in CI environments. See the [Expr documentation](https://expr-lang.org/docs/language-definition) for more information. | `string` | | | | `ref` | A reference to another executable to run in serial. One of `cmd` or `ref` must be set. | [ExecutableRef](#ExecutableRef) | | | | `retries` | The number of times to retry the executable if it fails. | `integer` | 0 | | @@ -353,7 +353,7 @@ Configuration for a serial executable. | ----- | ----------- | ---- | ------- | :--------: | | `args` | Arguments to pass to the executable. | `array` (`string`) | [] | | | `cmd` | The command to execute. One of `cmd` or `ref` must be set. | `string` | | | -| `if` | A condition to determine if the executable should be run. | `string` | | | +| `if` | An expression that determines whether the executable should run, using the Expr language syntax. The expression is evaluated at runtime and must resolve to a boolean value. The expression has access to OS/architecture information (os, arch), environment variables (env), stored data (store), and context information (ctx) like workspace and paths. For example, `os == "darwin"` will only run on macOS, `len(store["feature"]) > 0` will run if a value exists in the store, and `env["CI"] == "true"` will run in CI environments. See the [Expr documentation](https://expr-lang.org/docs/language-definition) for more information. | `string` | | | | `ref` | A reference to another executable to run in serial. One of `cmd` or `ref` must be set. | [ExecutableRef](#ExecutableRef) | | | | `retries` | The number of times to retry the executable if it fails. | `integer` | 0 | | | `reviewRequired` | If set to true, the user will be prompted to review the output of the executable before continuing. | `boolean` | false | | diff --git a/types/executable/executable.gen.go b/types/executable/executable.gen.go index 3705523..0c269fa 100644 --- a/types/executable/executable.gen.go +++ b/types/executable/executable.gen.go @@ -219,7 +219,20 @@ type ParallelRefConfig struct { // Cmd string `json:"cmd,omitempty" yaml:"cmd,omitempty" mapstructure:"cmd,omitempty"` - // A condition to determine if the executable should be run. + // An expression that determines whether the executable should run, using the Expr + // language syntax. + // The expression is evaluated at runtime and must resolve to a boolean value. + // + // The expression has access to OS/architecture information (os, arch), + // environment variables (env), stored data + // (store), and context information (ctx) like workspace and paths. + // + // For example, `os == "darwin"` will only run on macOS, `len(store["feature"]) > + // 0` will run if a value exists + // in the store, and `env["CI"] == "true"` will run in CI environments. + // See the [Expr documentation](https://expr-lang.org/docs/language-definition) + // for more information. + // If string `json:"if,omitempty" yaml:"if,omitempty" mapstructure:"if,omitempty"` // A reference to another executable to run in serial. @@ -386,7 +399,20 @@ type SerialRefConfig struct { // Cmd string `json:"cmd,omitempty" yaml:"cmd,omitempty" mapstructure:"cmd,omitempty"` - // A condition to determine if the executable should be run. + // An expression that determines whether the executable should run, using the Expr + // language syntax. + // The expression is evaluated at runtime and must resolve to a boolean value. + // + // The expression has access to OS/architecture information (os, arch), + // environment variables (env), stored data + // (store), and context information (ctx) like workspace and paths. + // + // For example, `os == "darwin"` will only run on macOS, `len(store["feature"]) > + // 0` will run if a value exists + // in the store, and `env["CI"] == "true"` will run in CI environments. + // See the [Expr documentation](https://expr-lang.org/docs/language-definition) + // for more information. + // If string `json:"if,omitempty" yaml:"if,omitempty" mapstructure:"if,omitempty"` // A reference to another executable to run in serial. diff --git a/types/executable/executable_schema.yaml b/types/executable/executable_schema.yaml index 20e3a86..6dbbf01 100644 --- a/types/executable/executable_schema.yaml +++ b/types/executable/executable_schema.yaml @@ -345,7 +345,16 @@ definitions: default: "" if: type: string - description: A condition to determine if the executable should be run. + description: | + An expression that determines whether the executable should run, using the Expr language syntax. + The expression is evaluated at runtime and must resolve to a boolean value. + + The expression has access to OS/architecture information (os, arch), environment variables (env), stored data + (store), and context information (ctx) like workspace and paths. + + For example, `os == "darwin"` will only run on macOS, `len(store["feature"]) > 0` will run if a value exists + in the store, and `env["CI"] == "true"` will run in CI environments. + See the [Expr documentation](https://expr-lang.org/docs/language-definition) for more information. default: "" args: type: array @@ -501,7 +510,16 @@ definitions: default: "" if: type: string - description: A condition to determine if the executable should be run. + description: | + An expression that determines whether the executable should run, using the Expr language syntax. + The expression is evaluated at runtime and must resolve to a boolean value. + + The expression has access to OS/architecture information (os, arch), environment variables (env), stored data + (store), and context information (ctx) like workspace and paths. + + For example, `os == "darwin"` will only run on macOS, `len(store["feature"]) > 0` will run if a value exists + in the store, and `env["CI"] == "true"` will run in CI environments. + See the [Expr documentation](https://expr-lang.org/docs/language-definition) for more information. default: "" args: type: array