# 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
  transformer: templates/operatorsMethodTransformer.js
  vars:
    pageId: _state
    pageTitle: _state
    types: |
      ```
      (key: string): any
      (all: boolean): any
      (arguments: {
        all?: boolean,
        key?: string,
        default?: any,
        contextId?: string
      }): any
      ```
    description: |
      The `_state` operator gets a value from the [`state`](/context-and-state) object. The `state` is a data object specific to the context it is in. The value of `input` blocks are available in `state`, with their `blockId` as key. By default, `_state` accesses the `state` object from the [`context`](/context-and-state) the operator is used in, but a different context can be specified.

    arguments: |
      ###### string
      If the `_state` operator is called with a string argument, the value of the key in the `state` object is returned. If the value is not found, `null` is returned. Dot notation and [block list indexes](/lists) are supported.

      ###### boolean
      If the `_state` operator is called with boolean argument `true`, the entire `state` object is returned.

      ###### object
        - `all: boolean`: If `all` is set to `true`, the entire `state` object is returned. One of `all` or `key` are required.
        - `key: string`: The value of the key in the `state` object is returned. If the value is not found, `null`, or the specified default value is returned. Dot notation and [block list indexes](/lists) are supported. One of `all` or `key` are required.
        - `default: any`: A value to return if the `key` is not found in `state`. By default, `null` is returned if a value is not found.
        - `contextId: string`: The id of a `context`. Setting this will get the value from the `state` of the specified context. A list of `contexts` that exist are returned by the [`_list_contexts`](/_list_contexts) operator. Cannot be used in `connections` or `requests`.
    examples: |
      ###### Get the value of `my_key` from `state`:
      ```yaml
      _state: my_key
      ```
      ```yaml
      _state:
        key: my_key
      ```
      Returns: The value of `my_key` in `state`.

      ###### Get the entire `state` object:
      ```yaml
      _state: true
      ```
      ```yaml
      _state:
        all: true
      ```
      Returns: The entire `state` object.

      ###### Dot notation:
      Assuming state:
      ```yaml
      my_object:
        subfield: 'Value'
      ```
      then:
      ```yaml
      _state: my_object.subfield
      ```
      ```yaml
      _state:
        key: my_object.subfield
      ```
      Returns: `"Value"`.

      ###### Return a default value if the value is not found:
      ```yaml
      _state:
        key: might_not_exist
        default: Default value
      ```
      Returns: The value of `might_not_exist`, or `"Default value"`.

      ###### Block list indices:
      Assuming `state`:
      ```yaml
      my_array:
        - value: 0
        - value: 1
        - value: 2
      ```
      then:
      ```yaml
      _state: my_array.$.value
      ```
      Returns: `0` when used from the first block (0th index) in a list.

      ###### Get a value from another `context`:
      ```yaml
      _state:
        key: my_key
        contextId: 'pageId:contextId:{}'
      ```
      Returns: The value of `my_key` in `state` in context `contextId` on page `pageId`.