From 3a185cef39df29043dd4d671b9c64690b6cb6961 Mon Sep 17 00:00:00 2001 From: Tig Date: Thu, 12 Jun 2025 12:33:31 -0600 Subject: [PATCH 1/2] Migrating api docs for v1 --- .github/workflows/api-docs.yml | 17 +++++++++-------- docfx/docs/index.md | 5 +++-- docfx/docs/toc.yml | 2 +- docfx/index.md | 3 ++- docfx/toc.yml | 4 ++-- 5 files changed, 17 insertions(+), 14 deletions(-) diff --git a/.github/workflows/api-docs.yml b/.github/workflows/api-docs.yml index 92caf5b21..8682a33ab 100644 --- a/.github/workflows/api-docs.yml +++ b/.github/workflows/api-docs.yml @@ -1,9 +1,8 @@ -name: Build and publish API docs +name: Build and publish v1 API docs on: push: - # only publish v2 (main or develop); v2 is published via the Terminal.GuiV2Docs repo - branches: [v1_release, v1_develop] + branches: [v1_release] paths: - docfx/** @@ -12,7 +11,6 @@ permissions: pages: write jobs: - # Single deploy job since we're just deploying deploy: name: Build and Deploy API docs to github-pages environment: @@ -40,8 +38,11 @@ jobs: with: path: docfx/_site - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v3 + - name: v1_release Repository Dispatch ${{ github.ref_name }} + if: github.ref_name == 'v1_release' + uses: peter-evans/repository-dispatch@v3 with: - token: ${{ secrets.GITHUB_TOKEN }} + token: ${{ secrets.V2DOCS_TOKEN }} + repository: gui-cs/Terminal.GuiV1Docs + event-type: v2_develop_push + client-payload: '{"ref": "${{ github.ref }}", "sha": "${{ github.sha }}"}' \ No newline at end of file diff --git a/docfx/docs/index.md b/docfx/docs/index.md index abe755b6d..716544b46 100644 --- a/docfx/docs/index.md +++ b/docfx/docs/index.md @@ -1,6 +1,7 @@ -# Conceptual Documentation +# Conceptual Documentation for Terminal.Gui v1 -**These are the v1 API docs**. The v2 API docs are [here](https://gui-cs.github.io/Terminal.GuiV2Docs/). +> [!NOTE] +> This is the v1 API documentation. For v2 go here: https://gui-cs.github.io/Terminal.Gui * [Terminal.Gui Overview](overview.md) * [List of Views](views.md) diff --git a/docfx/docs/toc.yml b/docfx/docs/toc.yml index a340d5c0e..6d3c41977 100644 --- a/docfx/docs/toc.yml +++ b/docfx/docs/toc.yml @@ -1,4 +1,4 @@ -- name: API Reference +- name: v1 API Reference href: api/Terminal.Gui/ - name: Terminal.Gui Overview href: overview.md diff --git a/docfx/index.md b/docfx/index.md index ab77217b5..558778c28 100644 --- a/docfx/index.md +++ b/docfx/index.md @@ -1,6 +1,7 @@ # Terminal.Gui v1 - Cross Platform Terminal UI toolkit for .NET -**These are the v1 API docs**. The v2 API docs are [here](https://gui-cs.github.io/Terminal.GuiV2Docs/). +> [!NOTE] +> This is the v1 API documentation. For v2 go here: https://gui-cs.github.io/Terminal.Gui A toolkit for building rich console apps for .NET, .NET Core, and Mono that works on Windows, the Mac, and Linux/Unix. diff --git a/docfx/toc.yml b/docfx/toc.yml index 08496c756..56400d403 100644 --- a/docfx/toc.yml +++ b/docfx/toc.yml @@ -2,9 +2,9 @@ href: docs/overview.md - name: Conceptual Docs href: docs/index.md -- name: API Reference +- name: v1 API Reference href: api/Terminal.Gui # - name: UI Catalog API # href: api/UICatalog/ - name: Source - href: https://github.com/gui-cs/Terminal.Gui + href: https://github.com/gui-cs/Terminal.Gui/tree/v1_release From bfb6252a49dbc0502738b6e16c80979f1bc73671 Mon Sep 17 00:00:00 2001 From: Tig Date: Thu, 12 Jun 2025 12:39:01 -0600 Subject: [PATCH 2/2] Migrating api docs for v1 2 --- Scripts/Terminal.Gui.PowerShell.Build.psd1 | 131 ++++++++++++++++++ Scripts/Terminal.Gui.PowerShell.Build.psm1 | 32 +++++ Scripts/Terminal.Gui.PowerShell.Core.psd1 | 138 +++++++++++++++++++ Scripts/Terminal.Gui.PowerShell.Core.psm1 | 145 ++++++++++++++++++++ Scripts/Terminal.Gui.PowerShell.Git.psd1 | 135 +++++++++++++++++++ Scripts/Terminal.Gui.PowerShell.Git.psm1 | 111 +++++++++++++++ Scripts/Terminal.Gui.PowerShell.psd1 | 150 +++++++++++++++++++++ 7 files changed, 842 insertions(+) create mode 100644 Scripts/Terminal.Gui.PowerShell.Build.psd1 create mode 100644 Scripts/Terminal.Gui.PowerShell.Build.psm1 create mode 100644 Scripts/Terminal.Gui.PowerShell.Core.psd1 create mode 100644 Scripts/Terminal.Gui.PowerShell.Core.psm1 create mode 100644 Scripts/Terminal.Gui.PowerShell.Git.psd1 create mode 100644 Scripts/Terminal.Gui.PowerShell.Git.psm1 create mode 100644 Scripts/Terminal.Gui.PowerShell.psd1 diff --git a/Scripts/Terminal.Gui.PowerShell.Build.psd1 b/Scripts/Terminal.Gui.PowerShell.Build.psd1 new file mode 100644 index 000000000..97395c3a8 --- /dev/null +++ b/Scripts/Terminal.Gui.PowerShell.Build.psd1 @@ -0,0 +1,131 @@ +@{ + +# No root module because this is a manifest module. +RootModule = '' + +# Version number of this module. +ModuleVersion = '1.0.0' + +# Supported PSEditions +CompatiblePSEditions = @('Core') + +# ID used to uniquely identify this module +GUID = 'c4a1de77-83fb-45a3-b1b5-18d275ef3601' + +# Author of this module +Author = 'Brandon Thetford (GitHub @dodexahedron)' + +# Company or vendor of this module +CompanyName = 'The Terminal.Gui Project' + +# Copyright statement for this module +Copyright = 'Brandon Thetford (GitHub @dodexahedron), provided to the Terminal.Gui project and you under the MIT license' + +# Description of the functionality provided by this module +Description = 'Build helper functions for Terminal.Gui.' + +# Minimum version of the PowerShell engine required by this module +PowerShellVersion = '7.4.0' + +# Name of the PowerShell "host" subsystem (not system host name). Helps ensure that we know what to expect from the environment. +PowerShellHostName = 'ConsoleHost' + +# Minimum version of the PowerShell host required by this module +PowerShellHostVersion = '7.4.0' + +# Processor architecture (None, MSIL, X86, IA64, Amd64, Arm, or an empty string) required by this module. One value only. +# Set to AMD64 here because development on Terminal.Gui isn't really supported on anything else. +# Has nothing to do with runtime use of Terminal.Gui. +ProcessorArchitecture = '' + +# Modules that must be imported into the global environment prior to importing this module +RequiredModules = @( + @{ + ModuleName='Microsoft.PowerShell.Utility' + ModuleVersion='7.0.0' + }, + @{ + ModuleName='Microsoft.PowerShell.Management' + ModuleVersion='7.0.0' + }, + @{ + ModuleName='PSReadLine' + ModuleVersion='2.3.4' + }, + "./Terminal.Gui.PowerShell.Core.psd1" +) + +# Assemblies that must be loaded prior to importing this module +# RequiredAssemblies = @() + +# Script files (.ps1) that are run in the caller's environment prior to importing this module. +# ScriptsToProcess = @() + +# Type files (.ps1xml) to be loaded when importing this module +# TypesToProcess = @() + +# Format files (.ps1xml) to be loaded when importing this module +# FormatsToProcess = @() + +# Modules to import as nested modules. +NestedModules = @('./Terminal.Gui.PowerShell.Build.psm1') + +# Functions to export from this module. +FunctionsToExport = @('Build-TerminalGui') + +# Cmdlets to export from this module. +CmdletsToExport = @() + +# Variables to export from this module +VariablesToExport = @() + +# Aliases to export from this module. +AliasesToExport = @() + +# List of all modules packaged with this module +# ModuleList = @() + +# List of all files packaged with this module +# FileList = @() + +# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell. +PrivateData = @{ + + PSData = @{ + + # Tags applied to this module. These help with module discovery in online galleries. + # Tags = @() + + # A URL to the license for this module. + LicenseUri = 'https://github.com/gui-cs/Terminal.Gui/tree/v2_develop/Scripts/COPYRIGHT' + + # A URL to the main website for this project. + ProjectUri = 'https://github.com/gui-cs/Terminal.Gui' + + # A URL to an icon representing this module. + # IconUri = '' + + # ReleaseNotes of this module + ReleaseNotes = 'See change history and releases for Terminal.Gui on GitHub' + + # Prerelease string of this module + # Prerelease = '' + + # Flag to indicate whether the module requires explicit user acceptance for install/update/save + RequireLicenseAcceptance = $false + + # External dependent modules of this module + # ExternalModuleDependencies = @() + + } # End of PSData hashtable + +} # End of PrivateData hashtable + +# HelpInfo URI of this module +# HelpInfoURI = '' + +# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix. +# DefaultCommandPrefix = '' + +} + diff --git a/Scripts/Terminal.Gui.PowerShell.Build.psm1 b/Scripts/Terminal.Gui.PowerShell.Build.psm1 new file mode 100644 index 000000000..538b89548 --- /dev/null +++ b/Scripts/Terminal.Gui.PowerShell.Build.psm1 @@ -0,0 +1,32 @@ +<# + .SYNOPSIS + Builds the Terminal.Gui library. + .DESCRIPTION + Builds the Terminal.Gui library. + Optional parameter sets are available to customize the build. + .PARAMETER versionBase + The base version for the Terminal.Gui library. +#> +Function Build-TerminalGui { + [CmdletBinding(SupportsShouldProcess, PositionalBinding=$false, DefaultParameterSetName="Basic", ConfirmImpact="Medium")] + [OutputType([bool],[PSObject])] + param( + [Parameter(Mandatory=$true)] + [Version]$versionBase, + [Parameter(Mandatory=$true, ParameterSetName="Custom")] + [switch]$Custom, + [Parameter(Mandatory=$false, ParameterSetName="Custom")] + [ValidateSet("Debug", "Release")] + [string]$slnBuildConfiguration = "Release", + [Parameter(Mandatory=$false, ParameterSetName="Custom")] + [ValidateSet("Any CPU", "x86"<#, "x64" #>)] + [string]$slnBuildPlatform = "Any CPU" + ) + + if(!$PSCmdlet.ShouldProcess("Building in $slnBuildConfiguration configuration for $slnBuildPlatform", "Terminal.Gui", "BUILDING")) { + return $null + } + + Write-Host NOT IMPLEMENTED. No Action has been taken. + return $false +} diff --git a/Scripts/Terminal.Gui.PowerShell.Core.psd1 b/Scripts/Terminal.Gui.PowerShell.Core.psd1 new file mode 100644 index 000000000..541265ee8 --- /dev/null +++ b/Scripts/Terminal.Gui.PowerShell.Core.psd1 @@ -0,0 +1,138 @@ +# +# Module manifest for module 'Terminal.Gui.PowerShell' +# +# Generated by: Brandon Thetford (GitHub @dodexahedron) +# +# Generated on: 4/19/2024 +# + +@{ + +# No root module because this is a manifest module. +RootModule = '' + +# Version number of this module. +ModuleVersion = '1.0.0' + +# Supported PSEditions +CompatiblePSEditions = @('Core') + +# ID used to uniquely identify this module +GUID = 'c661fb12-70ae-4a9e-a95c-786a7980681d' + +# Author of this module +Author = 'Brandon Thetford (GitHub @dodexahedron)' + +# Company or vendor of this module +CompanyName = 'The Terminal.Gui Project' + +# Copyright statement for this module +Copyright = 'Brandon Thetford (GitHub @dodexahedron), provided to the Terminal.Gui project and you under the MIT license' + +# Description of the functionality provided by this module +Description = 'Utilities for development-time operations on and management of components of Terminal.Gui code and other assets.' + +# Minimum version of the PowerShell engine required by this module +PowerShellVersion = '7.4.0' + +# Name of the PowerShell "host" subsystem (not system host name). Helps ensure that we know what to expect from the environment. +PowerShellHostName = 'ConsoleHost' + +# Minimum version of the PowerShell host required by this module +PowerShellHostVersion = '7.4.0' + +# Processor architecture (None, MSIL, X86, IA64, Amd64, Arm, or an empty string) required by this module. One value only. +# Set to AMD64 here because development on Terminal.Gui isn't really supported on anything else. +# Has nothing to do with runtime use of Terminal.Gui. +ProcessorArchitecture = '' + +# Modules that must be imported into the global environment prior to importing this module +RequiredModules = @( + @{ + ModuleName='Microsoft.PowerShell.Utility' + ModuleVersion='7.0.0' + }, + @{ + ModuleName='Microsoft.PowerShell.Management' + ModuleVersion='7.0.0' + }, + @{ + ModuleName='PSReadLine' + ModuleVersion='2.3.4' + } +) + +# Assemblies that must be loaded prior to importing this module +# RequiredAssemblies = @() + +# Script files (.ps1) that are run in the caller's environment prior to importing this module. +# ScriptsToProcess = @() + +# Type files (.ps1xml) to be loaded when importing this module +# TypesToProcess = @() + +# Format files (.ps1xml) to be loaded when importing this module +# FormatsToProcess = @() + +# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess +NestedModules = @('./Terminal.Gui.PowerShell.Core.psm1') + +# Functions to export from this module. +FunctionsToExport = @('Open-Solution','Close-Solution') + +# 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 = @() + +# 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 = @() + +# List of all modules packaged with this module +# ModuleList = @() + +# List of all files packaged with this module +# FileList = @() + +# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell. +PrivateData = @{ + + PSData = @{ + + # Tags applied to this module. These help with module discovery in online galleries. + # Tags = @() + + # A URL to the license for this module. + LicenseUri = 'https://github.com/gui-cs/Terminal.Gui/tree/v2_develop/Scripts/COPYRIGHT' + + # A URL to the main website for this project. + ProjectUri = 'https://github.com/gui-cs/Terminal.Gui' + + # A URL to an icon representing this module. + # IconUri = '' + + # ReleaseNotes of this module + ReleaseNotes = 'See change history and releases for Terminal.Gui on GitHub' + + # Prerelease string of this module + # Prerelease = '' + + # Flag to indicate whether the module requires explicit user acceptance for install/update/save + RequireLicenseAcceptance = $false + + # External dependent modules of this module + # ExternalModuleDependencies = @() + + } # End of PSData hashtable + +} # End of PrivateData hashtable + +# HelpInfo URI of this module +# HelpInfoURI = '' + +# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix. +# DefaultCommandPrefix = '' + +} + diff --git a/Scripts/Terminal.Gui.PowerShell.Core.psm1 b/Scripts/Terminal.Gui.PowerShell.Core.psm1 new file mode 100644 index 000000000..6a53e10c5 --- /dev/null +++ b/Scripts/Terminal.Gui.PowerShell.Core.psm1 @@ -0,0 +1,145 @@ +<# + .SYNOPSIS + (Windows Only) Opens Visual Studio and loads Terminal.sln. + .DESCRIPTION + (Windows Only) Opens Visual Studio and loads Terminal.sln. + .PARAMETER SolutionFilePath + (Optional) If specified, the path to the solution file. Typically unnecessary to supply this parameter. + .INPUTS + None + .OUTPUTS + None +#> +Function Open-Solution { + [CmdletBinding()] + param( + [Parameter(Mandatory=$false, HelpMessage="The path to the solution file to open.")] + [ValidatePattern(".*Terminal\.sln" )] + [string]$Path = $SolutionFilePath + ) + + if(!$IsWindows) { + [string]$warningMessage = "The Open-Solution cmdlet is only supported on Windows.`n` + Attempt to open file $Path with the system default handler?" + + Write-Warning $warningMessage -WarningAction Inquire + } + + Invoke-Item $Path + return +} + +<# + .SYNOPSIS + (Windows Only) Closes Visual Studio processes with Terminal.sln loaded. + .DESCRIPTION + (Windows Only) Closes Visual Studio processes with Terminal.sln loaded by finding any VS processes launched with the solution file or with 'Terminal' in their main window titles. + .INPUTS + None + .OUTPUTS + None +#> +Function Close-Solution { + $vsProcesses = Get-Process -Name devenv | Where-Object { ($_.CommandLine -Match ".*Terminal\.sln.*" -or $_.MainWindowTitle -Match "Terminal.*") } + Stop-Process -InputObject $vsProcesses + Remove-Variable vsProcesses +} + +<# + .SYNOPSIS + Sets up a standard environment for other Terminal.Gui.PowerShell scripts and modules. + .DESCRIPTION + Configures environment variables and global variables for other Terminal.Gui.PowerShell scripts to use. + Also modifies the prompt to indicate the session has been altered. + Reset changes by exiting the session or by calling Reset-PowerShellEnvironment or ./ResetEnvironment.ps1. + .PARAMETER Debug + Minimally supported for Write-Debug calls in this function only. + .NOTES + Mostly does not respect common parameters like WhatIf, Confirm, etc. + This is just meant to be called by other scripts. + Calling this manually is not supported. +#> +Function Set-PowerShellEnvironment { + [CmdletBinding()] + param() + + # Set up some common globals + New-Variable -Name ScriptsDirectory -Value $PSScriptRoot -Option ReadOnly -Scope Global -Visibility Public + New-Variable -Name RepositoryRootDirectory -Value (Join-Path -Resolve $ScriptsDirectory "..") -Option ReadOnly -Scope Global -Visibility Public + New-Variable -Name SolutionFilePath -Value (Join-Path -Resolve $RepositoryRootDirectory "Terminal.sln") -Option ReadOnly -Scope Global -Visibility Public + New-Variable -Name TerminalGuiProjectDirectory -Value (Join-Path -Resolve $RepositoryRootDirectory "Terminal.Gui") -Option ReadOnly -Scope Global -Visibility Public + New-Variable -Name TerminalGuiProjectFilePath -Value (Join-Path -Resolve $TerminalGuiProjectDirectory "Terminal.Gui.csproj") -Option ReadOnly -Scope Global -Visibility Public + + # Save existing PSModulePath for optional reset later. + # If it is already saved, do not overwrite, but continue anyway. + New-Variable -Name OriginalPSModulePath -Visibility Public -Option ReadOnly -Scope Global -Value ($Env:PSModulePath) -ErrorAction SilentlyContinue + Write-Debug -Message "`$OriginalPSModulePath is $OriginalPSModulePath" -Debug:$DebugPreference + + # Get platform-specific path variable entry separator. Continue if it's already set. + New-Variable -Name PathVarSeparator -Visibility Public -Option ReadOnly -Scope Global -Value ";" -Description 'Separator character used in environment variables such as $Env:PSModulePath' -ErrorAction SilentlyContinue + + if(!$IsWindows) { + $PathVarSeparator = ':' + } + Write-Debug -Message "`$PathVarSeparator is $PathVarSeparator" -Debug:$DebugPreference + + # If Env:PSModulePath already has the current path, don't append it again. + if($Env:PSModulePath -notlike "*$((Resolve-Path .).Path)*") { + Write-Debug -Message "Appending $((Resolve-Path .).Path) to `$Env:PSModulePath" -Debug:$DebugPreference + $env:PSModulePath = Join-String -Separator $PathVarSeparator -InputObject @( $env:PSModulePath, (Resolve-Path .).Path ) + } + Write-Debug -Message "`$Env:PSModulePath is $Env:PSModulePath" -Debug:$DebugPreference +} + + +<# + .SYNOPSIS + Resets changes made by ConfigureEnvironment.pst to the current PowerShell environment. + .DESCRIPTION + Optional function to undo changes to the current session made by ConfigureEnvironment.ps1. + Changes only affect the current session, so exiting will also "reset." + .PARAMETER Exit + Switch parameter that, if specified, exits the current PowerShell environment. + Does not bother doing any other operations, as none are necessary. + .INPUTS + None + .OUTPUTS + None + .EXAMPLE + Reset-PowerShellEnvironment + To undo changes in the current session. + .EXAMPLE + Reset-PowerShellEnvironment -Exit + To exit the current session. Same as simply using the Exit command. +#> +Function Reset-PowerShellEnvironment { + [CmdletBinding(DefaultParameterSetName="Basic")] + param( + [Parameter(Mandatory=$false, ParameterSetName="Basic")] + [switch]$Exit + ) + + if($Exit) { + [Environment]::Exit(0) + } + + if(Get-Variable -Name OriginalPSModulePath -Scope Global -ErrorAction SilentlyContinue){ + $Env:PSModulePath = $OriginalPSModulePath + Remove-Variable -Name OriginalPSModulePath -Scope Global -Force -ErrorAction SilentlyContinue + } + + Remove-Variable -Name PathVarSeparator -Scope Global -Force -ErrorAction SilentlyContinue + Remove-Variable -Name RepositoryRootDirectory -Scope Global -Force -ErrorAction SilentlyContinue + Remove-Variable -Name SolutionFilePath -Scope Global -Force -ErrorAction SilentlyContinue + Remove-Variable -Name TerminalGuiProjectDirectory -Scope Global -Force -ErrorAction SilentlyContinue + Remove-Variable -Name TerminalGuiProjectFilePath -Scope Global -Force -ErrorAction SilentlyContinue + Remove-Variable -Name ScriptsDirectory -Scope Global -Force -ErrorAction SilentlyContinue +} + +# This ensures the environment is reset when unloading the module. +# Without this, function:prompt will be undefined. +$MyInvocation.MyCommand.ScriptBlock.Module.OnRemove = { + Reset-PowerShellEnvironment +} + +Set-PowerShellEnvironment diff --git a/Scripts/Terminal.Gui.PowerShell.Git.psd1 b/Scripts/Terminal.Gui.PowerShell.Git.psd1 new file mode 100644 index 000000000..afca6f69b --- /dev/null +++ b/Scripts/Terminal.Gui.PowerShell.Git.psd1 @@ -0,0 +1,135 @@ +# +# Module manifest for module 'Terminal.Gui.PowerShell.Git' +# +# Generated by: Brandon Thetford +# +# Generated on: 4/26/2024 +# + +@{ + +# Script module or binary module file associated with this manifest. +RootModule = '' + +# Version number of this module. +ModuleVersion = '1.0.0' + +# Supported PSEditions +CompatiblePSEditions = 'Core' + +# ID used to uniquely identify this module +GUID = '33a6c4c9-c0a7-4c09-b171-1da0878f93ea' + +# Author of this module +Author = 'Brandon Thetford (GitHub @dodexahedron)' + +# Company or vendor of this module +CompanyName = 'The Terminal.Gui Project' + +# Copyright statement for this module +Copyright = 'Brandon Thetford (GitHub @dodexahedron), provided to the Terminal.Gui project and you under the MIT license' + +# Description of the functionality provided by this module +Description = 'Simple helper commands for common git operations.' + +# Minimum version of the PowerShell engine required by this module +PowerShellVersion = '7.4' + +# Name of the PowerShell host required by this module +PowerShellHostName = 'ConsoleHost' + +# Minimum version of the PowerShell host required by this module +PowerShellHostVersion = '7.4.0' + +# Processor architecture (None, MSIL, X86, IA64, Amd64, Arm, or an empty string) required by this module. One value only. +# Set to AMD64 here because development on Terminal.Gui isn't really supported on anything else. +# Has nothing to do with runtime use of Terminal.Gui. +ProcessorArchitecture = '' + +# Modules that must be imported into the global environment prior to importing this module +RequiredModules = @( + @{ + ModuleName='Microsoft.PowerShell.Utility' + ModuleVersion='7.0.0' + }, + @{ + ModuleName='Microsoft.PowerShell.Management' + ModuleVersion='7.0.0' + }, + @{ + ModuleName='PSReadLine' + ModuleVersion='2.3.4' + } +) + +# Script files (.ps1) that are run in the caller's environment prior to importing this module. +ScriptsToProcess = @() + +# Type files (.ps1xml) to be loaded when importing this module +TypesToProcess = @() + +# Format files (.ps1xml) to be loaded when importing this module +FormatsToProcess = @() + +# Modules to import as nested modules. +NestedModules = @("./Terminal.Gui.PowerShell.Git.psm1") + +# Functions to export from this module. +FunctionsToExport = @('New-GitBranch') + +# 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 = @() + +# 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 = @() + +# DSC resources to export from this module +DscResourcesToExport = @() + +# List of all modules packaged with this module +ModuleList = @('./Terminal.Gui.PowerShell.Git.psm1') + +# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell. +PrivateData = @{ + + PSData = @{ + + # Tags applied to this module. These help with module discovery in online galleries. + # Tags = @() + + # A URL to the license for this module. + # LicenseUri = '' + + # A URL to the main website for this project. + # ProjectUri = '' + + # A URL to an icon representing this module. + # IconUri = '' + + # ReleaseNotes of this module + # ReleaseNotes = '' + + # Prerelease string of this module + # Prerelease = '' + + # Flag to indicate whether the module requires explicit user acceptance for install/update/save + # RequireLicenseAcceptance = $false + + # External dependent modules of this module + # ExternalModuleDependencies = @() + + } # End of PSData hashtable + +} # End of PrivateData hashtable + +# HelpInfo URI of this module +# HelpInfoURI = '' + +# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix. +# DefaultCommandPrefix = '' + +} + diff --git a/Scripts/Terminal.Gui.PowerShell.Git.psm1 b/Scripts/Terminal.Gui.PowerShell.Git.psm1 new file mode 100644 index 000000000..ef5f9c743 --- /dev/null +++ b/Scripts/Terminal.Gui.PowerShell.Git.psm1 @@ -0,0 +1,111 @@ +<# + .SYNOPSIS + Creates a new branch with the specified name. + .DESCRIPTION + Creates a new branch with the specified name. + .PARAMETER Name + The name of the new branch. + Always required. + Must match the .net regex pattern "v2_\d{4}_[a-zA-Z0-9()_-]+". + Must also otherwise be a valid identifier for a git branch and follow any other project guidelines. + .PARAMETER NoSwitch + If specified, does not automatically switch to your new branch after creating it. + Default is to switch to the new branch after creating it. + .PARAMETER Push + If specified, automatically pushes the new branch to your remote after creating it. + .PARAMETER Remote + The name of the git remote, as configured. + If you never explicitly set this yourself, it is typically "origin". + If you only have one remote defined or have not explicitly set a remote yourself, do not provide this parameter; It will be detected automatically. + .INPUTS + None + .OUTPUTS + The name of the current branch after the operation, as a String. + If NoSwitch was specified and the operation succeeded, this should be the source branch. + If NoSwith was not specified or was explicitly set to $false and the operation succeeded, this should be the new branch. + If an exception occurs, does not return. Exceptions are unhandled and are the responsibility of the caller. + .NOTES + Errors thrown by git commands are not explicitly handled. +#> +Function New-GitBranch { + [CmdletBinding(PositionalBinding=$false, SupportsShouldProcess=$true, ConfirmImpact="Low", DefaultParameterSetName="Basic")] + param( + [Parameter(Mandatory=$true, ParameterSetName="Basic")] + [Parameter(Mandatory=$true, ParameterSetName="NoSwitch")] + [Parameter(Mandatory=$true, ParameterSetName="Push")] + [ValidatePattern("v2_\d{4}_[a-zA-Z0-9()_-]+")] + [string]$Name, + [Parameter(Mandatory=$true,ParameterSetName="NoSwitch",DontShow)] + [switch]$NoSwitch, + [Parameter(Mandatory=$false, ParameterSetName="Basic")] + [Parameter(Mandatory=$true, ParameterSetName="Push")] + [switch]$Push, + [Parameter(Mandatory=$false, ParameterSetName="Push")] + [string]$Remote = $null + ) + $currentBranch = (& git branch --show-current) + + if(!$PSCmdlet.ShouldProcess("Creating new branch named $Name from $currentBranch", $Name, "Creating branch")) { + return $null + } + + git branch $Name + + if(!$NoSwitch) { + git switch $Name + + if($Push) { + if([String]::IsNullOrWhiteSpace($Remote)) { + $tempRemotes = (git remote show) + if($tempRemotes -is [array]){ + # If we've gotten here, Push was specified, a remote was not specified or was blank, and there are multiple remotes defined locally. + # Not going to support that. Just error out. + Remove-Variable tempRemotes + throw "No Remote specified and multiple remotes are defined. Cannot continue." + } else { + # Push is set, Remote wasn't, but there's only one defined. Safe to continue. Use the only remote. + $Remote = $tempRemotes + Remove-Variable tempRemotes + } + } + + # Push is set, and either Remote was specified or there's only one remote defined and we will use that. + # Perform the push. + git push --set-upstream $Remote $Name + } + } else{ + # NoSwitch was specified. + # Return the current branch name. + return $currentBranch + } + + # If we made it to this point, return the Name that was specified. + return $Name +} + +<# + .SYNOPSIS + Checks if the command 'git' is available in the current session. + .DESCRIPTION + Checks if the command 'git' is available in the current session. + Throws an error if not. + Returns $true if git is available. + Only intended for use in scripts and module manifests. + .INPUTS + None + .OUTPUTS + If git exists, $true. + Otherwise, $false. +#> +Function Test-GitAvailable { + [OutputType([Boolean])] + [CmdletBinding()] + param() + if($null -eq (Get-Command git -ErrorAction Ignore)) { + Write-Error -Message "git was not found. Git functionality will not work." -Category ObjectNotFound -TargetObject "git" + return $false + } + return $true +} + +Test-GitAvailable -ErrorAction Continue \ No newline at end of file diff --git a/Scripts/Terminal.Gui.PowerShell.psd1 b/Scripts/Terminal.Gui.PowerShell.psd1 new file mode 100644 index 000000000..3d190a4ac --- /dev/null +++ b/Scripts/Terminal.Gui.PowerShell.psd1 @@ -0,0 +1,150 @@ +<# + .SYNOPSIS + All-inclusive module that includes all other Terminal.Gui.PowerShell.* modules. + .DESCRIPTION + All-inclusive module that includes all other Terminal.Gui.PowerShell.* modules. + .EXAMPLE + Import-Module ./Terminal.Gui.PowerShell.psd1 + .NOTES + Doc comments on manifest files are not supported by Get-Help as of PowerShell 7.4.2. + This comment block is purely informational and will not interfere with module loading. +#> + + +@{ + +# No root module because this is a manifest module. +RootModule = '' + +# Version number of this module. +ModuleVersion = '1.0.0' + +# Supported PSEditions +CompatiblePSEditions = @('Core') + +# ID used to uniquely identify this module +GUID = 'f28198f9-cf4b-4ab0-9f94-aef5616b7989' + +# Author of this module +Author = 'Brandon Thetford (GitHub @dodexahedron)' + +# Company or vendor of this module +CompanyName = 'The Terminal.Gui Project' + +# Copyright statement for this module +Copyright = 'Brandon Thetford (GitHub @dodexahedron), provided to the Terminal.Gui project and you under the MIT license' + +# Description of the functionality provided by this module +Description = 'Utilities for development-time operations on and management of components of Terminal.Gui code and other assets.' + +# Minimum version of the PowerShell engine required by this module +PowerShellVersion = '7.4.0' + +# Name of the PowerShell "host" subsystem (not system host name). Helps ensure that we know what to expect from the environment. +PowerShellHostName = 'ConsoleHost' + +# Minimum version of the PowerShell host required by this module +PowerShellHostVersion = '7.4.0' + +# Processor architecture (None, MSIL, X86, IA64, Amd64, Arm, or an empty string) required by this module. One value only. +# Set to AMD64 here because development on Terminal.Gui isn't really supported on anything else. +# Has nothing to do with runtime use of Terminal.Gui. +ProcessorArchitecture = '' + +# Modules that must be imported into the global environment prior to importing this module +RequiredModules = @( + @{ + ModuleName='Microsoft.PowerShell.Utility' + ModuleVersion='7.0.0' + }, + @{ + ModuleName='Microsoft.PowerShell.Management' + ModuleVersion='7.0.0' + }, + @{ + ModuleName='PSReadLine' + ModuleVersion='2.3.4' + } +) + +# Assemblies that must be loaded prior to importing this module +# RequiredAssemblies = @() + +# Script files (.ps1) that are run in the caller's environment prior to importing this module. +# ScriptsToProcess = @() + +# Type files (.ps1xml) to be loaded when importing this module +# TypesToProcess = @() + +# Format files (.ps1xml) to be loaded when importing this module +# FormatsToProcess = @() + +# Modules to import as nested modules of this module. +# This module is just a shortcut that loads all of our modules. +NestedModules = @('./Terminal.Gui.PowerShell.Core.psd1', './Terminal.Gui.PowerShell.Git.psd1', './Terminal.Gui.PowerShell.Build.psd1') + +# Functions to export from this module. +# Not filtered, so exports all functions exported by all nested modules. +FunctionsToExport = '*' + +# Cmdlets to export from this module. +# We don't have any, so empty array. +CmdletsToExport = @() + +# Variables to export from this module. +# We explicitly control scope of variables, so empty array. +VariablesToExport = @() + +# Aliases to export from this module. +# None defined at this time. +AliasesToExport = @() + +# List of all modules packaged with this module +# This is informational ONLY, so it's just blank right now. +# ModuleList = @() + +# List of all files packaged with this module +# This is informational ONLY, so it's just blank right now. +# FileList = @() + +# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell. +PrivateData = @{ + + PSData = @{ + + # Tags applied to this module. These help with module discovery in online galleries. + # Tags = @() + + # A URL to the license for this module. + LicenseUri = 'https://github.com/gui-cs/Terminal.Gui/tree/v2_develop/Scripts/COPYRIGHT' + + # A URL to the main website for this project. + ProjectUri = 'https://github.com/gui-cs/Terminal.Gui' + + # A URL to an icon representing this module. + # IconUri = '' + + # ReleaseNotes of this module + ReleaseNotes = 'See change history and releases for Terminal.Gui on GitHub' + + # Prerelease string of this module + # Prerelease = '' + + # Flag to indicate whether the module requires explicit user acceptance for install/update/save + RequireLicenseAcceptance = $false + + # External dependent modules of this module + # ExternalModuleDependencies = @() + + } # End of PSData hashtable + +} # End of PrivateData hashtable + +# HelpInfo URI of this module +# HelpInfoURI = '' + +# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix. +# DefaultCommandPrefix = '' + +} +