Edit for style, etc.

Author: Sean Wheeler

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

@@ -12,21 +12,20 @@ Describes the operators that are supported by PowerShell.
 
 ## Long description
 
-An operator is a language element that you can use in a command or
-expression. PowerShell supports several types of operators to help you
-manipulate values.
+An operator is a language element that you can use in a command or expression.
+PowerShell supports several types of operators to help you manipulate values.
 
 ### Arithmetic Operators
 
 Use arithmetic operators (`+`, `-`, `*`, `/`, `%`) to calculate values in a
-command or expression. With these operators, you can add, subtract,
-multiply, or divide values, and calculate the remainder (modulus) of a
-division operation.
+command or expression. With these operators, you can add, subtract, multiply,
+or divide values, and calculate the remainder (modulus) of a division
+operation.
 
 The addition operator concatenates elements. The multiplication operator
-returns the specified number of copies of each element. You can use
-arithmetic operators on any .NET type that implements them, such as: `Int`,
-`String`, `DateTime`, `Hashtable`, and Arrays.
+returns the specified number of copies of each element. You can use arithmetic
+operators on any .NET type that implements them, such as: `Int`, `String`,
+`DateTime`, `Hashtable`, and Arrays.
 
 For more information, see [about_Arithmetic_Operators](about_Arithmetic_Operators.md).
 
