ClipboardText.psm1

<#

IMPORTANT: THIS MODULE MUST REMAIN PSv2-COMPATIBLE.

#>

# Module-wide defaults.

# !! PSv2: We do not even activate the check for accessing nonexistent variables, because
# !!       of a pitfall where parameter variables belonging to a parameter set
# !!       other than the one selected by a given invocation are considered undefined.
if ($PSVersionTable.PSVersion.Major -gt 2) {
  Set-StrictMode -Version 1
}

#region == ALIASES
Set-Alias scbt Set-ClipboardText
Set-Alias gcbt Get-ClipboardText
#endregion

#region == Exported functions

function Get-ClipboardText {
<#
.SYNOPSIS
Gets text from the clipboard.

.DESCRIPTION
Retrieves text from the system clipboard as an arry of lines (by default)
or as-is (with -Raw).

If the clipboard is empty or contains no text, $null is returned.

LINUX CAVEAT: The xclip utility must be installed; on Debian-based platforms
              such as Ubuntu, install it with: sudo apt install xclip

.PARAMETER Raw
Output the retrieved text as-is, even if it spans multiple lines.
By default, if the retrieved text is a multi-line string, each line is 
output individually.

.NOTES
This function is a "polyfill" to make up for the lack of built-in clipboard
support in Windows Powershell v5.0- and in PowerShell Core as of v6.1, 
albeit only with respect to text.

In Windows PowerShell v5+, you can use the built-in Get-Clipboard cmdlet
instead (which this function invokes, if available).

In earlier versions, a helper type is compiled on demand that uses the
Windows API. Note that this means the first invocation of this function
in a given session will be noticeably slower, due to the on-demand compilation.

.EXAMPLE
Get-ClipboardText | ForEach-Object { $i=0 } { '#{0}: {1}' -f (++$i), $_ }

Retrieves text from the clipboard and sends its lines individually through
the pipeline, using a ForEach-Object command to prefix each line with its
line number.

.EXAMPLE
Get-ClipboardText -Raw > out.txt

Retrieves text from the clipboard as-is and saves it to file out.txt
(with a newline appended).
#>
  
  [CmdletBinding()]
  [OutputType([string])]
  param(
    [switch] $Raw
  )

  $rawText = $lines = $null
  # *Windows PowerShell* v5+ in *STA* COM threading mode (which is the default, but it can be started with -MTA)
  if ((test-WindowsPowerShell) -and $PSVersionTable.PSVersion.Major -ge 5 -and 'STA' -eq [threading.thread]::CurrentThread.ApartmentState.ToString()) { 

    Write-Verbose "Windows (PSv5+ in STA mode): deferring to Get-Clipboard"
    if ($Raw) {
      $rawText = Get-Clipboard -Format Text -Raw
    } else {
      $lines = Get-Clipboard -Format Text
    }

  } else {  # Windows PowerShell v4- and/or in MTA threading mode, PowerShell *Core* on any supported platform.

    # No native PS support for writing to the clipboard or native support not available due to MTA mode -> external utilities
    # must be used.
    # (Note: Attempts to use [System.Windows.Forms] proved to be brittle in MTA mode, causing intermittent failures.)
    # Since PS automatically splits external-program output into individual
    # lines and trailing empty lines can get lost in the process, we 
    # must, unfortunately, send the text to a temporary *file* and read
    # that.

    $isWin = $env:OS -eq 'Windows_NT' # Note: $IsWindows is only available in PS *Core*.

    if ($isWin) {

      Write-Verbose "Windows: using WinAPI via helper type"

      # Note: Originally we used a WSH-based solution a la http://stackoverflow.com/a/15747067/45375,
      #       but WSH may be blocked on some systems for security reasons.
      add-WinApiHelperType

      $rawText = [net.same2u.util.Clipboard]::GetText()

    } else {

      $tempFile = [io.path]::GetTempFileName()

      try {

        # Note: For security reasons, we want to make sure it is the actual standard
        #       shell we're invoking on each platform, so we use its full path.
        #       Similarly, for clipboard utilities that are standard on a given platform,
        #       we use their full paths.
        #       Mocking executables invoked by their full paths isn't directly supported
        #       in Pester, so we use helper function invoke-External, which *can* be mocked.
        
        if ($IsMacOS) {

          Write-Verbose "macOS: using pbpaste"

          invoke-External /bin/sh -c "/usr/bin/pbpaste > '$tempFile'"

        } else { # $IsLinux

          Write-Verbose "Linux: using xclip"

          # Note: Requires xclip, which is not installed by default on most Linux distros
          #       and works with freedesktop.org-compliant, X11 desktops.
          #       Note: Since xclip is not an in-box utility, we make no assumptions 
          #             about its specific location and rely on it to be in $env:PATH.
          invoke-External /bin/sh -c "xclip -selection clipboard -out > '$tempFile'"
          # Check for the specific exit code that indicates that `xclip` wasn't found and provide an installation hint.
          if ($LASTEXITCODE -eq 127) { new-StatementTerminatingError "xclip is not installed; please install it via your platform's package manager; e.g., on Debian-based distros such as Ubuntu: sudo apt install xclip" }

        }
        
        if ($LASTEXITCODE) { new-StatementTerminatingError "Invoking the native clipboard utility failed unexpectedly." }

        # Read the contents of the temp. file into a string variable.
        # Temp. file is UTF8, which is the default encoding
        $rawText = [IO.File]::ReadAllText($tempFile)

      } finally {
        Remove-Item $tempFile
      }
    } # -not $isWin
  }

  # Output the retrieved text
  if ($Raw) {  # as-is (potentially multi-line)
    $result = $rawText
  } else {     # as an array of lines (as the PsWinV5+ Get-Clipboard cmdlet does)
    if ($null -eq $lines) {
      # Note: This returns [string[]] rather than [object[]], but that should be fine.
      $lines = $rawText -split '\r?\n'
    }
    $result = $lines
  }

  # If the effective result is the *empty string* [wrapped in a single-element array], we output 
  # $null, because that's what the PsWinV5+ Get-Clipboard cmdlet does.
  if (-not $result) {
    # !! To be consistent with Get-Clipboard, we output $null even in the absence of -Raw,
    # !! even though you could argue that *nothing* should be output (i.e., implicitly, the "arry-valued null", 
    # !! [System.Management.Automation.Internal.AutomationNull]::Value)
    # !! so that trying to *enumerate* the result sends nothing through the pipeline.
    # !! (A similar, but opposite inconsistency is that Get-Content with a zero-byte file outputs the "array-valued null"
    # !!  both with and without -Raw).
    $null
  } else {
    $result
  }

}
  
