Merge branch 'pipeline-chain-operators' of https://github.com/rjmholt/PowerShell-Docs into pipeline-chain-operators

Author: Sean Wheeler

reference/7/Microsoft.PowerShell.Core/About/about_Operators.md

@@ -374,6 +374,22 @@ Get-Process | Get-Member
 Get-PSSnapin | Where-Object {$_.vendor -ne "Microsoft"}
 ```
 
+#### Pipeline chain operators `&&` and `||`
+
+Conditionally execute the right-hand side pipeline
+based on the success of the left-hand side pipeline.
+
+```powershell
+# If Get-Process successfully finds a process called notepad,
+# Stop-Process -Name notepad is called
+Get-Process notepad && Stop-Process -Name notepad
+```
+
+```powershell
+# If npm install fails, the node_modules directory is removed
+npm install || Remove-Item -Recurse ./node_modules
+```
+
 #### Property dereferences operator `.`
 
 Accesses the properties and methods of an object.
@@ -466,6 +482,8 @@ For more information, see [about_If](about_If.md).
 
 [about_Type_Operators](about_Type_Operators.md)
 
+[about_Pipeline_Chain_Operators](about_Pipeline_Chain_Operators.md)
+
 [about_Split](about_Split.md)
 
 [about_Join](about_Join.md)

reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md

@@ -0,0 +1,281 @@
+---
+ms.date:  09/30/2019
+schema:  2.0.0
+locale:  en-us
+keywords:  powershell,cmdlet
+title:  about_Pipeline_Chain_Operators
+---
+
+# About Pipeline Chain Operators
+
+## Short description
+
+Describes chaining pipelines with the `&&` and `||` operators in PowerShell.
+
+## Long description
+
+From PowerShell 7, PowerShell implements the `&&` and `||` operators
+to conditionally chain pipelines.
+These operators are known in PowerShell as *pipeline chain operators*,
+and are similar to [AND-OR lists](https://pubs.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_09_03)
+in POSIX shells like bash, zsh and sh,
+as well as [conditional processing symbols](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-xp/bb490954(v=technet.10)#using-multiple-commands-and-conditional-processing-symbols)
+in Windows' command shell (cmd.exe).
+
+`&&` and `||` allow conditional execution of PowerShell commands and pipelines
+based on the success of the left-hand pipeline.
+In particular, they allow conditional execution of native executables
+based on execution success:
+
+```powershell
+npm run build && npm run deploy
+```
+
+The `&&` operator will execute the right-hand pipeline,
+if the left-hand pipeline succeeded,
+whereas the `||` operator will execute the right-hand pipeline
+if the left-hand pipeline failed:
+
+```powershell
+Write-Output 'First' && Write-Output 'Second'
+```
+
+```Output
+First
+Second
+```
+
+```powershell
+Write-Error 'Bad' && Write-Output 'Second'
+```
+
+```Output
+Write-Error 'Bad' && Write-Output 'Second' : Bad
++ CategoryInfo          : NotSpecified: (:) [Write-Error], WriteErrorException
++ FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException
+```
+
+```powershell
+Write-Output 'First' || Write-Output 'Second'
+```
+
+```Output
+First
+```
+
+```powershell
+Write-Error 'Bad' || Write-Output 'Second'
+```
+
+```Output
+Write-Error 'Bad' && Write-Output 'Second' : Bad
++ CategoryInfo          : NotSpecified: (:) [Write-Error], WriteErrorException
++ FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException
+
+Second
+```
+
+Pipeline success is defined by the value of the `$?` variable,
+which PowerShell automatically sets after executing a pipeline based on its execution status.
+This means that pipeline chain operators have the following equivalence:
+
+```powershell
+Test-Command '1' && Test-Command '2'
+```
+
+works the same as
+
+```powershell
+Test-Command '1'; if ($?) { Test-Command '2' }
+```
+
+and
+
+```powershell
+Test-Command '1' || Test-Command '2'
+```
+
+works the same as
+
+```powershell
+Test-Command '1'; if (-not $?) { Test-Command '2' }
+```
+
+### Assignment from pipeline chains
+
+Assigning a variable from a pipeline chain takes the concatenation
+of all the pipelines in the chain:
+
+```powershell
+$result = Write-Output '1' && Write-Output '2'
+$result
+```
+
+```Output
+1
+2
+```
+
+If a script-terminating error is thrown during assignment from a pipeline chain,
+the assignment does not succeed:
+
+```powershell
+try
+{
+    $result = Write-Output 'Value' && $(throw 'Bad')
+}
+catch
+{
+    # Do nothing, just squash the error
+}
+
+"Result: $result"
+```
+
+```Output
+Result:
+```
+
+### Operator syntax and precedence
+
+Unlike other operators, `&&` and `||` operate on pipelines,
+rather than on expressions (like, for example, `+` or `-and`).
+
+`&&` and `||` have a lower precedence than piping (`|`) or redirection (`>`),
+but a higher precdence than job operators (`&`), assignment (`=`) or semicolons (`;`).
+This means that pipelines within a pipeline chain can be individually redirected,
+and that entire pipeline chains can be backgrounded, assigned from
+or separated as statements.
+
+To use lower precedence syntax within a pipeline chain,
+consider the use of parentheses `(...)` or a subexpression `$(...)`.
+
+### Error interaction
+
+Pipeline chain operators, particularly the `||` operator,
+do not absorb errors.
+If a statement in a pipeline chain throws a script-terminating error,
+that will abort the pipeline chain:
+
+```powershell
+$(throw 'Bad') || Write-Output '2'
+```
+
+```Output
+Bad
+At line:1 char:3
++ $(throw 'Bad') || Write-Output '2'
++   ~~~~~~~~~~~
++ CategoryInfo          : OperationStopped: (Bad:String) [], RuntimeException
++ FullyQualifiedErrorId : Bad
+```
+
+If the error is caught, the pipeline chain will still be cut short:
+
+```powershell
+try
+{
+    $(throw 'Bad') || Write-Output '2'
+}
+catch
+{
+    Write-Output "Caught: $_"
+}
+Write-Output 'Done'
+```
+
+```Output
+Caught: Bad
+Done
+```
+
+If an error is non-terminating,
+or only terminates a pipeline,
+the pipeline chain will continue, respecting on `$?`:
+
+```powershell
+function Test-NonTerminatingError
+{
+    [CmdletBinding()]
+    param()
+
+    $exception = [System.Exception]::new('BAD')
+    $errorId = 'BAD'
+    $errorCategory = 'NotSpecified'
+
+    $errorRecord = [System.Management.Automation.ErrorRecord]::new($exception, $errorId, $errorCategory, $null)
+
+    $PSCmdlet.WriteError($errorRecord)
+}
+
+Test-NonTerminatingError || Write-Output 'Second'
+```
+
+```Output
+Test-NonTerminatingError : BAD
+At line:1 char:1
++ Test-NonTerminatingError || Write-Output 'Second'
++ ~~~~~~~~~~~~~~~~~~~~~~~~
++ CategoryInfo          : NotSpecified: (:) [Test-NonTerminatingError], Exception
++ FullyQualifiedErrorId : BAD,Test-NonTerminatingError
+
+Second
+```
+
+### Chaining pipelines rather than commands
+
+Pipeline chain operators, by their name, can be used to chain pipelines,
+rather than just commands.
+This matches the behaviour of other shells,
+but can make "success" harder to reason about:
+
+```powershell
+function Test-NotTwo
+{
+    [CmdletBinding()]
+    param(
+      [Parameter(ValueFromPipeline)]
+      $Input
+    )
+
+    process
+    {
+        if ($Input -ne 2)
+        {
+            return $Input
+        }
+
+        $exception = [System.Exception]::new('Input is 2')
+        $errorId = 'InputTwo'
+        $errorCategory = 'InvalidData'
+
+        $errorRecord = [System.Management.Automation.ErrorRecord]::new($exception, $errorId, $errorCategory, $null)
+
+        $PSCmdlet.WriteError($errorRecord)
+    }
+}
+
+1,2,3 | Test-NotTwo && Write-Output 'All done!'
+```
+
+```Output
+1
+Test-NotTwo : Input is 2
+At line:1 char:9
++ 1,2,3 | Test-NotTwo && Write-Output 'All done!'
++         ~~~~~~~~~~~
++ CategoryInfo          : InvalidData: (:) [Test-NotTwo], Exception
++ FullyQualifiedErrorId : InputTwo,Test-NotTwo
+
+3
+```
+
+Note that `Write-Output 'All done!'` is not executed,
+since `Test-NotTwo` is deemed to have failed
+after throwing the non-terminating error.
+
+## See also
+
+- [about_Operators](about_Operators.md)
+- [about_Automatic_Variables](about_Automatic_Variables.md)
+- [about_pipelines](about_pipelines.md)