From e164d7d4d016218ade6096a85bc97b22733de4e4 Mon Sep 17 00:00:00 2001 From: SamTolmay Date: Thu, 21 Jan 2021 16:53:08 +0200 Subject: [PATCH] feat(docs): Add operator docs. --- packages/docs/lowdefy.yaml | 32 +++++++ packages/docs/operators/_and.yaml | 78 ++++++++++++++--- packages/docs/operators/_divide.yaml | 42 +++++++++ packages/docs/operators/_eq.yaml | 63 ++++++++++++++ packages/docs/operators/_if.yaml | 86 +++++++++++++++++++ packages/docs/operators/_if_none.yaml | 57 ++++++++++++ packages/docs/operators/_log.yaml | 32 +++++++ packages/docs/operators/_not.yaml | 43 ++++++++++ packages/docs/operators/_or.yaml | 78 +++++++++++++++++ packages/docs/operators/_product.yaml | 55 ++++++++++++ packages/docs/operators/_sum.yaml | 55 ++++++++++++ .../docs/templates/blocks/examples.yaml.njk | 2 +- .../docs/templates/blocks/template.yaml.njk | 4 +- packages/docs/templates/operators.yaml.njk | 68 +++++++++++++++ 14 files changed, 682 insertions(+), 13 deletions(-) create mode 100644 packages/docs/operators/_divide.yaml create mode 100644 packages/docs/operators/_eq.yaml create mode 100644 packages/docs/operators/_if.yaml create mode 100644 packages/docs/operators/_if_none.yaml create mode 100644 packages/docs/operators/_log.yaml create mode 100644 packages/docs/operators/_not.yaml create mode 100644 packages/docs/operators/_or.yaml create mode 100644 packages/docs/operators/_product.yaml create mode 100644 packages/docs/operators/_sum.yaml create mode 100644 packages/docs/templates/operators.yaml.njk diff --git a/packages/docs/lowdefy.yaml b/packages/docs/lowdefy.yaml index f684bb207..30d0db1c4 100644 --- a/packages/docs/lowdefy.yaml +++ b/packages/docs/lowdefy.yaml @@ -204,6 +204,30 @@ menus: - id: _and type: MenuLink pageId: _and + - id: _divide + type: MenuLink + pageId: _divide + - id: _eq + type: MenuLink + pageId: _eq + - id: _if_none + type: MenuLink + pageId: _if_none + - id: _log + type: MenuLink + pageId: _log + - id: _not + type: MenuLink + pageId: _not + - id: _or + type: MenuLink + pageId: _or + - id: _product + type: MenuLink + pageId: _product + - id: _sum + type: MenuLink + pageId: _sum pages: - _ref: introduction.yaml @@ -247,3 +271,11 @@ pages: - _ref: actions/Validate.yaml - _ref: operators/_and.yaml + - _ref: operators/_divide.yaml + - _ref: operators/_eq.yaml + - _ref: operators/_if_none.yaml + - _ref: operators/_log.yaml + - _ref: operators/_not.yaml + - _ref: operators/_or.yaml + - _ref: operators/_product.yaml + - _ref: operators/_sum.yaml diff --git a/packages/docs/operators/_and.yaml b/packages/docs/operators/_and.yaml index 0fdd326ec..3a5d375e5 100644 --- a/packages/docs/operators/_and.yaml +++ b/packages/docs/operators/_and.yaml @@ -13,16 +13,74 @@ # limitations under the License. _ref: - path: templates/general.yaml.njk + path: templates/operators.yaml.njk vars: pageId: _and pageTitle: _and - section: Operators - content: - - id: markdown - type: Markdown - style: - '.markdown-body': - fontSize: 14px - properties: - content: | + argument_types: array[any] + return_types: boolean + description: | + The `_and` operator performs a logical `and` over an array of inputs, using javascript [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy) and [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy) rules. + + It only returns true if all the values in the array are truthy (not `false`, `0`, `null`, `undefined`, or the empty string `""`). Else it returns false. + arguments: | + #### array + An array of values over which to perform a logical and. + examples: | + #### Two `true` values: + ```yaml + _and: + - true + - true + ``` + Returns: `true` + + #### Array of `true` and `false` values: + ```yaml + _and: + - true + - true + - true + - false + ``` + Returns: `false` + + #### Check if two boolean inputs are true: + ```yaml + _and: + - _state: confirm_accept_terms + - _state: confirm_accept_privacy_policy + ``` + Returns: `true` if both inputs are `true` + + #### Truthy values: + ```yaml + _and: + - "Hello" + - 42 + - [] + - key: value + ``` + Returns: `true` + + #### Falsy values: + ```yaml + _and: + - true + - null + ``` + Returns: `false` + + ```yaml + _and: + - true + - 0 + ``` + Returns: `false` + + ```yaml + _and: + - true + - "" + ``` + Returns: `false` diff --git a/packages/docs/operators/_divide.yaml b/packages/docs/operators/_divide.yaml new file mode 100644 index 000000000..5cf6920cf --- /dev/null +++ b/packages/docs/operators/_divide.yaml @@ -0,0 +1,42 @@ +# Copyright 2020-2021 Lowdefy, Inc + +# 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. + +_ref: + path: templates/operators.yaml.njk + vars: + pageId: _divide + pageTitle: _divide + argument_types: array[number] + return_types: number + description: | + The `_divide` operator divides two numbers. It takes an array of two numbers as input and returns a number. Dividing by zero will throw an error. + arguments: | + #### array + An array of two numbers. + examples: | + #### Divide two numbers: + ```yaml + _divide: + - 12 + - 4 + ``` + Returns: `3` + + #### Cannot divide by zero: + ```yaml + _divide: + - 1 + - 0 + ``` + Returns: `null` and throws a operator error. diff --git a/packages/docs/operators/_eq.yaml b/packages/docs/operators/_eq.yaml new file mode 100644 index 000000000..b348cb67b --- /dev/null +++ b/packages/docs/operators/_eq.yaml @@ -0,0 +1,63 @@ +# Copyright 2020-2021 Lowdefy, Inc + +# 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. + +_ref: + path: templates/operators.yaml.njk + vars: + pageId: _eq + pageTitle: _eq + argument_types: array[any] + return_types: boolean + description: | + The `_eq` operator tests if two values are equal. It takes an array of two values to test. + + > The `_eq` operator tests for strict equality, and won't do a deep comparison. + + arguments: | + #### array + An array of two values to compare. + examples: | + #### Two strings: + ```yaml + _eq: + - Hello + - Hello + ``` + Returns: `true` + + #### Two numbers: + ```yaml + _eq: + - _sum: + - 3 + - 4 + - 8 + ``` + Returns: `false` + + #### Arrays are not compared deeply: + ```yaml + _eq: + - [1,2,3] + - [1,2,3] + ``` + Returns: `false` + + #### Values from "getter" operators are copies and not equal: + ```yaml + _eq: + - _state: my_object + - _state: my_object + ``` + Returns: `false` diff --git a/packages/docs/operators/_if.yaml b/packages/docs/operators/_if.yaml new file mode 100644 index 000000000..6ae815339 --- /dev/null +++ b/packages/docs/operators/_if.yaml @@ -0,0 +1,86 @@ +# Copyright 2020-2021 Lowdefy, Inc + +# 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. + +_ref: + path: templates/operators.yaml.njk + vars: + pageId: _and + pageTitle: _and + argument_types: array + return_types: boolean + description: | + The `_and` operator performs a logical `and` over an array of inputs, using javascript 'truthy' and 'falsy' rules. + + It returns true if all the values in the array are truthy (not `false`, `0`, `null`, `undefined`, or the empty string `""`). Else it returns false. + arguments: | + #### array + An array of values over which to perform a logical and. + examples: | + #### Two `true` values: + ``` + _and: + - true + - true + ``` + Returns: `true` + + #### Array of `true` and `false` values: + ``` + _and: + - true + - true + - true + - false + ``` + Returns: `false` + + #### Check if two boolean inputs are true: + ``` + _and: + - _state: confirm_accept_terms + - _state: confirm_accept_privacy_policy + ``` + Returns: `true` if both inputs are `true` + + #### Truthy values: + ``` + _and: + - "Hello" + - 42 + - [] + - key: value + ``` + Returns: `true` + + #### Falsy values: + ``` + _and: + - true + - null + ``` + Returns: `false` + + ``` + _and: + - true + - 0 + ``` + Returns: `false` + + ``` + _and: + - true + - "" + ``` + Returns: `false` diff --git a/packages/docs/operators/_if_none.yaml b/packages/docs/operators/_if_none.yaml new file mode 100644 index 000000000..d01ba51e3 --- /dev/null +++ b/packages/docs/operators/_if_none.yaml @@ -0,0 +1,57 @@ +# Copyright 2020-2021 Lowdefy, Inc + +# 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. + +_ref: + path: templates/operators.yaml.njk + vars: + pageId: _if_none + pageTitle: _if_none + argument_types: array[any] + return_types: boolean + description: | + The `_if_none` operator replaces the input value with an alternative if the value is of a "none-type" like `null` or `undefined`. + arguments: | + #### array + - First value: The value to test. + - Second value: The replacement. + examples: | + #### The value is not replaced if it is not of a none-type: + ```yaml + _if_none: + - Value + - Replacement + ``` + Returns: `Value` + + #### The value is replaced if it is of a none-type: + ```yaml + _if_none: + - null + - Replacement + ``` + Returns: `Replacement` + + ```yaml + _if_none: + - _state: does_not_exist # Value in state that does not exist + - Replacement + ``` + Returns: `Replacement` + + ```yaml + _if_none: + - _request: still_loading # _request returns null if the request is loading + - [] + ``` + Returns: `[]` diff --git a/packages/docs/operators/_log.yaml b/packages/docs/operators/_log.yaml new file mode 100644 index 000000000..d7d7da05a --- /dev/null +++ b/packages/docs/operators/_log.yaml @@ -0,0 +1,32 @@ +# Copyright 2020-2021 Lowdefy, Inc + +# 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. + +_ref: + path: templates/operators.yaml.njk + vars: + pageId: _log + pageTitle: _log + argument_types: any + return_types: any + description: | + The `_log` operator logs it input to the console, and returns the value it received. Since it returns the value it received, it can be used to debug without affecting the rest of the configuration. + arguments: | + #### any + examples: | + #### Log the results of a request to the console: + ```yaml + _log: + _request: my_request + ``` + Returns: The value of the request diff --git a/packages/docs/operators/_not.yaml b/packages/docs/operators/_not.yaml new file mode 100644 index 000000000..dbd3f5a41 --- /dev/null +++ b/packages/docs/operators/_not.yaml @@ -0,0 +1,43 @@ +# Copyright 2020-2021 Lowdefy, Inc + +# 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. + +_ref: + path: templates/operators.yaml.njk + vars: + pageId: _not + pageTitle: _not + argument_types: any + return_types: boolean + description: | + The `_not` operator returns the logical negation of the input. If the value is not a boolean, it will be converted to a boolean using javascript [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy) and [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy) rules. + arguments: | + #### any + examples: | + #### Not `true` is `false`: + ```yaml + _not: true + ``` + Returns: `false` + + #### Return `true` for a falsy value: + ```yaml + _not: null + ``` + Returns: `true` + + #### Return `false` for a truthy value: + ```yaml + _not: 100 + ``` + Returns: `false` diff --git a/packages/docs/operators/_or.yaml b/packages/docs/operators/_or.yaml new file mode 100644 index 000000000..8e42b8499 --- /dev/null +++ b/packages/docs/operators/_or.yaml @@ -0,0 +1,78 @@ +# Copyright 2020-2021 Lowdefy, Inc + +# 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. + +_ref: + path: templates/operators.yaml.njk + vars: + pageId: _or + pageTitle: _or + argument_types: array[any] + return_types: boolean + description: | + The `_or` operator performs a logical `or` over an array of inputs, using javascript [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy) and [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy) rules. + + It returns true if any of the values in the array are truthy (not `false`, `0`, `null`, `undefined`, or the empty string `""`). If all the values are falsy, it returns `false`. + arguments: | + #### array + An array of values over which to perform a logical or. + examples: | + #### `true` and `false` values: + ```yaml + _or: + - true + - false + ``` + Returns: `true` + + #### Array of `true` and `false` values: + ```yaml + _or: + - true + - false + - false + - false + ``` + Returns: `true` + + #### Falsy values values: + ``` + ```yaml + _or: + - null + - 0 + - '' + ``` + Returns: `false` + + #### Truthy values: + ```yaml + _or: + - false + - "Hello" + ``` + Returns: `true` + + ```yaml + _or: + - false + - 99 + ``` + Returns: `true` + + ```yaml + _or: + - false + - [1,2,3] + ``` + Returns: `true` diff --git a/packages/docs/operators/_product.yaml b/packages/docs/operators/_product.yaml new file mode 100644 index 000000000..eac5ec632 --- /dev/null +++ b/packages/docs/operators/_product.yaml @@ -0,0 +1,55 @@ +# Copyright 2020-2021 Lowdefy, Inc + +# 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. + +_ref: + path: templates/operators.yaml.njk + vars: + pageId: _sum + pageTitle: _sum + argument_types: array[any] + return_types: number + description: | + The `_sum` operator takes the sum of the values given as input. If a value is not a number, the value is skipped. + arguments: | + #### array + An array of values to add. + examples: | + #### Two numbers: + ```yaml + _sum: + - 3 + - 4 + ``` + Returns: `7` + + #### Array of numbers: + ```yaml + _sum: + - 1 + - 2 + - 3 + - 4 + ``` + Returns: `10` + + #### Non-numbers are skipped: + ```yaml + _sum: + - 1 + - null + - 3 + - "four" + - 5 + ``` + Returns: `9` diff --git a/packages/docs/operators/_sum.yaml b/packages/docs/operators/_sum.yaml new file mode 100644 index 000000000..0332d4d41 --- /dev/null +++ b/packages/docs/operators/_sum.yaml @@ -0,0 +1,55 @@ +# Copyright 2020-2021 Lowdefy, Inc + +# 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. + +_ref: + path: templates/operators.yaml.njk + vars: + pageId: _product + pageTitle: _product + argument_types: array[any] + return_types: number + description: | + The `_product` operator takes the product of the values given as input. If a value is not a number, the value is skipped. + arguments: | + #### array + An array of values to multiply. + examples: | + #### Two numbers: + ```yaml + _product: + - 3 + - 4 + ``` + Returns: `12` + + #### Array of numbers: + ```yaml + _product: + - 1 + - 2 + - 3 + - 4 + ``` + Returns: `24` + + #### Non-numbers are skipped: + ```yaml + _product: + - 1 + - null + - 3 + - "four" + - 5 + ``` + Returns: `15` diff --git a/packages/docs/templates/blocks/examples.yaml.njk b/packages/docs/templates/blocks/examples.yaml.njk index d5e8dc25b..b4f8c7bf7 100644 --- a/packages/docs/templates/blocks/examples.yaml.njk +++ b/packages/docs/templates/blocks/examples.yaml.njk @@ -32,7 +32,7 @@ blocks: - id: example_config_{{ loop.index }} layout: span: 12 - type: Markdown + type: MarkdownWithHtml properties: content: _nunjucks: diff --git a/packages/docs/templates/blocks/template.yaml.njk b/packages/docs/templates/blocks/template.yaml.njk index 09319e6e8..1b4e5f1b9 100644 --- a/packages/docs/templates/blocks/template.yaml.njk +++ b/packages/docs/templates/blocks/template.yaml.njk @@ -98,7 +98,7 @@ blocks: - _var: category - input - id: state_markdown - type: Markdown + type: MarkdownWithHtml visible: _eq: - _var: category @@ -122,7 +122,7 @@ blocks: properties: title: Block Setup - id: setup_markdown - type: Markdown + type: MarkdownWithHtml properties: content: _nunjucks: diff --git a/packages/docs/templates/operators.yaml.njk b/packages/docs/templates/operators.yaml.njk new file mode 100644 index 000000000..7d2f96ce4 --- /dev/null +++ b/packages/docs/templates/operators.yaml.njk @@ -0,0 +1,68 @@ +# Copyright 2020-2021 Lowdefy, Inc + +# 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. + +_ref: + path: templates/general.yaml.njk + vars: + pageId: + _var: pageId + pageTitle: + _var: pageTitle + section: Operators + content: + - id: types + type: Markdown + style: + '.markdown-body': + fontSize: 14px + properties: + content: "`[ {{ argument_types }} ] => [ {{ return_types }} ]`" + - id: description + type: MarkdownWithHtml + style: + '.markdown-body': + fontSize: 14px + properties: + content: + _var: description + - id: arguments_title + type: Markdown + style: + '.markdown-body': + fontSize: 14px + properties: + content: '### Arguments' + - id: arguments + type: MarkdownWithHtml + style: + '.markdown-body': + fontSize: 14px + properties: + content: + _var: arguments + - id: examples_title + type: Markdown + style: + '.markdown-body': + fontSize: 14px + properties: + content: '### Examples' + - id: examples + type: MarkdownWithHtml + style: + '.markdown-body': + fontSize: 14px + properties: + content: + _var: examples \ No newline at end of file