docs added for elvis and null coalescing operators

app/app.go

@@ -15,7 +15,7 @@ const (
 	version  = "%d.%d.%d"
 	Major    = 5
 	Minor    = 1
-	Revision = 2000
+	Revision = 2100
 )
 
 // Copyright is the copyright owner string

builtins/docs/summaries.go

@@ -272,7 +272,8 @@ func init() {
 		"parser/equ":                       "Evaluate a mathematical function (deprecated)",
 		"parser/greater-than-greater-than": "Writes STDIN to disk - appending contents if file already exists",
 		"parser/pipe-append":               "Redirects STDOUT to a file and append its contents",
-		"parser/elvis":                     "Returns the right operand if the left operand is empty",
+		"parser/elvis":                     "Returns the right operand if the left operand is falsy",
+		"parser/null-coalescing":           "Returns the right operand if the left operand is empty / undefined",
 		"parser/pipe-err":                  "Pipes STDERR from the left hand command to STDIN of the right hand command",
 		"parser/range":                     "Outputs a ranged subset of data from STDIN",
 		"parser/element":                   "Outputs an element from a nested structure",
@@ -729,6 +730,7 @@ func init() {
 		"parser/fappend":                  "parser/greater-than-greater-than",
 		"parser/pipe-append":              "parser/pipe-append",
 		"parser/elvis":                    "parser/elvis",
+		"parser/null-coalescing":          "parser/null-coalescing",
 		"parser/pipe-err":                 "parser/pipe-err",
 		"parser/@[":                       "parser/range",
 		"parser/[[":                       "parser/element",

docs/parser/README.md

@@ -56,7 +56,9 @@ files.
 * [`>>` Append Pipe](../parser/pipe-append.md):
   Redirects STDOUT to a file and append its contents
 * [`?:` Elvis Operator](../parser/elvis.md):
-  Returns the right operand if the left operand is empty
+  Returns the right operand if the left operand is falsy
+* [`??` Null Coalescing Operator](../parser/null-coalescing.md):
+  Returns the right operand if the left operand is empty / undefined
 * [`?` STDERR Pipe](../parser/pipe-err.md):
   Pipes STDERR from the left hand command to STDIN of the right hand command
 * [`[..range]`](../parser/range.md):

docs/parser/elvis.md

@@ -1,20 +1,21 @@
 # `?:` Elvis Operator
 
-> Returns the right operand if the left operand is empty
+> Returns the right operand if the left operand is falsy
 
 ## Description
 
 The elvis operator is a little like a conditional where the result of the
-operation is the first non-empty value from left to right.
+operation is the first non-falsy value from left to right.
 
-An empty value is any of the following:
+A falsy value is any of the following:
 
-* An unset / undefined variable
-* Any value with a `null` data type
-
-Other "falsy" values such as numerical values of `0`, boolean `false`, zero
-length strings and strings containing `"null"` are not considered empty by the
-elvis operator.
+* an unset / undefined variable
+* any value with a `null` data type
+* a `str` or generic with the value `false`, `null`, `0`, `no`, `off`, `fail`,
+  `failed`, or `disabled`
+* a number (`num`, `float` or `int`) with the value `0`
+* an empty object or zero length array 
+* and, of course, a boolean with the value `false`
 
 
 
@@ -26,12 +27,12 @@ elvis operator.
 » $foo = $bar ?: "baz"
 ```
 
-If `$bar` is unset then the value of `$foo` will be **"baz"**.
+If `$bar` is falsy, then the value of `$foo` will be **"baz"**.
 
 **Multiple elvis operators:**
 
 ```
-» $unset_variable ?: null ?: "foobar"
+» $unset_variable ?: null ?: false ?: "foobar"
 foobar
 ```
 
@@ -54,6 +55,8 @@ where it says:
   Overview of the different schedulers (or 'run modes') in Murex
 * [`&&` And Logical Operator](../parser/logical-and.md):
   Continues next operation if previous operation passes
+* [`??` Null Coalescing Operator](../parser/null-coalescing.md):
+  Returns the right operand if the left operand is empty / undefined
 * [`?` STDERR Pipe](../parser/pipe-err.md):
   Pipes STDERR from the left hand command to STDIN of the right hand command
 * [`err`](../commands/err.md):

docs/parser/logical-and.md

@@ -48,7 +48,7 @@ try {
 * [Schedulers](../user-guide/schedulers.md):
   Overview of the different schedulers (or 'run modes') in Murex
 * [`?:` Elvis Operator](../parser/elvis.md):
-  Returns the right operand if the left operand is empty
+  Returns the right operand if the left operand is falsy
 * [`?` STDERR Pipe](../parser/pipe-err.md):
   Pipes STDERR from the left hand command to STDIN of the right hand command
 * [`err`](../commands/err.md):

docs/parser/logical-or.md

@@ -53,7 +53,7 @@ There is no workaround for `trypipe`.
 * [`&&` And Logical Operator](../parser/logical-and.md):
   Continues next operation if previous operation passes
 * [`?:` Elvis Operator](../parser/elvis.md):
-  Returns the right operand if the left operand is empty
+  Returns the right operand if the left operand is falsy
 * [`?` STDERR Pipe](../parser/pipe-err.md):
   Pipes STDERR from the left hand command to STDIN of the right hand command
 * [`err`](../commands/err.md):

docs/parser/null-coalescing.md

@@ -0,0 +1,84 @@
+# `??` Null Coalescing Operator
+
+> Returns the right operand if the left operand is empty / undefined
+
+## Description
+
+The null coalescing operator is a little like a conditional where the result of the
+operation is the first non-empty value from left to right.
+
+An empty value is any of the following:
+
+* an unset / undefined variable
+* any value with a `null` data type
+
+Other "falsy" values such as numerical values of `0`, boolean `false`, zero
+length strings and strings containing `"null"` are not considered empty by the
+null coalescing operator.
+
+
+
+## Examples
+
+**Assign a variable with a default value:**
+
+```
+» $foo = $bar ?? "baz"
+```
+
+If `$bar` is unset then the value of `$foo` will be **"baz"**.
+
+**Multiple operators:**
+
+```
+» $unset_variable ?? null ?? "foobar"
+foobar
+```
+
+## Detail
+
+The following extract was taken from [Wikipedia](https://en.wikipedia.org/wiki/Null_coalescing_operator):
+
+> The null coalescing operator (called the Logical Defined-Or operator in Perl)
+> is a binary operator that is part of the syntax for a basic conditional
+> expression in several programming languages, including C#, PowerShell as of
+> version 7.0.0, Perl as of version 5.10, Swift, and PHP 7.0.0. While its
+> behavior differs between implementations, the null coalescing operator
+> generally returns the result of its left-most operand if it exists and is not
+> null, and otherwise returns the right-most operand. This behavior allows a
+> default value to be defined for cases where a more specific value is not
+> available.
+>
+> In contrast to the ternary conditional if operator used as `x ? x : y`, but
+> like the binary Elvis operator used as `x ?: y`, the null coalescing operator
+> is a binary operator and thus evaluates its operands at most once, which is
+> significant if the evaluation of `x` has side-effects. 
+
+## See Also
+
+* [Pipeline](../user-guide/pipeline.md):
+  Overview of what a "pipeline" is
+* [Schedulers](../user-guide/schedulers.md):
+  Overview of the different schedulers (or 'run modes') in Murex
+* [`&&` And Logical Operator](../parser/logical-and.md):
+  Continues next operation if previous operation passes
+* [`?:` Elvis Operator](../parser/elvis.md):
+  Returns the right operand if the left operand is falsy
+* [`?` STDERR Pipe](../parser/pipe-err.md):
+  Pipes STDERR from the left hand command to STDIN of the right hand command
+* [`err`](../commands/err.md):
+  Print a line to the STDERR
+* [`out`](../commands/out.md):
+  Print a string to the STDOUT with a trailing new line character
+* [`try`](../commands/try.md):
+  Handles errors inside a block of code
+* [`trypipe`](../commands/trypipe.md):
+  Checks state of each function in a pipeline and exits block on error
+* [`||` Or Logical Operator](../parser/logical-or.md):
+  Continues next operation only if previous operation fails
+* [null](../commands/devnull.md):
+  null function. Similar to /dev/null
+
+<hr/>
+
+This document was generated from [gen/parser/null_coalescing_op_doc.yaml](https://github.com/lmorg/murex/blob/master/gen/parser/null_coalescing_op_doc.yaml).

docs/user-guide/README.md

@@ -94,7 +94,9 @@ The [Language Tour](/tour.md) is a great introduction into the Murex language.
 * [`>>` Append Pipe](parser/pipe-append.md):
   Redirects STDOUT to a file and append its contents
 * [`?:` Elvis Operator](parser/elvis.md):
-  Returns the right operand if the left operand is empty
+  Returns the right operand if the left operand is falsy
+* [`??` Null Coalescing Operator](parser/null-coalescing.md):
+  Returns the right operand if the left operand is empty / undefined
 * [`?` STDERR Pipe](parser/pipe-err.md):
   Pipes STDERR from the left hand command to STDIN of the right hand command
 * [`[..range]`](parser/range.md):

docs/user-guide/rosetta-stone.md

@@ -88,11 +88,11 @@ if you want to learn more about shell scripting in Murex.
 ### Variables
 | Description   | Bash          | Murex  |
 |---------------|---------------|--------|
-| [Printing a variable](../parser/string.md) | `echo "$foobar"` | `out $foobar` [[5]](#footnotes)<br/><br/>`$foobar` <br/><br/> (variables don't need to be quoted in Murex) |
+| [Printing a variable](../parser/scalar.md) | `echo "$foobar"` | `out $foobar` [[5]](#footnotes)<br/><br/>`$foobar` <br/><br/> (variables don't need to be quoted in Murex) |
 | [Assign a local variable](../commands/set.md) | `local foo="bar"` | `$foo = "bar"` [[2]](#footnotes) [[6]](#footnotes)<br/><br/>`out "bar" \| set $foo` |
 | [Assign a global variable](../commands/global.md) | `foo="bar"` | `$GLOBAL.foo = "bar"` [[6]](#footnotes)<br/><br/>`out "bar" \| global $foo` |
 | [Assign an environmental variable](../commands/export.md) | `export foo="bar"` | `export foo = "bar"` [[1]](#footnotes) [[2]](#footnotes) [[3]](#footnotes)<br/><br/>`$ENV.foo = "bar"` [[6]](#footnotes)<br/><br/>`out "bar" \| export $foo` [[3]](#footnotes) |
-| Assign with a default value | `FOOBAR="${VARIABLE:-default}"` | `$foobar = $variable ?: "default"` <br/><br/> (the elvis operator can be used in any part of expressions and just for assignments)
+| [Assign with a default value](../parser/null-coalescing.md) | `FOOBAR="${VARIABLE:-default}"` | `$foobar = $variable ?: "default"` <br/><br/> (the elvis operator can be used in any part of expressions and just for assignments)
 
 ### Arrays
 (eg arrays, lists)

gen/parser/elvis_op_doc.yaml

@@ -3,32 +3,33 @@
     `?:` Elvis Operator
   CategoryID: parser
   Summary: >-
-    Returns the right operand if the left operand is empty
+    Returns the right operand if the left operand is falsy
   Description: |-
     The elvis operator is a little like a conditional where the result of the
-    operation is the first non-empty value from left to right.
+    operation is the first non-falsy value from left to right.
 
-    An empty value is any of the following:
+    A falsy value is any of the following:
     
-    * An unset / undefined variable
-    * Any value with a `null` data type
-
-    Other "falsy" values such as numerical values of `0`, boolean `false`, zero
-    length strings and strings containing `"null"` are not considered empty by the
-    elvis operator.
+    * an unset / undefined variable
+    * any value with a `null` data type
+    * a `str` or generic with the value `false`, `null`, `0`, `no`, `off`, `fail`,
+      `failed`, or `disabled`
+    * a number (`num`, `float` or `int`) with the value `0`
+    * an empty object or zero length array 
+    * and, of course, a boolean with the value `false`
   Examples: |-
     **Assign a variable with a default value:**
 
     ```
     » $foo = $bar ?: "baz"
     ```
 
-    If `$bar` is unset then the value of `$foo` will be **"baz"**.
+    If `$bar` is falsy, then the value of `$foo` will be **"baz"**.
 
     **Multiple elvis operators:**
 
     ```
-    » $unset_variable ?: null ?: "foobar"
+    » $unset_variable ?: null ?: false ?: "foobar"
     foobar
     ```
   Detail: |-
@@ -41,6 +42,7 @@
     > ?:, is viewed sideways, it resembles an emoticon of Elvis Presley with his
     > signature hairstyle.
   Related:
+  - null-coalescing
   - pipe-err
   - pipeline
   - schedulers

gen/parser/null_coalescing_op_doc.yaml

@@ -0,0 +1,62 @@
+- DocumentID: null-coalescing
+  Title: >-
+    `??` Null Coalescing Operator
+  CategoryID: parser
+  Summary: >-
+    Returns the right operand if the left operand is empty / undefined
+  Description: |-
+    The null coalescing operator is a little like a conditional where the result of the
+    operation is the first non-empty value from left to right.
+
+    An empty value is any of the following:
+    
+    * an unset / undefined variable
+    * any value with a `null` data type
+
+    Other "falsy" values such as numerical values of `0`, boolean `false`, zero
+    length strings and strings containing `"null"` are not considered empty by the
+    null coalescing operator.
+  Examples: |-
+    **Assign a variable with a default value:**
+
+    ```
+    » $foo = $bar ?? "baz"
+    ```
+
+    If `$bar` is unset then the value of `$foo` will be **"baz"**.
+
+    **Multiple operators:**
+
+    ```
+    » $unset_variable ?? null ?? "foobar"
+    foobar
+    ```
+  Detail: |-
+    The following extract was taken from [Wikipedia](https://en.wikipedia.org/wiki/Null_coalescing_operator):
+    
+    > The null coalescing operator (called the Logical Defined-Or operator in Perl)
+    > is a binary operator that is part of the syntax for a basic conditional
+    > expression in several programming languages, including C#, PowerShell as of
+    > version 7.0.0, Perl as of version 5.10, Swift, and PHP 7.0.0. While its
+    > behavior differs between implementations, the null coalescing operator
+    > generally returns the result of its left-most operand if it exists and is not
+    > null, and otherwise returns the right-most operand. This behavior allows a
+    > default value to be defined for cases where a more specific value is not
+    > available.
+    >
+    > In contrast to the ternary conditional if operator used as `x ? x : y`, but
+    > like the binary Elvis operator used as `x ?: y`, the null coalescing operator
+    > is a binary operator and thus evaluates its operands at most once, which is
+    > significant if the evaluation of `x` has side-effects. 
+  Related:
+  - elvis
+  - pipe-err
+  - pipeline
+  - schedulers
+  - out
+  - err
+  - try
+  - trypipe
+  - logical-and
+  - logical-or
+  - "null"

gen/user-guide/rosetta-stone.inc.md

@@ -84,11 +84,11 @@ if you want to learn more about shell scripting in Murex.
 ### Variables
 | Description   | Bash          | Murex  |
 |---------------|---------------|--------|
-| [Printing a variable](../parser/string.md) | `echo "$foobar"` | `out $foobar` [[5]](#footnotes)<br/><br/>`$foobar` <br/><br/> (variables don't need to be quoted in Murex) |
+| [Printing a variable](../parser/scalar.md) | `echo "$foobar"` | `out $foobar` [[5]](#footnotes)<br/><br/>`$foobar` <br/><br/> (variables don't need to be quoted in Murex) |
 | [Assign a local variable](../commands/set.md) | `local foo="bar"` | `$foo = "bar"` [[2]](#footnotes) [[6]](#footnotes)<br/><br/>`out "bar" \| set $foo` |
 | [Assign a global variable](../commands/global.md) | `foo="bar"` | `$GLOBAL.foo = "bar"` [[6]](#footnotes)<br/><br/>`out "bar" \| global $foo` |
 | [Assign an environmental variable](../commands/export.md) | `export foo="bar"` | `export foo = "bar"` [[1]](#footnotes) [[2]](#footnotes) [[3]](#footnotes)<br/><br/>`$ENV.foo = "bar"` [[6]](#footnotes)<br/><br/>`out "bar" \| export $foo` [[3]](#footnotes) |
-| Assign with a default value | `FOOBAR="${VARIABLE:-default}"` | `$foobar = $variable ?: "default"` <br/><br/> (the elvis operator can be used in any part of expressions and just for assignments)
+| [Assign with a default value](../parser/null-coalescing.md) | `FOOBAR="${VARIABLE:-default}"` | `$foobar = $variable ?: "default"` <br/><br/> (the elvis operator can be used in any part of expressions and just for assignments)
 
 ### Arrays
 (eg arrays, lists)

lang/expressions/expression.go

@@ -96,10 +96,10 @@ func executeExpression(tree *ParserT, order symbols.Exp) (err error) {
 			err = expAssignMerge(tree)
 
 			// 13. Conditional expression (ternary)
-		case symbols.Elvis:
-			err = expElvis(tree)
 		case symbols.NullCoalescing:
 			err = expNullCoalescing(tree)
+		case symbols.Elvis:
+			err = expElvis(tree)
 
 		// 12. Logical OR
 		case symbols.LogicalOr:

lang/expressions/symbols/exp.go

@@ -54,8 +54,8 @@ const (
 	AssignAndMerge
 
 	// 13. Conditional expression (ternary)
-	NullCoalescing
 	Elvis
+	NullCoalescing
 
 	// 12. Logical OR
 	LogicalOr