Merge pull request #61 from PowershellFrameworkCollective/updates

2.2.35

Author: FriedrichWeinmann

PSUtil/PSUtil.psd1

@@ -3,7 +3,7 @@
 	RootModule = 'PSUtil.psm1'
 
 	# Version number of this module.
-	ModuleVersion = '2.0.20'
+	ModuleVersion = '2.2.35'
 
 	# ID used to uniquely identify this module
 	GUID = '9ef51588-c40c-4064-910d-9b624b758cf6'
@@ -26,8 +26,8 @@
 	# Modules that must be imported into the global environment prior to importing
 	# this module
 	RequiredModules = @(
-		@{ ModuleName = 'PSFramework'; ModuleVersion = '1.1.59' }
-		@{ ModuleName = 'string'; ModuleVersion = '0.6.1' }
+		@{ ModuleName = 'PSFramework'; ModuleVersion = '1.6.205' }
+		@{ ModuleName = 'string'; ModuleVersion = '1.0.0' }
 	)
 
 	# Assemblies that must be loaded prior to importing this module
@@ -44,6 +44,7 @@
 		'Backup-PSULocation'
 		'Convert-PSUObject'
 		'Expand-PSUObject'
+		'Get-PSUCalendarWeek'
 		'Get-PSUPathAlias'
 		'Invoke-PSUDesktop'
 		'Invoke-PSUExplorer'
@@ -68,10 +69,10 @@
 	)
 
 	# Cmdlets to export from this module
-	CmdletsToExport = ''
+	# CmdletsToExport = ''
 
 	# Variables to export from this module
-	VariablesToExport = ''
+	# VariablesToExport = ''
 
 	# Aliases to export from this module
 	AliasesToExport    = @(
@@ -82,8 +83,10 @@
 		'c'
 		'cast'
 		'cfj'
+		'cfx'
 		'convert'
 		'ctj'
+		'ctx'
 		'desktop'
 		'ec'
 		'ex'
@@ -115,6 +118,7 @@
 		'split'
 		'Split-PSUString'
 		'spo'
+		'teach'
 		'temp'
 		'timer'
 		'trim'

PSUtil/bin/PSUtil.dll

@@ -1,4 +1,15 @@
 # Changelog
+
+## 2.2.35 (2021-10-13)
+
+- New: Object Conversion - NT <--> SID
+- New: Object Conversion - string <--> base64
+- New: Command Get-PSUCalendarWeek - Calculates the calendar week of the specified date.
+- Upd: Start-PSUTimer - added `-RandomInterval` parameter, randomizing the sound playback interval
+- Upd: Start-PSUTimer - added `-DisableScreensaver` parameter, blocking screensaver for the duration of the timer
+- Upd: Start-PSUTimer - now automatically adds a day if the destination-time is in the past
+- Upd: Manifest - added ctx and cfx to the aliases exported, enabling auto-import from using those.
+
 ## 2.1.28 (2020-03-21)
  - New: Component: Knowledge - store and search knowledge
  - New: Command: Read-PSUKnowledge (read, page, learn) - retrieves stored knowledge

PSUtil/bin/PSUtil.pdb

@@ -104,4 +104,5 @@
 			catch { Stop-PSFFunction -String 'Set-PSUKnowledge.Book.ExportFailed' -StringValues $Name, $Book, $bookPath -ErrorRecord $_ -EnableException $EnableException -Continue }
 		}
 	}
-}
+}
+Import-PSUAlias -Name 'teach' -Command Write-PSUKnowledge

PSUtil/bin/PSUtil.xml

@@ -25,7 +25,7 @@
         Use this if you want the function to throw terminating errors you want to catch.
 	
 	.EXAMPLE
-		PS C:\> 100..110 | convert IntDec IntHex
+		PS C:\> 100..110 | convert dec hex
 	
 		Converts the numbers 100 through 110 from decimal to hexadecimal.
 #>

PSUtil/changelog.md