function Set-ClipboardText {
<#
.SYNOPSIS
Copies text to the clipboard.

.DESCRIPTION
Copies a text representation of the input to the system clipboard.

Input can be provided via the pipeline or via the -InputObject parameter.

If you provide no input, the empty string, or $null, the clipboard is
effectively cleared.

Non-text input is formatted the same way as it would print to the console,
which means that the console/terminal window's [buffer] width determines
the output line width, which may result in truncated data (indicated with
"...").
To avoid that, you can increase the max. line width with -Width, but see 
the caveats in the parameter description.

LINUX CAVEAT: The xclip utility must be installed; on Debian-based platforms
              such as Ubuntu, install it with: sudo apt install xclip

.PARAMETER Width
For non-text input, determines the maximum output-line length.
The default is Out-String's default, which is the current console/terminal
window's [buffer] width.

Be careful with high values and avoid [int]::MaxValue, however, because in
the case of (implicit) Format-Table output each output line is padded to 
that very width, which can require a lot of memory.

.PARAMETER PassThru
In addition to copying the resulting string representation of the input to
the clipboard, also outputs it, as single string.

.NOTES
This function is a "polyfill" to make up for the lack of built-in clipboard
support in Windows Powershell v5.0- and in PowerShell Core as of v6.1,
albeit only with respect to text.
In Windows PowerShell v5.1+, you can use the built-in Set-Clipboard cmdlet
instead (which this function invokes, if available).

.EXAMPLE
Set-ClipboardText "Text to copy"

Copies the specified text to the clipboard.

.EXAMPLE
Get-ChildItem -File -Name | Set-ClipboardText

Copies the names of all files the current directory to the clipboard.

.EXAMPLE
Get-ChildItem | Set-ClipboardText -Width 500

Copies the text representations of the output from Get-ChildItem to the
clipboard, ensuring that output lines are 500 characters wide.
#>
  
  [CmdletBinding(DefaultParameterSetName='Default')] # !! PSv2 doesn't support PositionalBinding=$False
  [OutputType([string], ParameterSetName='PassThru')]
  param(
      [Parameter(Position=0, ValueFromPipeline = $True)] # Note: The built-in PsWinV5.0+ Set-Clipboard cmdlet does NOT have mandatory input, in which case the clipbard is effectively *cleared*.
      [AllowNull()] # Note: The built-in PsWinV5.0+ Set-Clipboard cmdlet allows $null too.
      $InputObject
      ,
      [int] $Width # max. output-line width for non-string input
      ,
      [Parameter(ParameterSetName='PassThru')]
      [switch] $PassThru
  )

  begin {
    # Initialize an array to collect all input objects in.
    # !! Incredibly, in PSv2 using either System.Collections.Generic.List[object] or
    # !! System.Collections.ArrayList ultimately results in different ... | Out-String
    # !! output, with the group header ('Directory:') for input `GetItem / | Out-String`
    # !! inexplicably missing - even .ToArray() conversion or an [object[]] cast
    # !! before piping to Out-String doesn't help.
    # !! Given that we don't expect large collections to be sent to the clipboard,
    # !! we make do with inefficiently "growing" an *array* ([object[]]), i.e.
    # !! cloning the old array for each input object.
    $inputObjs = @()
  }

  process {
    # Collect the input objects.
    $inputObjs += $InputObject
  }
  
  end {

    # * The input as a whole is converted to a a single string with
    #   Out-String, which formats objects the same way you would see on the
    #   console.
    # * Since Out-String invariably appends a trailing newline, we must remove it.
    #   (The PS Core v6 -NoNewline switch is NOT an option, as it also doesn't
    #   place newlines *between* objects.)
    $widthParamIfAny = if ($PSBoundParameters.ContainsKey('Width')) { @{ Width = $Width } } else { @{} }
    $allText = ($inputObjs | Out-String @widthParamIfAny) -replace '\r?\n\z'

    # *Windows PowerShell* v5+ in *STA* COM threading mode (which is the default, but it can be started with -MTA)
    if ((test-WindowsPowerShell) -and $PSVersionTable.PSVersion.Major -ge 5 -and 'STA' -eq [threading.thread]::CurrentThread.ApartmentState.ToString()) { 
        
      # !! As of PsWinV5.1, `Set-Clipboard ''` reports a spurious error (but still manages to effectively) clear the clipboard.
      # !! By contrast, using `Set-Clipboard $null` succeeds.
      Set-Clipboard -Value ($allText, $null)[$allText.Length -eq 0]
      
    } else { # Windows PowerShell v4- and/or in MTA threading mode, PowerShell *Core* on any supported platform.
      
      # No native PS support for writing to the clipboard or native support not available due to MTA mode ->
      # external utilities must be used.
      # (Note: Attempts to use [System.Windows.Forms] proved to be brittle in MTA mode, causing intermittent failures.)

      $isWin = $env:OS -eq 'Windows_NT' # Note: $IsWindows is only available in PS *Core*.

      # To prevent adding a trailing \n, which PS inevitably adds when sending
      # a string through the pipeline to an external command, use a temp. file,
      # whose content can be provided via native input redirection (<)
      $tmpFile = [io.path]::GetTempFileName()

      if ($isWin) {
        # The clip.exe utility requires *BOM-less* UTF16-LE for full Unicode support.
        [IO.File]::WriteAllText($tmpFile, $allText, (New-Object System.Text.UnicodeEncoding $False, $False))
      } else { # $IsUnix -> use BOM-less UTF8
        # PowerShell's UTF8 encoding invariably creates a file WITH BOM
        # so we use the .NET Framework, whose default is BOM-*less* UTF8.
        [IO.File]::WriteAllText($tmpFile, $allText)
      }
      
      # Feed the contents of the temporary file via stdin to the 
      # platform-appropriate clipboard utility.
      try {

        # Note: For security reasons, we want to make sure it is the actual standard
        #       shell we're invoking on each platform, so we use its full path.
        #       Similarly, for clipboard utilities that are standard on a given platform,
        #       we use their full paths.
        #       Mocking executables invoked by their full paths isn't directly supported
        #       in Pester, so we use helper function invoke-External, which *can* be mocked.
  
        if ($isWin) {

          Write-Verbose "Windows: using clip.exe"

          # !! Temporary switch to the system drive (a drive guaranteed to be local) so as to 
          # !! prevent cmd.exe from issuing a warning if a UNC path happens to be the current location
          # !! - see https://github.com/mklement0/ClipboardText/issues/4
          Push-Location -LiteralPath $env:SystemRoot
            invoke-External "$env:SystemRoot\System32\cmd.exe" /c "$env:SystemRoot\System32\clip.exe" '<' $tmpFile
          Pop-Location

        } elseif ($IsMacOS) {

          Write-Verbose "macOS: using pbcopy"

          invoke-External /bin/sh -c "/usr/bin/pbcopy < '$tmpFile'"

        } else { # $IsLinux

          Write-Verbose "Linux: using xclip"
          # Note: Since xclip is not an in-box utility, we make no assumptions 
          #       about its specific location and rely on it to be in $env:PATH.
          # !! >&- (i.e., closing stdout) is necessary, because xclip hangs if you try to redirect its - nonexistent output with `-in`, which also happens impliclity via `$null = ...` in the context of Pester tests.          
          invoke-External /bin/sh -c "xclip -selection clipboard -in < '$tmpFile' >&-"

          # Check for the specific exit code that indicates that `xclip` wasn't found and provide an installation hint.
          if ($LASTEXITCODE -eq 127) { new-StatementTerminatingError "xclip is not installed; please install it via your platform's package manager; e.g., on Debian-based distros such as Ubuntu: sudo apt install xclip" }

        }
        
        if ($LASTEXITCODE) { new-StatementTerminatingError "Invoking the platform-specific clipboard utility failed unexpectedly." }

      } finally {
        Pop-Location # Restore the previously current location.
        Remove-Item $tmpFile
      }

    }

    if ($PassThru) {
      $allText
    }

  }

}