@@ -40,9 +39,9 @@ For more information, see [about_Assignment_Operators](about_Assignment_Operator
 
 ### Comparison Operators
 
-Use comparison operators (`-eq`, `-ne`, `-gt`, `-lt`, `-le`, `-ge`) to
-compare values and test conditions. For example, you can compare two string
-values to determine whether they are equal.
+Use comparison operators (`-eq`, `-ne`, `-gt`, `-lt`, `-le`, `-ge`) to compare
+values and test conditions. For example, you can compare two string values to
+determine whether they are equal.
 
 The comparison operators also include operators that find or replace patterns
 in text. The (`-match`, `-notmatch`, `-replace`) operators use regular
@@ -51,17 +50,17 @@ expressions, and (`-like`, `-notlike`) use wildcards `*`.
 Containment comparison operators determine whether a test value appears in a
 reference set (`-in`, `-notin`, `-contains`, `-notcontains`).
 
-Bitwise comparison operators (`-bAND`, `-bOR`, `-bXOR`, `-bNOT`) manipulate
-the bit patterns in values.
+Bitwise comparison operators (`-bAND`, `-bOR`, `-bXOR`, `-bNOT`) manipulate the
+bit patterns in values.
 
 For more information, see [about_Comparison_Operators](about_Comparison_Operators.md).
 
 ### Logical Operators
 
 Use logical operators (`-and`, `-or`, `-xor`, `-not`, `!`) to connect
-conditional statements into a single complex conditional. For example, you
-can use a logical `-and` operator to create an object filter with two
-different conditions.
+conditional statements into a single complex conditional. For example, you can
+use a logical `-and` operator to create an object filter with two different
+conditions.
 
 For more information, see [about_Logical_Operators](about_logical_operators.md).
 
@@ -77,9 +76,9 @@ For more information, see [about_Redirection](about_Redirection.md)
 
 ### Split and Join Operators
 
-The `-split` and `-join` operators divide and combine substrings. The
-`-split` operator splits a string into substrings. The `-join` operator
-concatenates multiple strings into a single string.
+The `-split` and `-join` operators divide and combine substrings. The `-split`
+operator splits a string into substrings. The `-join` operator concatenates
+multiple strings into a single string.
 
 For more information, see [about_Split](about_Split.md) and
 [about_Join](about_Join.md).
@@ -93,15 +92,15 @@ For more information, see [about_Type_Operators](about_Type_Operators.md).
 
 ### Unary Operators
 
-Use unary operators to increment or decrement variables or object
-properties and to set integers to positive or negative numbers. For
-example, to increment the variable `$a` from `9` to `10`, you type `$a++`.
+Use unary operators to increment or decrement variables or object properties
+and to set integers to positive or negative numbers. For example, to increment
+the variable `$a` from `9` to `10`, you type `$a++`.
 
 ### Special Operators
 
 Special operators have specific use-cases that do not fit into any other
-operator group. For example, special operators allow you to
-run commands, change a value's data type, or retrieve elements from an array.
+operator group. For example, special operators allow you to run commands,
+change a value's data type, or retrieve elements from an array.
 
 #### Array subexpression operator `@( )`
 
@@ -261,8 +260,8 @@ $job = Start-Job -ScriptBlock {Get-Process -Name pwsh}
 Receive-Job $job -Wait
 ```
 
-If you want to run multiple commands, each in their own background process
-but all on one line, simply place `&` between and after each of the commands.
+If you want to run multiple commands, each in their own background process but
+all on one line, simply place `&` between and after each of the commands.
 
 For more information on PowerShell jobs, see [about_Jobs](about_Jobs.md).
 
@@ -300,18 +299,18 @@ variables that the script creates are added to the current scope.
 > distinguish the dot from the dot (`.`) symbol that represents the current
 > directory.
 
-In the following example, the Sample.ps1 script in the current directory is
-run in the current scope.
+In the following example, the Sample.ps1 script in the current directory is run
+in the current scope.
 
 ```powershell
 . .\sample.ps1
 ```
 
 #### Format operator `-f`
 
-Formats strings by using the format method of string objects. Enter the
-format string on the left side of the operator and the objects to be
-formatted on the right side of the operator.
+Formats strings by using the format method of string objects. Enter the format
+string on the left side of the operator and the objects to be formatted on the
+right side of the operator.
 
 ```powershell
 "{0} {1,-10} {2:N}" -f 1,"hello",[math]::pi
@@ -326,10 +325,10 @@ method and [Composite Formatting](/dotnet/standard/base-types/composite-formatti
 
 #### Index operator `[ ]`
 
-Selects objects from indexed collections, such as arrays and hash tables.
-Array indexes are zero-based, so the first object is indexed as `[0]`. For
-arrays (only), you can also use negative indexes to get the last values.
-Hash tables are indexed by key value.
+Selects objects from indexed collections, such as arrays and hash tables. Array
+indexes are zero-based, so the first object is indexed as `[0]`. For arrays
+(only), you can also use negative indexes to get the last values. Hash tables
+are indexed by key value.
 
 ```
 PS> $a = 1, 2, 3
@@ -365,9 +364,9 @@ Once upon a time...
 
 #### Pipeline operator `|`
 
-Sends ("pipes") the output of the command that precedes it to the command
-that follows it. When the output includes more than one object (a
-"collection"), the pipeline operator sends the objects one at a time.
+Sends ("pipes") the output of the command that precedes it to the command that
+follows it. When the output includes more than one object (a "collection"), the
+pipeline operator sends the objects one at a time.
 
 ```powershell
 Get-Process | Get-Member
@@ -376,8 +375,12 @@ 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.
+> [!NOTE]
+> This is an experimental feature. For more information see
+> [about_Experimental_Features](about_Experimental_Features.md).
+
+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,

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

@@ -14,27 +14,32 @@ 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:
+Beginning in 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](/previous-versions/windows/it-pro/windows-xp/bb490954(v=technet.10)#using-multiple-commands-and-conditional-processing-symbols)
+in the Windows Command Shell (cmd.exe).
+
+The `&&` operator executes the right-hand pipeline, if the left-hand pipeline
+succeeded. Conversely, the `||` operator executes the right-hand pipeline if
+the left-hand pipeline failed.
+
+This can be use for conditional execution of software deployments. For example:
 
 ```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.
+In this example the `npm run deploy` command only runs if the build command
+succeeds.
+
+> [!NOTE]
+> This is an experimental feature. For more information see
+> [about_Experimental_Features](about_Experimental_Features.md).
+
+### Examples
 
 #### Two successful commands
 
@@ -59,7 +64,7 @@ Write-Error 'Bad' && Write-Output 'Second' : Bad
 + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException
 ```
 
-#### First command succeeds, so `||` means second command not executed
+#### First command succeeds, so the second command is not executed
 
 ```powershell
 Write-Output 'First' || Write-Output 'Second'
@@ -69,7 +74,7 @@ Write-Output 'First' || Write-Output 'Second'
 First
 ```
 
-#### First command fails, so `||` means second command is executed
+#### First command fails, so the second command is executed
 
 ```powershell
 Write-Error 'Bad' || Write-Output 'Second'
@@ -83,8 +88,8 @@ Write-Error 'Bad' && Write-Output 'Second' : Bad
 Second
 ```
 
-Pipeline success is defined by the value of the `$?` variable,
-which PowerShell automatically sets after executing a pipeline based on its execution status.
+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
@@ -111,8 +116,8 @@ 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:
+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'
@@ -124,8 +129,8 @@ $result
 2
 ```
 
-If a script-terminating error is thrown during assignment from a pipeline chain,
-the assignment does not succeed:
+If a script-terminating error is thrown during assignment from a pipeline
+chain, the assignment does not succeed:
 
 ```powershell
 try
@@ -146,24 +151,24 @@ Result:
 
 ### Operator syntax and precedence
 
-Unlike other operators, `&&` and `||` operate on pipelines,
-rather than on expressions (like, for example, `+` or `-and`).
+Unlike other operators, `&&` and `||` operate on pipelines, rather than on
+expressions like `+` or `-and`, for example.
 
 `&&` 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.
+but a higher precedence 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 to variables, or separated as statements.
 
-To use lower precedence syntax within a pipeline chain,
-consider the use of parentheses `(...)` or a subexpression `$(...)`.
+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:
+Pipeline chain operators do not absorb errors. When a statement in a pipeline
+chain throws a script-terminating error, the pipeline chain is terminated.
+
+For example:
 
 ```powershell
 $(throw 'Bad') || Write-Output '2'
@@ -178,7 +183,7 @@ At line:1 char:3
 + FullyQualifiedErrorId : Bad
 ```
 
-If the error is caught, the pipeline chain will still be cut short:
+Even when the error is caught, the pipeline chain is still terminated:
 
 ```powershell
 try
@@ -197,9 +202,8 @@ Caught: Bad
 Done
 ```
 
-If an error is non-terminating,
-or only terminates a pipeline,
-the pipeline chain will continue, respecting on `$?`:
+If an error is non-terminating, or only terminates a pipeline, the pipeline
+chain continues, respecting the value of `$?`:
 
 ```powershell
 function Test-NonTerminatingError
@@ -232,10 +236,9 @@ 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:
+Pipeline chain operators, by their name, can be used to chain pipelines, rather
+than just commands. This matches the behavior of other shells, but can make
+*success* harder to determine:
 
 ```powershell
 function Test-NotTwo
@@ -278,9 +281,8 @@ At line:1 char:9
 3
 ```
 
-Note that `Write-Output 'All done!'` is not executed,
-since `Test-NotTwo` is deemed to have failed
-after throwing the non-terminating error.
+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