Add Show-ObjectTree cmdlet

docs/Microsoft.PowerShell.ConsoleGuiTools/Show-ObjectTree.md

@@ -0,0 +1,155 @@
+---
+external help file: ConsoleGuiToolsModule.dll-Help.xml
+keywords: powershell,cmdlet
+locale: en-us
+Module Name: Microsoft.PowerShell.ConsoleGuiTools
+ms.date: 07/20/2023
+schema: 2.0.0
+title: Show-ObjectTree
+---
+
+# Show-ObjectTree
+
+## SYNOPSIS
+
+Sends output to an interactive tree in the same console window.
+
+## SYNTAX
+
+```PowerShell
+ Show-ObjectTree [-InputObject <psobject>] [-Title <string>] [-OutputMode {None | Single |
+    Multiple}] [-Filter <string>] [-MinUi] [<CommonParameters>]
+```
+
+## DESCRIPTION
+
+The **Show-ObjectTree** cmdlet sends the output from a command to a tree view window where the output is displayed in an interactive tree.
+
+You can use the following features of the tree to examine your data:
+
+- Quick Filter. Use the Filter box at the top of the window to search the text in the tree. You can search for literals or multiple words. You can use the `-Filter` command to pre-populate the Filter box. The filter uses regular expressions.
+
+For instructions for using these features, type `Get-Help Show-ObjectTree -Full` and see How to Use the Tree View Window Features in the Notes section.
+
+## EXAMPLES
+
+### Example 1: Output processes to a tree view
+
+```PowerShell
+PS C:\> Get-Process | Show-ObjectTree
+```
+
+This command gets the processes running on the local computer and sends them to a tree view window.
+
+### Example 2: Save output to a variable, and then output a tree view
+
+```PowerShell
+PS C:\> ($A = Get-ChildItem -Path $pshome -Recurse) | sot
+```
+
+This command saves its output in a variable and sends it to **Show-ObjectTree**.
+
+The command uses the Get-ChildItem cmdlet to get the files in the Windows PowerShell installation directory and its subdirectories.
+The path to the installation directory is saved in the $pshome automatic variable.
+
+The command uses the assignment operator (=) to save the output in the $A variable and the pipeline operator (|) to send the output to **Show-ObjectTree**.
+
+The parentheses in the command establish the order of operations.
+As a result, the output from the Get-ChildItem command is saved in the $A variable before it is sent to **Show-ObjectTree**.
+
+## PARAMETERS
+
+### -Filter
+Pre-populates the Filter edit box, allowing filtering to be specified on the command line.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -InputObject
+Specifies that the cmdlet accepts input for **Show-ObjectTree**.
+
+When you use the **InputObject** parameter to send a collection of objects to **Show-ObjectTree**, **Show-ObjectTree** treats the collection as one collection object, and it displays one row that represents the collection.
+
+To display the each object in the collection, use a pipeline operator (|) to send objects to **Show-ObjectTree**.
+
+```yaml
+Type: PSObject
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: True (ByValue)
+Accept wildcard characters: False
+```
+
+### -Title
+Specifies the text that appears in the title bar of the **Show-ObjectTree** window.
+
+By default, the title bar displays the command that invokes **Show-ObjectTree**.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -MinUi
+If specified no window frame, filter box, or status bar will be displayed in the **Show-ObjectTree** window.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+### System.Management.Automation.PSObject
+
+You can send any object to this cmdlet.
+
+## OUTPUTS
+
+### None
+
+`Show-ObjectTree` does not output any objects.
+
+## NOTES
+
+* The command output that you send to **Show-ObjectTree** should not be formatted, such as by using the Format-Table or Format-Wide cmdlets. To select properties, use the Select-Object cmdlet.
+
+* Deserialized output from remote commands might not be formatted correctly in the tree view window.
+
+## RELATED LINKS
+
+[Out-File](Out-File.md)
+
+[Out-Printer](Out-Printer.md)
+
+[Out-String](Out-String.md)

src/Microsoft.PowerShell.ConsoleGuiTools/Microsoft.PowerShell.ConsoleGuiTools.psd1

@@ -70,13 +70,13 @@ NestedModules = @()
 FunctionsToExport = @()
 
 # Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.
-CmdletsToExport = @( 'Out-ConsoleGridView' )
+CmdletsToExport = @( 'Out-ConsoleGridView', 'Show-ObjectTree' )
 
 # Variables to export from this module
 VariablesToExport = '*'
 
 # Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export.
-AliasesToExport = @( 'ocgv' )
+AliasesToExport = @( 'ocgv', 'sot' )
 
 # DSC resources to export from this module
 # DscResourcesToExport = @()
