grrr

Author: sharpchen

docs/document/Powershell/docs/1.Overview.md

@@ -1,5 +1,15 @@
 # Overview
 
+- Integrated with `.NET`
+Reuse almost any type in `.NET`.
 - Dynamic typing
+Powershell adds extra attribute and properties on dotnet types to enhance experience.
 - Case insensitive
+All language syntax, pattern syntax and even strings are case-insensitive.
+(There's exception for file system on non-Windows platform)
 - Everything is object, more than plain text in shell.
+Powershell formats the object value as a table if the object is not a primitive type.
+For primitive type, `Tostring()` will be used instead.
+- Always handle both array and singular object.
+A powershell cmdlet always accepts an array or an single object as input parameter.
+And returns the result as an array or an object too.

docs/document/Powershell/docs/File System/1.Overview.md

@@ -2,8 +2,8 @@
 
 **FileSystem** is a builtin **PSProvider** in Powershell.
 
-FileSystem can have one or more **PSDrive** depends on the system.
+FileSystem can have one or more **PSDrive** depending on the system.
 
 In windows, drives can be `C:`, `D:` and so on. In linux they can be some mount points.
 
-This is introduces how to manipulate file system objects with item-related cmdlet.
+This section introduces how to manipulate file system objects with item-related cmdlet.

docs/document/Powershell/docs/Language/Collection.md

@@ -0,0 +1,5 @@
+# Collection
+
+## Array
+
+## HashTable

docs/document/Powershell/docs/Language/Function.md

@@ -1,5 +1,40 @@
 # Function
 
+## Return
+
+Powershell allows implicit return, and multiple implicit returns.
+
+> [!NOTE]
+> Implicit returns are auto-collected as an array or single value.
+> And it does not print out anything.
+
+```ps1
+[int] function Sum {
+    param([int]$l, [int]$r)
+    $l + $r # implicit return # [!code highlight] 
+}
+
+# You won't need to declare an array and append it on each loop!
+# they're collected automatically as they're implicit returns
+function Foo {
+   for($i = 0; $i -lt 10; $i = $i + 1)  {
+        $i
+   }
+}
+
+(Foo).GetType().Name # object[] # [!code highlight] 
+```
+
+Explicit return is surely supported, but more like a necessity to exit inside a flow.
+
+```ps1
+[int] function Sum {
+    param([int]$l, [int]$r)
+    return $l + $r # explicit return # [!code highlight] 
+    $r + $l # not reachable  # [!code warning] 
+}
+```
+
 ## Parameter
 
 Parameters are wrapped inside a function block with `param(...)`

docs/document/Powershell/docs/Language/Invocation.md

@@ -0,0 +1,36 @@
+# Invocation
+
+> [!CAUTION]
+> Always be careful to run an external script or input script content.
+
+## Call Operator
+
+Call operator `&` can be used for invoking one of the following:
+
+- Command without any option.
+- A `.ps1` script file
+- Script block
+
+**`&` is awared of the context of current session, it does not start a new process.**
+
+It's more like a system execution 
+
+```ps1
+& 'gps'
+& 'gps pwsh' # extra option not allowed # [!code error] 
+& 'gps' pwsh # pass option after command name instead # [!code ++] 
+& 'gps' -Name pwsh # pass option after command name instead # [!code ++] 
+
+& 'path/to/script.ps1' # may add some option...  # [!code highlight] 
+
+& { param($a, $b) $a, $b } 1, 2
+```
+
+## Invoke-Expression
+
+`Invoke-Expression` used for executing any script content represented as a string.
+
+```ps1
+Invoke-Expression 'gps pwsh'
+'gps pwsh' | iex
+```

docs/document/Powershell/docs/Language/PSCustomObject.md

@@ -0,0 +1,45 @@
+# PSCustomObject
+
+**PSCustomObject** is similar to object literal that can even have custom methods.
+
+## Create a PSCustomObject
+
+PSCustomObject borrows the syntax from HashTable with a casting.
+
+```ps1
+$john = [PSCustomObject] @{
+    Name = 'John Smith' 
+    Age = 18
+}
+```
+
+### From a HashTable
+
+You can explicitly convert a HashTable to PSCustomObject
+
+```ps1
+$table = @{
+    Foo = 'foo'
+}
+
+$obj = [PSCustomObject]$table # [!code highlight] 
+```
+
+Or use `New-Object`
+
+```ps1
+$obj = New-Object -TypeName PSObject -Property $table
+```
+
+## Copy a PSCustomObject
+
+- Shallow copy
+
+```ps1
+$john = [PSCustomObject] @{
+    Name = 'John Smith' 
+    Age = 18
+}
+
+$smith = $john.PSObject.Copy()
+```

docs/document/Powershell/docs/Language/Script Block.md

@@ -0,0 +1,36 @@
+# Script Block
+
+**Script Block** is a special object in powerhsell, it looks like a syntax that creates a new scope in the flow, but itself can be stored in a variable.
+So it's more like a anonymous function, you may call it as lambda expression.
+
+```ps1
+$action = {
+    echo 'hello from script block'
+}
+
+$func = {
+    param($foo, $bar)
+    return "$foo$bar"
+}
+```
+
+## Invoke a Script Block
+
+```ps1
+& { 1, 2 }
+# 1
+# 2
+
+& { param($a, $b) $a, $b } 'a' 'b'
+# a
+# b
+```
+
+## Script Block as Lambda
+
+As a replacement for lambda expression, Script Block is being used to work with LINQ api.
+
+```ps1
+$arr = @(1, 2, 3, 5)
+$arr.Where({ $_ -lt 4 })
+```

docs/document/Powershell/docs/Modulization/Modules.md

@@ -23,20 +23,3 @@ Search module to be installed in registered repositories.
 Find-Module <pattern>
 ```
 
-## Custom Module Path
-
-Powershell automatically scans modules at certain locations.
-Inspect existing module path by:
-
-:::code-group
-```ps1[Windows]
-$env:PSModulePath -split ';' # windows
-```
-```ps1[Linux/Mac]
-$env:PSModulePath -split ':' # linux/mac
-```
-:::
-
-```ps1
-$env:PSModulePath += [IO.Path]::PathSeparator + '<path>'
-```

docs/document/Powershell/docs/Object Manipulation/1.Overview.md

@@ -4,6 +4,6 @@ Powershell is a Object-Oriented shell language, so inspection and manipulation o
 
 This section focuses on how to work with objects, including:
 
-- LINQ like transformation over objects.
+- LINQ like transformation over objects.(including usage of `.NET` LINQ in Powershell)
 - Object comparison.
 - Serialization and Deserialization.

docs/document/Powershell/docs/Object Manipulation/Compare Objects.md

@@ -1,5 +1,7 @@
 # Compare Objects
 
+## Overview
+
 > [!TIP]
 > Use `diff` or `compare` alias for `Compare-Object`
 
@@ -46,4 +48,4 @@ diff @('abc', 'dfg') @('fg', 'abc') -Property Length # compare on string.Length
 - `ToString()` and compare on string
 
 > [!TIP]
-> If the object to be compared doesn't implement `IComparable`, you should use `-Property`.
+> If the object to be compared doesn't implement `IComparable`, you should use `-Property` unless it's a primitive type.