Belated Expression Workflow Changes

basic-examples/expressions/README.md

@@ -1,43 +1,136 @@
-# Expressions
+# String Expressions
 
 ## Workflow Description
 
-This workflow demonstrates example expressions as detailed in our [expression documentation](https://arcalot.io/arcaflow/workflows/expressions/).
+This workflow demonstrates some example expressions as detailed in our [expression 
+documentation](https://arcalot.io/arcaflow/workflows/expressions/). Arcaflow 
+expressions are a way to reference paths within the workflow or their fields, and they 
+additionally allow you to manipulate the data.
+
+*Note: Arcaflow expressions were inspired by JSONPath, and may look familar, but 
+expressions have diverged from the JSONPath syntax to enable a rich feature set that is 
+specific to Arcaflow.* 
+
+The basic use of expressions in a workflow YAML looks like this:
+
+```
+some_value: !expr $.your.expression.here
+```
+
+## Examples
+
+Basic path references are already used across the other example workflows. These 
+include references in a step to an input from the schema:
+
+```
+steps:
+  example:
+    plugin:
+      deployment_type: image
+      src: quay.io/arcalot/arcaflow-plugin-example:0.5.0
+    input:
+      name:
+        _type: nickname
+        #Expression for an input path reference
+        nick: !expr $.input.nickname
+```
+
+As well as references in the output to a step field:
+
+```
+outputs:
+  success:
+    #Expression for a step field reference
+    example: !expr $.steps.example.outputs.success
+```
+
+This workflow demonstrates string literals and concatenation:
+
+```
+steps:
+  example1:
+    plugin:
+      deployment_type: image
+      src: quay.io/arcalot/arcaflow-plugin-template-python:0.4.0
+    input:
+      #Expression with concatenation and string literal
+      name: !expr $.input.name + ' -- \"The Noble Workflow Engine\"'
+```
+
+As well as type conversions and math operations:
+
+```
+steps:
+  example2:
+    plugin:
+      deployment_type: image
+      src: quay.io/arcalot/arcaflow-plugin-template-python:0.4.0
+    input:
+      # Expression with type conversions, math operation, and concatenation
+      name: >
+        !expr intToString(floatToInt(intToFloat($.input.int_value) * 
+        $.input.float_value)) + ' User'
+```
+
+In this last expression, the plugin requires a string input. The logical steps here are:
+1.  An integer input is converted to a float in order to make it compatible with a math 
+operation with another float input: `intToFloat($.input_int_value)`
+2. The two float values are multiplied: `... * $.input.float_value`
+3. The resulting float is converted to an integer (truncating the fractional value): 
+`floatToInt(...)`
+4. The integer is converted to a string: `intToString(...)`
+5. Finally, the two strings are concatenated: `... + ' User'`
 
 ## Files
 
-- [`workflow.yaml`](workflow.yaml) -- Defines the workflow input schema, the plugins to run
-  and their data relationships, and the output to present to the user
-- [`input.yaml`](input.yaml) -- The input parameters that the user provides for running
-  the workflow
-- [`config.yaml`](config.yaml) -- Global config parameters that are passed to the Arcaflow
-  engine
+- [`workflow.yaml`](workflow.yaml) -- Defines the workflow input schema, the plugins to 
+run and their data relationships, and the output to present to the user
+- [`input.yaml`](input.yaml) -- The input parameters that the user provides for running 
+the parent workflow
+- [`config.yaml`](config.yaml) -- Global config parameters that are passed to the 
+Arcaflow engine
 
 ## Running the Workflow
 
 ### Workflow Execution
 
-Download a Go binary of the latest version of the Arcaflow engine from: https://github.com/arcalot/arcaflow-engine/releases
+Download a Go binary of the latest version of the Arcaflow engine from: 
+https://github.com/arcalot/arcaflow-engine/releases
 
 Run the workflow:
 ```
 $ export WFPATH=<path to this workflow directory>
 $ arcaflow -input ${WFPATH}/input.yaml -config ${WFPATH}/config.yaml -context ${WFPATH}
 ```
-### Output
-
-Each input expression to the `name` parameter outputs as the same string.
 
-```shell
-output_data:
-  message:
-    data:
-      - name: Hello, Here's an apostrophe and "embedded quotes".!
-      - name: Hello, Here's an apostrophe and "embedded quotes".!
-      - name: Hello, Here's an apostrophe and "embedded quotes".!
-      - name: Hello, Here's an apostrophe and "embedded quotes".!
-      - name: Hello, Here's an apostrophe and "embedded quotes".!
-      - name: Hello, Here's an apostrophe and "embedded quotes".!
-output_id: success
+## Workflow Diagram
 
-```
+```mermaid title="workflow.yaml"
+%% Mermaid markdown workflow
+flowchart LR
+%% Success path
+steps.example2.outputs-->steps.example2.outputs.success
+steps.example1.deploy-->steps.example1.starting
+steps.example1.outputs.success-->outputs.success
+steps.example2.cancelled-->steps.example2.outputs
+steps.example2.outputs.success-->outputs.success
+steps.example2.running-->steps.example2.outputs
+steps.example1.outputs-->steps.example1.outputs.success
+steps.example1.cancelled-->steps.example1.outputs
+steps.example2.starting-->steps.example2.starting.started
+steps.example2.starting-->steps.example2.running
+input-->steps.example1.starting
+input-->steps.example2.starting
+steps.example2.disabled-->steps.example2.disabled.output
+steps.example1.starting-->steps.example1.starting.started
+steps.example1.starting-->steps.example1.running
+steps.example1.enabling-->steps.example1.enabling.resolved
+steps.example1.enabling-->steps.example1.starting
+steps.example1.enabling-->steps.example1.disabled
+steps.example1.disabled-->steps.example1.disabled.output
+steps.example1.running-->steps.example1.outputs
+steps.example2.enabling-->steps.example2.enabling.resolved
+steps.example2.enabling-->steps.example2.starting
+steps.example2.enabling-->steps.example2.disabled
+steps.example2.deploy-->steps.example2.starting
+```

basic-examples/expressions/config.yaml

@@ -1,8 +1,8 @@
 deployers:
   image:
-    deployer_name: docker
+    deployer_name: podman
 log:
   level: debug    
 logged_outputs:
   error:
-    level: error
+    level: debug

basic-examples/expressions/input.yaml

@@ -1 +1,3 @@
-{}
+name: Arcaflow
+int_value: 42
+float_value: 31.84

basic-examples/expressions/workflow.yaml

@@ -1,25 +1,51 @@
----
 version: v0.2.0
 input:
   root: RootObject
   objects:
     RootObject:
       id: RootObject
-      properties: {}
+      properties:
+        name:
+          display:
+            description: Just a name
+            name: Name
+          required: true
+          type:
+            type_id: string
+        int_value:
+          display:
+            description: Just an integer value
+            name: Integer Value
+          required: true
+          type:
+            type_id: integer
+        float_value:
+          display:
+            description: Just a float value
+            name: Float Value
+          required: true
+          type:
+            type_id: float
+
 steps:
-  example:
-    kind: foreach
-    workflow: subworkflow.yaml
-    items:
-      - name: !expr '"Here''s an apostrophe and \"embedded quotes\"."'
-      - name: !expr "'Here\\'s an apostrophe and \"embedded quotes\".'"
-      - name: !expr |-
-          'Here\'s an apostrophe and "embedded quotes".'
-      - name: !expr |-
-          "Here's an apostrophe and \"embedded quotes\"."
-      - name: !expr '`Here''s an apostrophe and "embedded quotes".`'
-      - name: !expr |-
-          `Here's an apostrophe and "embedded quotes".`
+  example1:
+    plugin:
+      deployment_type: image
+      src: quay.io/arcalot/arcaflow-plugin-template-python:0.4.0
+    input:
+      #Expression with concatenation and string literal
+      name: !expr $.input.name + ' -- \"The Noble Workflow Engine\"'
+  example2:
+    plugin:
+      deployment_type: image
+      src: quay.io/arcalot/arcaflow-plugin-template-python:0.4.0
+    input:
+      # Expression with type conversions, math operation, and concatenation
+      name: >
+        !expr intToString(floatToInt(intToFloat($.input.int_value) * 
+        $.input.float_value)) + ' User'
+
 outputs:
   success:
-    message: !expr $.steps.example.outputs.success
+    name: !expr $.steps.example1.outputs.success
+    message: !expr $.steps.example2.outputs.success