@@ -93,7 +93,7 @@ PrivateData = @{
     PSData = @{
 
         # Tags applied to this module. These help with module discovery in online galleries.
-        Tags = @('Console', 'Gui', 'Out-GridView', 'Out-ConsoleGridView', 'Terminal.Gui', 'gui.cs', 'MacOS', 'Windows', 'Linux', 'PSEdition_Core')
+        Tags = @('Console', 'Gui', 'Out-GridView', 'Out-ConsoleGridView', 'Show-ObjectTree', 'Terminal.Gui', 'gui.cs', 'MacOS', 'Windows', 'Linux', 'PSEdition_Core')
 
         # A URL to the license for this module.
         LicenseUri = 'https://github.com/PowerShell/GraphicalTools/blob/master/LICENSE.txt'

src/Microsoft.PowerShell.ConsoleGuiTools/ShowObjectTreeCmdletCommand.cs

@@ -0,0 +1,155 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System;
+using System.Collections;
+using System.Collections.Generic;
+using System.Management.Automation;
+using System.Management.Automation.Internal;
+using OutGridView.Models;
+
+namespace OutGridView.Cmdlet
+{
+    [Cmdlet("Show", "ObjectTree")]
+    [Alias("sot")]
+    public class ShowObjectTreeCmdletCommand : PSCmdlet, IDisposable
+    {
+        #region Properties
+
+        private const string DataNotQualifiedForShowObjectTree = nameof(DataNotQualifiedForShowObjectTree);
+        private const string EnvironmentNotSupportedForShowObjectTree = nameof(EnvironmentNotSupportedForShowObjectTree);
+
+        private List<PSObject> _psObjects = new List<PSObject>();
+
+        #endregion Properties
+
+        #region Input Parameters
+
+        /// <summary>
+        /// This parameter specifies the current pipeline object.
+        /// </summary>
+        [Parameter(ValueFromPipeline = true, HelpMessage = "Specifies the input pipeline object")]
+        public PSObject InputObject { get; set; } = AutomationNull.Value;
+
+        /// <summary>
+        /// Gets/sets the title of the Out-GridView window.
+        /// </summary>
+        [Parameter(HelpMessage = "Specifies the text that appears in the title bar of the Out-ConsoleGridView window. y default, the title bar displays the command that invokes Out-ConsoleGridView.")]
+        [ValidateNotNullOrEmpty]
+        public string Title { get; set; }
+
+        /// <summary>
+        /// gets or sets the initial value for the filter in the GUI
+        /// </summary>
+        [Parameter(HelpMessage = "Pre-populates the Filter edit box, allowing filtering to be specified on the command line. The filter uses regular expressions." )]
+        public string Filter { set; get; }
+
+        /// <summary>
+        /// gets or sets the whether "minimum UI" mode will be enabled
+        /// </summary>
+        [Parameter(HelpMessage = "If specified no window frame, filter box, or status bar will be displayed in the GUI.")]
+        public SwitchParameter MinUI { set; get; }
+        /// <summary>
+        /// gets or sets the whether the Terminal.Gui System.Net.Console-based ConsoleDriver will be used instead of the 
+        /// default platform-specific (Windows or Curses) ConsoleDriver.
+        /// </summary>
+        [Parameter(HelpMessage = "If specified the Terminal.Gui System.Net.Console-based ConsoleDriver (NetDriver) will be used.")]
+        public SwitchParameter UseNetDriver { set; get; }
+
+        /// <summary>
+        /// For the -Debug switch
+        /// </summary>
+        public bool Debug => MyInvocation.BoundParameters.TryGetValue("Debug", out var o);
+
+        #endregion Input Parameters
+
+        // This method gets called once for each cmdlet in the pipeline when the pipeline starts executing
+        protected override void BeginProcessing()
+        {
+            if (Console.IsInputRedirected)
+            {
+                ErrorRecord error = new ErrorRecord(
+                    new PSNotSupportedException("Not supported in this environment (when input is redirected)."),
+                    EnvironmentNotSupportedForShowObjectTree,
+                    ErrorCategory.NotImplemented,
+                    null);
+
+                ThrowTerminatingError(error);
+            }
+        }
+
+        // This method will be called for each input received from the pipeline to this cmdlet; if no input is received, this method is not called
+        protected override void ProcessRecord()
+        {
+            if (InputObject == null || InputObject == AutomationNull.Value)
+            {
+                return;
+            }
+
+            if (InputObject.BaseObject is IDictionary dictionary)
+            {
+                // Dictionaries should be enumerated through because the pipeline does not enumerate through them.
+                foreach (DictionaryEntry entry in dictionary)
+                {
+                    ProcessObject(PSObject.AsPSObject(entry));
+                }
+            }
+            else
+            {
+                ProcessObject(InputObject);
+            }
+        }
+
+        private void ProcessObject(PSObject input)
+        {
+
+            object baseObject = input.BaseObject;
+
+            // Throw a terminating error for types that are not supported.
+            if (baseObject is ScriptBlock ||
+                baseObject is SwitchParameter ||
+                baseObject is PSReference ||
+                baseObject is PSObject)
+            {
+                ErrorRecord error = new ErrorRecord(
+                    new FormatException("Invalid data type for Show-ObjectTree"),
+                    DataNotQualifiedForShowObjectTree,
+                    ErrorCategory.InvalidType,
+                    null);
+
+                ThrowTerminatingError(error);
+            }
+
+            _psObjects.Add(input);
+        }
+
+        // This method will be called once at the end of pipeline execution; if no input is received, this method is not called
+        protected override void EndProcessing()
+        {
+            base.EndProcessing();
+
+            //Return if no objects
+            if (_psObjects.Count == 0)
+            {
+                return;
+            }
+
+            var applicationData = new ApplicationData
+            {
+                Title = Title ?? "Show-ObjectTree",
+                Filter = Filter,
+                MinUI = MinUI,
+                UseNetDriver = UseNetDriver,
+                Debug = Debug,
+                ModuleVersion = MyInvocation.MyCommand.Version.ToString()
+            };
+
+            ShowObjectView.Run(_psObjects, applicationData);
+        }
+
+        public void Dispose()
+        {
+
+        }
+    }
+}