main

Author: sharpchen

docs/document/PowerShell/docs/Language/Array.md

@@ -75,6 +75,25 @@ $foo = @{
 @($foo.GetEnumerator()).Length # 2, System.Collections.DictionaryEntry from the HashTable # [!code highlight] 
 ```
 
+### From Range
+
+Range operator can create array from integer range and character range inclusively from both sides.
+
+> [!NOTE]
+> character range was added in PowerShell 6 
+
+```ps1
+1..10 # 1 to 10 inclusively
+'a'..'z' # a to z inclusively
+```
+
+If the *end* is less than the *start*, the array counts down from *start* to *end*
+
+```ps1
+5..1 # 5 4 3 2 1
+5..-1 # 5 4 3 2 1 0 -1
+```
+
 ## Access Item
 
 Powershell allows indexer syntax to access one or more items at a time or use `Select-Object`.

docs/document/PowerShell/docs/Language/Function.md

@@ -1,8 +1,5 @@
 # Function
 
-
-## Parameter
-
 Parameters are wrapped inside a function block with `param(...)`
 
 ```ps1
@@ -17,7 +14,7 @@ function Foo {
 > 
 > Default type of a parameter is `System.Object`.
 
-### Implicit Parameter
+## Implicit Parameter
 
 If no parameter name was set, all value passed in will be captured by `$args`, an `object[]`.
 
@@ -31,7 +28,10 @@ function vim {
 vim ./foo.txt
 ```
 
-### Positional Parameter
+> [!NOTE]
+> `$args` is not available when any of `ParameterAttribute` and `CmdletBinding` is applied on the function.
+
+## Positional Parameter
 
 Positional parameters allows passing values with explicit names.
 
@@ -54,9 +54,9 @@ Or use a explicit position argument on attribute.
 ```ps1
 function Foo {
     param (
-        [Parameter(Position=1)] # [!code highlight] 
+        [Parameter(Position = 1)] # [!code highlight] 
         [string] $Bar
-        [Parameter(Position=0)] # [!code highlight] 
+        [Parameter(Position = 0)] # [!code highlight] 
         [string] $Foo,
     )
     
@@ -67,7 +67,14 @@ Foo -Foo foo -Bar bar
 Foo foo bar # it's the same # [!code highlight] 
 ```
 
-### Flags
+PowerShell starts counting the position when there's a value belonging to no explicit parameter name.
+Assuming `-Flag` is a switch, `-Foo` has position `0`, the value `foo` will be assigned to `-Foo`.
+
+```ps1
+Foo -Flag foo
+```
+
+## Flags
 
 Defining flags that represents a toggle needs a special type called `switch`.
 `switch` has the same nature of `bool`, but `bool` parameter requires explicit assignment when the function being called.
@@ -91,7 +98,7 @@ Manual assignment is also available:
 Foo -f:$false -b $true
 ```
 
-### Default Parameter
+## Default Parameter
 
 - Explicitly typed parameters can have implicit default value.
     - `switch` and `bool` is `$false` by default.
@@ -117,7 +124,7 @@ function Foo {
 > [!NOTE]
 > For overriding default parameter outside the function, see [$PSDefaultParameterValues](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_parameters_default_values?view=powershell-7.4#long-description) 
 
-### Required Parameter
+## Required Parameter
 
 All parameters are optional by default. Use `[Parameter(Mandatory=$true)]` to mark it as required.
 
@@ -137,7 +144,7 @@ param (
 >)
 >```
 
-### Parameter Alias
+## Parameter Alias
 
 Parameters can have aliases. It's not needed for most of time though since pwsh can distinguish option by leading string.
 
@@ -156,7 +163,7 @@ function Person {
 Person -n "Alice" -a 30 # [!code highlight] 
 ```
 
-### Parameter Validation
+## Parameter Validation
 
 Pass a validation logic as script block to `ValidateScript` attribute, `$_` represents singular value of the parameter or current item of a collection.
 Will throw an error if any parameter does not satisfies the condition.
@@ -197,7 +204,7 @@ param (
     )
     ```
 
-### Pass By Reference
+## Pass By Reference
 
 Parameter passed by reference is implemented by a wrapper `System.Management.Automation.PSReference`.
 Value types are passed by value by default, the pass as reference, mark the parameter with `[ref]`.
@@ -278,7 +285,7 @@ A function would generally not acting a cmdlet unless it was annotated with `Cmd
 
 `CmdletBinding()` can have the following properties:
 
-- `DefaultParameterSetName`: name of implicit Parameter Set
+- `DefaultParameterSetName`: pwsh will prefer this name when there's a ambiguity between syntax provided.
 - `HelpURI`: link to documenetation
 - `SupportsPaging`: implicitly adds parameters `-First`, `-Skip`, `-IncludeTotalCount`, value accessible by `$PSCmdlet.PagingParameters`
     ```ps1
@@ -302,7 +309,7 @@ How a same cmdlet manage different syntax for different usages? The trick is **P
 Parameter Set is a classification on paramater to distinguish or limit the use of parameters from scenarios.
 
 - a parameter set must have at least one unique parameter to others to identify the set
-- a parameter can have multiple Parameter Set
+- a parameter can be member of multiple parameter sets.
 - a parameter can have different roles in different Parameter Set, can be mandatory in one and optional in another
 - a parameter without explicit Parameter Set belongs to all other Parameter Set
 - at least one parameter in the Parameter Set is mandatory
@@ -312,7 +319,6 @@ Parameter Set is a classification on paramater to distinguish or limit the use o
 
 `$PSCmdlet.ParameterSetName` reflects the Parameter Set been chosen when a cmdlet is executing with certain syntax.
 
-
 ## Common Parameters
 
 Any function or cmdlet applied with `CmdletBinding()` or `Parameter()` attribute has the following implicit parameters added by PowerShell:
@@ -334,7 +340,7 @@ Any function or cmdlet applied with `CmdletBinding()` or `Parameter()` attribute
 - ProgressAction (proga)
 - OutVariable (ov): declare **inline** and store the output to the variable. Similar to `ev`.
     It's interesting that `-OutVariable` collects incremnentally.
-    It collects new item from pipeline on iteration.
+    It collects new item from pipeline on each iteration.
     ```ps1
     1..5 | % { $_ } -OutVariable foo | % { "I am $foo" }
     # I am 1
@@ -349,14 +355,16 @@ Any function or cmdlet applied with `CmdletBinding()` or `Parameter()` attribute
 - PipelineVariable (pv) <!-- TODO: PipelineVariable -->
 - Verbose (vb): whether display the verbose message from `Write-Verbose`
 
-## Mitigation Parameters
+### Mitigation Parameters
+
+Mitigation parameters were added when `CmdletBinding(SupportsShouldProcess)` was applied.
 
-- WhatIf (wi)
-- Confirm (cf)
+- WhatIf (wi): shows explaination for the command without executing it.
+- Confirm (cf): ask for confirmation when executing the command.
 
 ## Return
 
-Powershell allows implicit return, and multiple implicit returns.
+PowerShell allows implicit return, and multiple implicit returns.
 
 > [!NOTE]
 > Implicit returns are auto-collected as an array or single value.
@@ -400,11 +408,9 @@ PowerShell never do type checking by this attribute, it's just responsible for h
 [OutputType('System.Int32', ParameterSetName = 'ID')]
 [OutputType([string], ParameterSetName = 'Name')]
 param (
-    [Parameter(Mandatory = $true, ParameterSetName = 'ID')]
-    [int[]]
-    $UserID,
-    [Parameter(Mandatory = $true, ParameterSetName = 'Name')]
-    [string[]]
-    $UserName
+    [Parameter(Mandatory, ParameterSetName = 'ID')]
+    [int[]]$UserID,
+    [Parameter(Mandatory, ParameterSetName = 'Name')]
+    [string[]]$UserName
 )
 ```

docs/document/PowerShell/docs/Language/String.md

@@ -136,6 +136,29 @@ All comparison operators have its case-sensitive version with leading `-c`
 (gci -file) -join ',' # ToString is invoked to evaluated objects to string.
 ```
 
+### Join from Objects
+
+`Join-String` is a more generic solution for joining multiple items as a single string.
+`-join` operator handles only collection while `Join-String` can accept pipeline input **by value**.
+
+- `-Property(0)`: pick one property name or script block to be joined in the result
+    ```ps1
+    gci -file | Join-String FullName
+    gci -file | Join-String { $_.FullName }
+    ```
+- `-Separator(1)`: separator between each two properties
+    ```ps1
+    gci -file | Join-String FullName ', '
+    ```
+- `-DoubleQuote`: optionally surround each item by double quote
+- `-SingleQuote`: optionally surround each item by single quote
+- `-OutputPrefix`: specify a initial leading string for the result
+- `-OutputSuffix`: specify a trailing string for the result
+- `-FormatString`: use string format to reshape the string from `-Property`(you can do the similar in `-Property` too)
+    ```ps1
+    gci -file | Join-String Name "$([Environment]::NewLine)" -FormatString 'File name: {0}'
+    ```
+
 ## Match & Replace
 
 PowerShell has two kinds of matching strategy for strings.
@@ -268,15 +291,17 @@ gci | Out-String | sls 'foo' # match the entire string
 gci | oss | sls 'foo' # match the matched line only
 ```
 
-## String Evaluation in Interpolation
+## String Evaluation
 
 ### Collection
 
-Collections like Array and HashTable are formatted by certain separator defined by `$OFS`(Output Field Separator)
+Collections like Array and HashTable are formatted by separator stored in `$OFS`(Output Field Separator)
 
 ```ps1
 "$(1, 2, 3)" # 1 2 3
+$OFS = ', '
+"$(1, 2, 3)" # 1, 2, 3
 ```
 
 > [!NOTE]
-> `$OFS` is not a builtin variable, you'll have to create it manually or pwsh uses space ` ` as the separator.
+> `$OFS` is not a builtin variable, you'll have to create it manually or pwsh uses space ` ` as the default separator.

docs/document/PowerShell/docs/Language/Variable.md

@@ -11,6 +11,35 @@ $var = 'foo'
 echo $var
 ```
 
-## Scope
+## Variable Provider
 
+PowerShell has builtin PSProvider for all variables named `Variable:`
+
+## Item Cmdlet for Variables
+
+You may use Item cmdlets for manipulating variables since they're from a PSDrive.
+Typically useful when manipulating in batch.
+
+When `-ItemType` unspecified and `-Path` were a path from variable drive, `New-Item` creates a variable.
+
+```ps1
+ni -Path Variable:process -Name process -Value (gps)
+```
+
+There's not much necessity for using Item cmdlets for variables, you may use them but it doesn't seem to be straightforward.
+
+## Variable Cmdlet
+
+- `Get-Variable`: retrieve variables from scope
+- `New-Variable`: create variables with more options available
+- `Set-Variable`: override value for variables
+- `Remove-Variable`: delete variables from scope or pattern
+- `Clear-Variable`: set variable to null
+
+> [!NOTE]
+> All these variable cmdlets supports `-Name` that accepts pipeline input by property.
+
+It's more recommended to use variable cmdlets since it supports more parameters to work with
+
+- `Scope`: work with variables in certain scope
 

docs/document/PowerShell/docs/Type System/Extended Type System.md

@@ -17,26 +17,30 @@ There's two kinds of intrinsic members in PowerShell
 All objects in PowerShell have five **object views** members:
 
 - `psobject`: a `MemberSet` containing reflection source of members.
-```ps1
-$foo = 'I am foo'
-[object]::ReferenceEquals($foo, $foo.psobject.BaseObject) # True
-```
+
+    ```ps1
+    $foo = 'I am foo'
+    [object]::ReferenceEquals($foo, $foo.psobject.BaseObject) # True
+    ```
 - `psbase`: a `MemberSet` containing members of the object being wrapped.
-```ps1
-$foo = 'I am foo'
-[object]::ReferenceEquals($foo.ToString, $foo.psbase.ToString) # True
-```
+
+    ```ps1
+    $foo = 'I am foo'
+    [object]::ReferenceEquals($foo.ToString, $foo.psbase.ToString) # True
+    ```
+
 - `psadapted`: a `MemberSet` containing adapted members added by ETS.
 - `psextended`: a `MemberSet` containing extended members **added at runtime**.
 - `pstypenames`: a `CodeProperty` equivalent to `psobject.TypeNames`. Returns a collection containing the type names of inheritance chain.
-```ps1
-$foo = 'I am foo'
-[object]::ReferenceEquals($foo.psobject.TypeNames, $foo.pstypenames) # True
-```
+
+    ```ps1
+    $foo = 'I am foo'
+    [object]::ReferenceEquals($foo.psobject.TypeNames, $foo.pstypenames) # True
+    ```
 
 Intrinsic methods and properties are to mimic singular object and collection in a same form.
-- `Where`: a method for filtering or slicing by condition. See [Where](../Object Manipulation/Where.md) 
-- `ForEach`: a method to perform iteration with certain logic or perform casting all items to target type. See [ForEach](../Object Manipulation/ForEach.md) 
+- `Where`: a method for filtering or slicing by condition. See [Where](/docs/document/PowerShell/docs/Object%20Manipulation/3.Where.md)
+- `ForEach`: a method to perform iteration with certain logic or perform casting all items to target type. See [ForEach](/docs/document/PowerShell/docs/Object%20Manipulation/4.ForEach.md#intrinsic-foreach)
 - `Count`
 - `Length`