@@ -0,0 +1,57 @@
+function Get-PSUCalendarWeek {
+<#
+	.SYNOPSIS
+		Calculates the calendar week of the specified date.
+	
+	.DESCRIPTION
+		Calculates the calendar week of the specified date.
+		Can be customized to fit the calendar rules of a given culture.
+	
+	.PARAMETER Date
+		The date for which to process the calendar week.
+		Defaults to the current time and date.
+	
+	.PARAMETER FirstDay
+		Which day is considered the first day of the week.
+		Defaults to the current or selected culture.
+	
+	.PARAMETER WeekRule
+		The rule by which the first week of the year is determined.
+		Defaults to the current or selected culture.
+	
+	.PARAMETER Culture
+		The culture to use when determining the calendarweek of the specified date.
+		Defaults to the current culture.
+	
+	.EXAMPLE
+		PS C:\> Get-PSUCalendarWeek
+		
+		Gets the current calendar week
+#>
+	[CmdletBinding()]
+	param (
+		[PSFDateTime]
+		$Date = (Get-Date),
+		
+		[DayOfWeek]
+		$FirstDay,
+		
+		[System.Globalization.CalendarWeekRule]
+		$WeekRule,
+		
+		[System.Globalization.CultureInfo]
+		$Culture = (Get-Culture)
+	)
+	
+	process {
+		$first = $FirstDay
+		if (Test-PSFParameterBinding -ParameterName FirstDay -Not -BoundParameters $PSBoundParameters) {
+			$first = $Culture.DateTimeFormat.FirstDayOfWeek
+		}
+		$wRule = $WeekRule
+		if (Test-PSFParameterBinding -ParameterName WeekRule -Not -BoundParameters $PSBoundParameters) {
+			$wRule = $Culture.DateTimeFormat.CalendarWeekRule
+		}
+		$Culture.Calendar.GetWeekOfYear($Date, $wRule, $first)
+	}
+}

PSUtil/functions/knowledge/Write-PSUKnowledge.ps1

@@ -24,6 +24,9 @@
 	.PARAMETER AlarmInterval
 		In what time interval to write warnings and send sound.
 	
+	.PARAMETER RandomInterval
+		Randomizes the interval between two signal sounds.
+	
 	.PARAMETER MinFrequency
 		The minimum frequency of the beeps.
 		Must be at least one lower than MaxFrequency.
@@ -34,11 +37,16 @@
 		Must be at least one higher than MaxFrequency.
 		Increase delta to play random frequency sounds on each beep.
 	
+	.PARAMETER DisableScreensaver
+		Disables the screensaver while the timer is pending.
+		This only works on Windows and has the command pretend to be a video & backup application, preventing untimely activation of a screensaver.
+	
 	.EXAMPLE
 		PS C:\> timer 170 Tea
 		
 		After 170 Duration give warning that the tea is ready.
 #>
+	[Alias('timer')]
 	[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
 	[CmdletBinding()]
 	param (
@@ -60,17 +68,25 @@
 		[int]
 		$AlarmInterval = 250,
 
+		[switch]
+		$RandomInterval,
+		
 		[int]
 		$MinFrequency = 2999,
 
 		[int]
-		$MaxFrequency = 3000
+		$MaxFrequency = 3000,
+		
+		[switch]
+		$DisableScreensaver
 	)
 
 	begin
 	{
 		$start = Get-Date
 		$end = $Duration.Value
+		# Allow conveniently specifying absolute times for the day after
+		if ($end -lt $start) { $end = $end.AddDays(1) }
 
 		function Get-FriendlyTime
 		{
@@ -111,6 +127,7 @@
 		while ($end -gt (Get-Date))
 		{
 			Start-Sleep -Milliseconds 500
+			if ($DisableScreensaver) { [PSUtil.Utility.UtilityHost]::DisableScreensaver() }
 
 			if (-not $NoProgress)
 			{
@@ -129,10 +146,11 @@
 		while ($countAlarm -lt $AlarmCount)
 		{
 			Write-PSFHostColor -String "(<c='sub'>$countAlarm</c>) ### <c='em'>$($Message)</c> ###"
+			if ($DisableScreensaver) { [PSUtil.Utility.UtilityHost]::DisableScreensaver() }
 			[System.Console]::Beep((Get-Random -Minimum $MinFrequency -Maximum $MaxFrequency), $AlarmInterval)
-			Start-Sleep -Milliseconds $AlarmInterval
+			if ($RandomInterval) { Start-Sleep -Milliseconds (Get-Random -Minimum $AlarmInterval -Maximum ($AlarmInterval * 2)) }
+			else { Start-Sleep -Milliseconds $AlarmInterval }
 			$countAlarm++
 		}
 	}
-}
-Import-PSUAlias -Name "timer" -Command "Start-PSUTimer"
+}

PSUtil/functions/objects/Convert-PSUObject.ps1

@@ -0,0 +1,8 @@
+Register-PSUObjectConversion -From NT -To SID -ScriptBlock {
+	param ($InputObject)
+	([System.Security.Principal.NTAccount]$InputObject).Translate([System.Security.Principal.SecurityIdentifier])
+}
+Register-PSUObjectConversion -From SID -To NT -ScriptBlock {
+	param ($InputObject)
+	([System.Security.Principal.SecurityIdentifier]$InputObject).Translate([System.Security.Principal.NTAccount])
+}