feat: Get-WebSocket -WatchFor ( Fixes #29 )

Author: StartAutomating

docs/Get-WebSocket.md

@@ -12,7 +12,7 @@ Get-WebSocket gets a websocket.
 
 This will create a job that connects to a WebSocket and outputs the results.
 
-If the `-Watch` parameter is provided, will output a continous stream of objects from the websocket.
+If the `-Watch` parameter is provided, will output a continous stream of objects.
 
 ---
 
@@ -84,6 +84,40 @@ websocket wss://jetstream2.us-east.bsky.network/subscribe?wantedCollections=app.
         $_.commit.record.embed.external.uri
     }
 ```
+BlueSky, but just the hashtags
+
+```PowerShell
+websocket wss://jetstream2.us-west.bsky.network/subscribe?wantedCollections=app.bsky.feed.post -WatchFor @{
+    {$webSocketoutput.commit.record.text -match "\#\w+"}={
+        $matches.0
+    }                
+}
+```
+BlueSky, but just the hashtags (as links)
+
+```PowerShell
+websocket wss://jetstream2.us-west.bsky.network/subscribe?wantedCollections=app.bsky.feed.post -WatchFor @{
+    {$webSocketoutput.commit.record.text -match "\#\w+"}={
+        if ($psStyle.FormatHyperlink) {
+            $psStyle.FormatHyperlink($matches.0, "https://bsky.app/search?q=$([Web.HttpUtility]::UrlEncode($matches.0))")
+        } else {
+            $matches.0
+        }
+    }
+}
+```
+> EXAMPLE 10
+
+```PowerShell
+websocket wss://jetstream2.us-west.bsky.network/subscribe?wantedCollections=app.bsky.feed.post -WatchFor @{
+    {$args.commit.record.text -match "\#\w+"}={
+        $matches.0
+    }
+    {$args.commit.record.text -match '[\p{IsHighSurrogates}\p{IsLowSurrogates}]+'}={
+        $matches.0
+    }
+}
+```
 
 ---
 
@@ -104,6 +138,7 @@ A ScriptBlock that will handle the output of the WebSocket.
 
 #### **Variable**
 Any variables to declare in the WebSocket job.
+These variables will also be added to the job as properties.
 
 |Type           |Required|Position|PipelineInput|
 |---------------|--------|--------|-------------|
@@ -166,6 +201,15 @@ If set, will watch the output of the WebSocket job, outputting results continuou
 |----------|--------|--------|-------------|-------|
 |`[Switch]`|false   |named   |false        |Tail   |
 
+#### **WatchFor**
+If set, will watch the output of a WebSocket job for one or more conditions.
+The conditions are the keys of the dictionary, and can be a regex, a string, or a scriptblock.
+The values of the dictionary are what will happen when a match is found.
+
+|Type           |Required|Position|PipelineInput|Aliases               |
+|---------------|--------|--------|-------------|----------------------|
+|`[IDictionary]`|false   |named   |false        |WhereFor<br/>Wherefore|
+
 #### **TimeOut**
 The timeout for the WebSocket connection.  If this is provided, after the timeout elapsed, the WebSocket will be closed.
 
@@ -208,5 +252,5 @@ RunspacePools allow you to limit the scope of the handler to a pool of runspaces
 
 ### Syntax
 ```PowerShell
-Get-WebSocket [[-WebSocketUri] <Uri>] [-Handler <ScriptBlock>] [-Variable <IDictionary>] [-Name <String>] [-InitializationScript <ScriptBlock>] [-BufferSize <Int32>] [-OnConnect <ScriptBlock>] [-OnError <ScriptBlock>] [-OnOutput <ScriptBlock>] [-OnWarning <ScriptBlock>] [-Watch] [-TimeOut <TimeSpan>] [-Maximum <Int64>] [-ConnectionTimeout <TimeSpan>] [-Runspace <Runspace>] [-RunspacePool <RunspacePool>] [<CommonParameters>]
+Get-WebSocket [[-WebSocketUri] <Uri>] [-Handler <ScriptBlock>] [-Variable <IDictionary>] [-Name <String>] [-InitializationScript <ScriptBlock>] [-BufferSize <Int32>] [-OnConnect <ScriptBlock>] [-OnError <ScriptBlock>] [-OnOutput <ScriptBlock>] [-OnWarning <ScriptBlock>] [-Watch] [-WatchFor <IDictionary>] [-TimeOut <TimeSpan>] [-Maximum <Int64>] [-ConnectionTimeout <TimeSpan>] [-Runspace <Runspace>] [-RunspacePool <RunspacePool>] [<CommonParameters>]
 ```