Merge pull request #19 from PowershellFrameworkCollective/scopes

Create psfhashtables.md

Author: FriedrichWeinmann

documentation/documents/psframework/utility.md

@@ -7,22 +7,22 @@ title: PSFramework: Utility
 
 ## Synopsis
 
-Utility is the catch-all category for individual commands that do not fit into any more specific category or would be a category ontu themselves.
+Utility is the catch-all category for individual commands and features that do not fit into any more specific category or would be a category ontu themselves.
 
 ## Commands
 
 ### Select-PSFObject
 
 `Select-PSFObject` completely replaces `Select-Object`, offering all of its functionality, but offering greater input comfort and more readable code by avoiding hashtables for simple operations. It also adds the ability to extend an object, rather than building a new object, fully replacing `Add-Member`.
 
- - [Select-PSFObject](utility/select-psfobject.html)
++ [Select-PSFObject](utility/select-psfobject.html)
 
 ### ConvertFrom-PSFArray
 
 `ConvertFrom-PSFArray` converts properties on objects that are collections into a single string.
 This helps with exporting as flat data, e.g. when exporting as csv.
 
- - [ConvertFrom-PSFArray](utility/convertfrom-psfarray.html)
++ [ConvertFrom-PSFArray](utility/convertfrom-psfarray.html)
 
 ### Argument Transformation Attributes
 
@@ -33,10 +33,14 @@ This is where Argument Transformation Attributes can shine:
 
 + [ScriptTransformation](utility/ScriptTransformation.html): Implement your own conversion logic in script.
 
+### PSFramework Hashtables
+
+Hashtables are awesome!
+But they could be even better.
+Introducing the PSFramework Hashtables, extending hashtables to include default values, passing through unknown key or even dynamically calculating the result of an unexpected key!
+
++ [PSFramework Hashtables](utility/psfhashtables.html)
+
 ## Notes
 
 [Back to PSFramework](https://psframework.org/documentation/documents/psframework.html)
-
-| Version | 1.1 |
-| Written on: | 2018-10-23 |
-| Updated on: | 2019-11-07 |

documentation/documents/psframework/utility/psfhashtables.md

@@ -0,0 +1,119 @@
+# PSFHashtables
+
+[Back to utility](http://psframework.org/documentation/documents/psframework/utility.html)
+
+## Synopsis
+
+PSFramework Hashtables - `[PsfHashtable]` - are an extension / improvement over the default `[Hashtable]`.
+They can do everything a regular hashtable can do, but they can also offer alternative options on what to do, when asking for a key _not_ already included in the hashtable.
+
+## Description
+
+The `[PsfHashtable]` data-type was added as a means to make hashtables more powerful and flexible, in many cases replacing the need for switch-statements.
+This can help simplify the code layout significantly.
+
+> Example: The simple hashtable
+
+```powershell
+$organizations = @{
+	LondonHR = 'London'
+	LondonSales = 'London'
+	LondonDev = 'London'
+	NewYorkHR = 'New York'
+	NewYorkSales = 'New York'
+	NewYorkDev = 'New York'
+}
+
+$users | Select-Object Name, Mail, @{
+	Name = 'Users'
+	Expression = {
+		if ($organizations[$_.Organization]) {
+			$organizations[$_.Organization]
+		}
+		else { $_.Organization}
+	}
+}
+```
+
+> Example: PsfHashtable
+
+```powershell
+$organizations = [PsfHashtable]@{
+	LondonHR = 'London'
+	LondonSales = 'London'
+	LondonDev = 'London'
+	NewYorkHR = 'New York'
+	NewYorkSales = 'New York'
+	NewYorkDev = 'New York'
+}
+# If key not known: Return key
+$organizations.EnablePassthru()
+
+$users | Select-Object Name, Mail, @{
+	Name = 'Users'
+	Expression = { $organizations[$_.Organization] }
+}
+```
+
+## Special Features
+
+So, after luring you in with a simple example, what all can the `[PsfHashtable]` do for you?
+
+### PassThru
+
+As shown in the previous example, a `[PsfHashtable]` can be configured to pass through the key, if it is not yet known:
+
+```powershell
+$mapping = [PsfHashtable]@{
+	Answer = 42
+	Conspiracy = 23
+}
+$mapping.EnablePassthru()
+
+$mapping["Answer"] # 42
+$mapping.Answer # 42
+$mapping["Foo"] # Foo
+$mapping.Foo # <nothing>
+```
+
+> Note: One limitation with extending hashtables: The features on unknown keys _only_ work, when using the _index_ notation (e.g. `$mapping["Foo"]`), not the _property_ notation (e.g. `$mapping.Foo`).
+
+### Default Value
+
+Rather than passing through the key, you can also provide a default value to return:
+
+```powershell
+$mapping = [PsfHashtable]@{
+	Answer = 42
+	Conspiracy = 23
+}
+$mapping.SetDefaultValue(1)
+
+$mapping["Answer"] # 42
+$mapping.Answer # 42
+$mapping["Foo"] # 1
+$mapping.Foo # <nothing>
+```
+
+> Note: One limitation with extending hashtables: The features on unknown keys _only_ work, when using the _index_ notation (e.g. `$mapping["Foo"]`), not the _property_ notation (e.g. `$mapping.Foo`).
+
+### Dynamic Value
+
+A third alternative is to provide a custom scriptblock that gets executed on unknown keys:
+
+```powershell
+$mapping = [PsfHashtable]@{
+	Answer = 42
+	Conspiracy = 23
+}
+$mapping.SetCalculator({ $_ * 2 })
+
+$mapping["Answer"] # 42
+$mapping.Answer # 42
+$mapping["Foo"] # FooFoo
+$mapping.Foo # <nothing>
+```
+
+> Note: One limitation with extending hashtables: The features on unknown keys _only_ work, when using the _index_ notation (e.g. `$mapping["Foo"]`), not the _property_ notation (e.g. `$mapping.Foo`).
+
+[Back to utility](http://psframework.org/documentation/documents/psframework/utility.html)