Add examples for custom functions with scoped variables (#2406)

* added examples for custom functions with scoped variables, closes influxdata/DAR#196

* changed manipulate to use

* Apply suggestions from code review

Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com>

* updated custom function example

* minor updates to custom functions doc

Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com>

content/influxdb/v1.7/flux/guides/mathematic-operations.md

@@ -89,7 +89,7 @@ percent(sample: 20.0, total: 80.0)
 ### Transform values in a data stream
 To transform multiple values in an input stream, your function needs to:
 
-- [Handle piped-forward data](/{{< latest "influxdb" "v2" >}}/query-data/flux/custom-functions/#functions-that-manipulate-piped-forward-data).
+- [Handle piped-forward data](/{{< latest "influxdb" "v2" >}}/query-data/flux/custom-functions/#use-piped-forward-data-in-a-custom-function).
 - Each operand necessary for the calculation exists in each row _(see [Pivot vs join](#pivot-vs-join) below)_.
 - Use the [`map()` function](/{{< latest "influxdb" "v2" >}}/reference/flux/stdlib/built-in/transformations/map) to iterate over each row.
 

content/influxdb/v1.8/flux/guides/mathematic-operations.md

@@ -89,7 +89,7 @@ percent(sample: 20.0, total: 80.0)
 ### Transform values in a data stream
 To transform multiple values in an input stream, your function needs to:
 
-- [Handle piped-forward data](/{{< latest "influxdb" "v2" >}}/query-data/flux/custom-functions/#functions-that-manipulate-piped-forward-data).
+- [Handle piped-forward data](/{{< latest "influxdb" "v2" >}}/query-data/flux/custom-functions/#use-piped-forward-data-in-a-custom-function).
 - Each operand necessary for the calculation exists in each row _(see [Pivot vs join](#pivot-vs-join) below)_.
 - Use the [`map()` function](/{{< latest "influxdb" "v2" >}}/reference/flux/stdlib/built-in/transformations/map) to iterate over each row.
 

content/influxdb/v2.0/query-data/flux/custom-functions/_index.md

@@ -21,14 +21,19 @@ list_code_example: |
   ```
 ---
 
-Flux's functional syntax allows for custom functions.
+Flux's functional syntax lets you create custom functions.
 This guide walks through the basics of creating your own function.
 
-## Function definition structure
-The basic structure for defining functions in Flux is as follows:
+- [Function definition syntax](#function-definition-syntax)
+- [Use piped-forward data in a custom function](#use-piped-forward-data-in-a-custom-function)
+- [Define parameter defaults](#define-parameter-defaults)
+- [Define functions with scoped variables](#define-functions-with-scoped-variables)
+
+## Function definition syntax
+The basic syntax for defining functions in Flux is as follows:
 
 ```js
-// Basic function definition structure
+// Basic function definition syntax
 functionName = (functionParameters) => functionOperations
 ```
 
@@ -60,13 +65,13 @@ square = (n) => n * n
 multiply = (x, y) => x * y
 
 // Function usage
-> multiply(x:2, y:15)
+> multiply(x: 2, y: 15)
 30
 ```
 
-## Functions that manipulate piped-forward data
-Most Flux functions manipulate data piped-forward into the function.
-In order for a custom function to process piped-forward data, one of the function
+## Use piped-forward data in a custom function
+Most Flux functions process piped-forward data.
+To process piped-forward data, one of the function
 parameters must capture the input tables using the `<-` pipe-receive expression.
 
 In the example below, the `tables` parameter is assigned to the `<-` expression,
@@ -111,39 +116,111 @@ functionName = (param1=defaultValue1, param2=defaultValue2) => functionOperation
 
 Defaults are overridden by explicitly defining the parameter in the function call.
 
-#### Example functions with defaults
+### Example functions with defaults
 
-###### Get the winner or the "winner"
-The example below defines a `getWinner` function that returns the record with the highest
-or lowest `_value` (winner versus "winner") depending on the `noSarcasm` parameter which defaults to `true`.
+#### Get a list of leaders
+The example below defines a `leaderBoard` function that returns a limited number
+of records sorted by values in specified columns.
 It uses the [`sort()` function](/influxdb/v2.0/reference/flux/stdlib/built-in/transformations/sort)
 to sort records in either descending or ascending order.
 It then uses the [`limit()` function](/influxdb/v2.0/reference/flux/stdlib/built-in/transformations/limit)
-to return the first record from the sorted table.
+to return a specified number of records from the sorted table.
 
 ```js
 // Function definition
-getWinner = (tables=<-, noSarcasm:true) =>
+leaderBoard = (tables=<-, limit=4, columns=["_value"], desc=true) =>
   tables
-    |> sort(desc: noSarcasm)
-    |> limit(n:1)
+    |> sort(columns: columns, desc: desc)
+    |> limit(n: limit)
 
 // Function usage
-// Get the winner
+// Get the 4 highest scoring players
 from(bucket: "example-bucket")
   |> range(start: -1m)
   |> filter(fn: (r) =>
-    r._measurement == "mem" and
-    r._field == "used_percent"
+    r._measurement == "player-stats" and
+    r._field == "total-points"
   )
-  |> getWinner()
+  |> leaderBoard()
 
-// Get the "winner"
+// Get the 10 shortest race times
 from(bucket: "example-bucket")
   |> range(start: -1m)
   |> filter(fn: (r) =>
-    r._measurement == "mem" and
-    r._field == "used_percent"
+    r._measurement == "race-times" and
+    r._field == "elapsed-time"
   )
-  |> getWinner(noSarcasm: false)
+  |> leaderBoard(limit: 10, desc: false)
+```
+
+## Define functions with scoped variables
+To create custom functions with variables scoped to the function, place your
+function operations and variables inside of a [block (`{}`)](/influxdb/v2.0/reference/flux/language/blocks/)
+and use a `return` statement to return a specific variable.
+
+```js
+functionName = (functionParameters) => {
+  exampleVar = "foo"
+  return exampleVar
+}
+```
+
+### Example functions with scoped variables
+
+- [Return an alert level based on a value](#return-an-alert-level-based-on-a-value)
+- [Convert a HEX color code to a name](#convert-a-hex-color-code-to-a-name)
+
+#### Return an alert level based on a value
+The following function uses conditional logic to return an alert level based on
+a numeric input value:
+
+```js
+alertLevel = (v) => {
+  level = if float(v:v) >= 90.0 then "crit"
+          else if float(v:v) >= 80.0 then "warn"
+          else if float(v:v) >= 65.0 then "info"
+          else "ok"
+  return level
+}
+
+alertLevel(v: 87.3)
+// Returns "warn"
+```
+
+#### Convert a HEX color code to a name
+The following function converts a hexadecimal (HEX) color code to the equivalent HTML color name.
+The functions uses the [Flux dictionary package](/influxdb/v2.0/reference/flux/stdlib/dict/)
+to create a dictionary of HEX codes and their corresponding names.
+
+```js
+import "dict"
+
+hexName = (hex) => {
+  hexNames = dict.fromList(pairs: [
+    {key: "#00ffff", value: "Aqua"},
+    {key: "#000000", value: "Black"},
+    {key: "#0000ff", value: "Blue"},
+    {key: "#ff00ff", value: "Fuchsia"},
+    {key: "#808080", value: "Gray"},
+    {key: "#008000", value: "Green"},
+    {key: "#00ff00", value: "Lime"},
+    {key: "#800000", value: "Maroon"},
+    {key: "#000080", value: "Navy"},
+    {key: "#808000", value: "Olive"},
+    {key: "#800080", value: "Purple"},
+    {key: "#ff0000", value: "Red"},
+    {key: "#c0c0c0", value: "Silver"},
+    {key: "#008080", value: "Teal"},
+    {key: "#ffffff", value: "White"},
+    {key: "#ffff00", value: "Yellow"},
+  ])  
+  name = dict.get(dict: hexNames, key: hex, default: "No known name")
+  return name
+}
+
+hexName(hex: "#000000")
+// Returns "Black"
+
+hexName(hex: "#8b8b8b")
+// Returns "No known name"
 ```

content/influxdb/v2.0/query-data/flux/mathematic-operations.md

@@ -98,7 +98,7 @@ percent(sample: 20.0, total: 80.0)
 ### Transform values in a data stream
 To transform multiple values in an input stream, your function needs to:
 
-- [Handle piped-forward data](/influxdb/v2.0/query-data/flux/custom-functions/#functions-that-manipulate-piped-forward-data).
+- [Handle piped-forward data](/influxdb/v2.0/query-data/flux/custom-functions/#use-piped-forward-data-in-a-custom-function).
 - Each operand necessary for the calculation exists in each row _(see [Pivot vs join](#pivot-vs-join) below)_.
 - Use the [`map()` function](/influxdb/v2.0/reference/flux/stdlib/built-in/transformations/map) to iterate over each row.