#endregion

#region == Private helper functions
  
# Throw a statement-terminating error (instantly exits the calling function and its enclosing statement).
function new-StatementTerminatingError([string] $Message, [System.Management.Automation.ErrorCategory] $Category = 'InvalidOperation') {
    $PSCmdlet.ThrowTerminatingError((New-Object System.Management.Automation.ErrorRecord `
      $Message,
      $null, # a custom error ID (string)
      $Category, # the PS error category - do NOT use NotSpecified - see below.
      $null # the target object (what object the error relates to)
    )) 
}

# Determine if we're runnning in Windows PowerShell.
function test-WindowsPowerShell {
  # !! $IsCoreCLR is not available in Windows PowerShell and, if
  # !! Set-StrictMode is set, trying to access it would fail.
  $null, 'Desktop' -contains $PSVersionTable.PSEdition 
}

# Helper function for invoking an external utility (executable).
# The raison d'être for this function is so that calls to utilities called 
# with their *full paths* can be mocked in Pester.
function invoke-External {
  param(
    [Parameter(Mandatory=$true)]
    [string] $LiteralPath,
    [Parameter(ValueFromRemainingArguments=$true)]
    $PassThruArgs
  )
  & $LiteralPath $PassThruArgs
}


# Adds helper type [net.same2u.util.Clipboard] for clipboard access via the 
# Windows API.
# Note: It is fine to blindly call this function repeatedly - after the initial
#       performance hit due to compilation, subsequent invocations are very fast.
function add-WinApiHelperType {
  Add-Type -Name Clipboard -Namespace net.same2u.util -MemberDefinition @'
  [DllImport("user32.dll", SetLastError=true)]
  static extern bool OpenClipboard(IntPtr hWndNewOwner);
  [DllImport("user32.dll", SetLastError = true)]
  static extern IntPtr GetClipboardData(uint uFormat);
  [DllImport("user32.dll", SetLastError=true)]
  static extern bool CloseClipboard();
  
  public static string GetText() {
    string txt = null;
    if (!OpenClipboard(IntPtr.Zero)) { throw new Exception("Failed to open clipboard."); }
    IntPtr handle = GetClipboardData(13); // CF_UnicodeText
    if (handle != IntPtr.Zero) { // if no handle is returned, assume that no text was on the clipboard.
      txt = Marshal.PtrToStringAuto(handle);
    }
    if (!CloseClipboard()) { throw new Exception("Failed to close clipboard."); }
    return txt;
  }
'@
}

#endregion