added initial module functions complete with tests. (#5)

* Added module PSData and build config

* remove template classes

* Resolved conflicts and updated changes

* removed Get-BackupFilePath and tests

* add public functions unit tests

* added tests

* update readme

* updated changelog

* fix test error for Get-FunctionScriptBlock

.vscode/settings.json

@@ -16,6 +16,9 @@
     "files.trimTrailingWhitespace": true,
     "files.trimFinalNewlines": true,
     "files.insertFinalNewline": true,
+    "files.autoSave": "afterDelay", // Enables autosave after a delay
+    "files.autoSaveDelay": 1000, // Autosave after 1 second of inactivity (1000ms)
+    "editor.formatOnSave": true, // Enables format on save
     "files.associations": {
         "*.ps1xml": "xml"
     },

CHANGELOG.md

@@ -6,18 +6,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
-- Added detailed comment-based help to all public functions in the `WisherTools.Helpers` module. This provides better guidance and documentation for the following functions:
-  - `Get-BackupFilePath`
+
+- Added detailed comment-based help and Unit Tests to all public functions in the
+`WisherTools.Helpers` module. This provides better guidance and documentation
+for the following functions:
   - `Get-DirectoryPath`
   - `Get-FunctionScriptBlock`
+  - `New-UniqueFilePath`
   - `Test-ComputerPing`
-  - `Test-DirectoryExists`
+  - `Test-DirectoryExistence`
+
+- Added module PSData and build config
+
+- Added warning to `New-UniqueFilePath` when the specified directory does not
+exist and automatically creates the directory.
+
+- Environment variables (`FILE_DIRECTORY`, `FILE_PREFIX`, `FILE_EXTENSION`) are
+now used as default parameters for `New-UniqueFilePath`.
+
+- Created new function `New-UniqueFilePath`, a more generic version of
+`Get-BackupFilePath`, to generate unique file paths with customizable
+prefixes, directories, and extensions.
+
+### Changed
+
+- Replaced hardcoded defaults in `Get-BackupFilePath` with dynamic environment
+variables and made the function more generic.
+
+- Updated `New-UniqueFilePath` to use environment variables for default values
+and fallback defaults if not set.
 
 ## [v0.1.0] - 2024-09-07
 
 ### Changed
 
-- Removed Test Requierments to Test release
+- Removed Test Requirements to Test release
 
 ### Fixed
+
 - Updated Pipeline to pass deploy

README.md

@@ -1,31 +1,163 @@
 # WisherTools.Helpers
 
-The WisherTools.Helpers module is a collection of essential utility functions designed to assist with common tasks in PowerShell scripting. This module provides reusable components for managing directories, working with PowerShell functions dynamically, verifying system availability through network pings, and generating backup file paths. It streamlines various processes that are frequently used across different scripts and modules, offering a robust set of helper tools to enhance efficiency and maintainability.
+<div align="center">
+  <img src="https://raw.githubusercontent.com/LarryWisherMan/ModuleIcons/main/WisherTools.Helpers.png"
+   alt="WisherTools.Helpers Icon" width="400" />
+</div>
 
-**Function Overview**
+The **WisherTools.Helpers** module is a collection of helper functions I often
+keep using. It is designed to assist with common tasks in PowerShell scripting.
+This module provides reusable components for managing directories, working with
+PowerShell functions dynamically, verifying system availability through network
+pings, and generating unique backup file paths. This module is sure to grow as
+I am hoping to reuse common functions.
 
-1. **Get-DirectoryPath**  
-   Converts a base path to a local or UNC format based on whether the target is local or remote.
+## **Used In**
+
+Currently I use **WisherTools.Helpers** module in few other modules I have
+developed to help reuse code. It is currently used in the following modules:
+
+- [WinRegOps](https://github.com/LarryWisherMan/WinRegOps): A module for managing
+  Windows Registry operations.
+- [WinProfileOps](https://github.com/LarryWisherMan/WinProfileOps): A module for
+  handling Windows user profiles.
+- [WinDirOps](https://github.com/LarryWisherMan/WinDirOps): A module for working
+with Windows directories.
+
+## **Installation**
+
+To install **WisherTools.Helpers**, you have two options:
+
+1. **Install from PowerShell Gallery**  
+   You can install the module directly from the [PowerShell Gallery](https://www.powershellgallery.com/packages/WisherTools.Helpers)
+   using the `Install-Module` command:
+
+   ```powershell
+   Install-Module -Name WisherTools.Helpers
+   ```
+
+1. **Install from GitHub Releases**  
+   You can also download the latest release from the [GitHub Releases page](https://github.com/LarryWisherMan/WisherTools.Helpers/releases).
+   Download the `.zip` file of the release, extract it, and place it in one of
+   your `$PSModulePath` directories.
+
+## **Function Overview**
+
+### 1. **Get-DirectoryPath**
+
+   Converts a base path to either a local or UNC format depending on whether the
+   target is local or remote.
+
+- **Parameters**:
+  - `BasePath`: The base directory path that needs to be converted.
+  - `ComputerName`: The name of the computer where the directory is located.
+  - `IsLocal`: A boolean indicating if the target is local (`$true`) or remote (`$false`).
+
+- **Example**:
+
+     ```powershell
+     Get-DirectoryPath -BasePath "C:\Files" -ComputerName "RemotePC" -IsLocal $false
+     ```
+
+     Converts the local path "C:\Files" to a UNC path for the remote computer.
+
+- **Outputs**: `System.String` (The converted path in local or UNC format.)
+
+---
+
+### 2. **Get-FunctionScriptBlock**
 
-2. **Get-FunctionScriptBlock**  
    Retrieves the script block of a specified PowerShell function.
 
-3. **Get-BackupFilePath**  
-   Generates a unique backup file path with a timestamp.
+- **Parameters**:
+  - `FunctionName`: The name of the PowerShell function to retrieve the script
+  block for.
 
-4. **Test-DirectoryExists**  
-   Ensures that a directory exists; creates it if necessary.
+- **Examples**:
 
-5. **Test-ComputerPing**  
-   Pings a computer to check if it is online with a configurable timeout.
+     ```powershell
+     Get-FunctionScriptBlock -FunctionName 'Get-Process'
+     ```
+
+     Retrieves the script block of the 'Get-Process' function.
+
+     ```powershell
+     Get-FunctionScriptBlock -FunctionName 'Test-Function'
+     ```
+
+     Retrieves the script block of 'Test-Function' if it exists.
+
+- **Outputs**: `System.String` (The full script block of the function.)
+
+---
+
+### 3. **New-UniqueFilePath**
+
+   Generates a unique file path with a timestamp.
+
+- **Parameters**:
+  - `Directory`: The directory where the file will be saved (defaults to the environment
+  variable `FILE_DIRECTORY` or the user's TEMP directory if not set).
+
+  - `Prefix`: The prefix for the file name (defaults to the environment variable
+  `FILE_PREFIX` or "File").
+
+  - `Extension`: The file extension (defaults to the environment variable
+   `FILE_EXTENSION` or ".txt").
+
+- **Examples**:
+
+     ```powershell
+     New-UniqueFilePath -Directory "C:\Backups" -Prefix "UserBackup" -Extension ".reg"
+     ```
+
+     Generates a file path like `C:\Backups\UserBackup_20240909_141500.reg`.
+
+     ```powershell
+     New-UniqueFilePath -Directory "C:\Logs" -Prefix "Log" -Extension ".log"
+     ```
+
+     Generates a file path like `C:\Logs\Log_20240909_141500.log`.
+
+- **Outputs**: `System.String` (The full path of the newly generated file.)
 
+---
+
+### 4. **Test-DirectoryExistence**
+
+   Ensures that a specified directory exists, and creates it if necessary.
+
+- **Parameters**:
+  - `Directory`: The path of the directory to check or create.
+
+- **Example**:
+
+     ```powershell
+     Test-DirectoryExistence -Directory "C:\Backups"
+     ```
 
-## Make it yours
+     Checks if the directory "C:\Backups" exists. If not, it creates it.
+
+- **Outputs**: None.
 
 ---
-Generated with Plaster and the SampleModule template
 
+### 5. **Test-ComputerPing**
+
+   Pings a computer to check if it is online with a configurable timeout.
+
+- **Parameters**:
+  - `ComputerName`: The name of the computer to be pinged.
+  - `Timeout`: The timeout value for the ping request in milliseconds (default
+  is 2000 ms).
+
+- **Example**:
+
+     ```powershell
+     Test-ComputerPing -ComputerName "RemotePC" -Timeout 3000
+     ```
 
-This is a sample Readme
+     Pings the computer "RemotePC" with a timeout of 3 seconds to check if it's online.
 
-## Make it yours
+- **Outputs**: `System.Boolean` (Returns `true` if the computer is reachable,
+`false` otherwise.)

build.yaml

@@ -10,7 +10,7 @@ BuiltModuleSubdirectory: module
 CopyPaths:
   - en-US
 #  - DSCResources
-  # - Modules
+# - Modules
 Encoding: UTF8
 # Can be used to manually specify module's semantic version if the preferred method of
 # using GitVersion is not available, and it is not possible to set the session environment
@@ -43,7 +43,7 @@ NestedModule:
 ####################################################
 # Defining 'Workflows' (suite of InvokeBuild tasks) to be run using their alias
 BuildWorkflow:
-  '.': # "." is the default Invoke-Build workflow. It is called when no -Tasks is specified to the build.ps1
+  ".": # "." is the default Invoke-Build workflow. It is called when no -Tasks is specified to the build.ps1
     - build
     - test
 
@@ -53,13 +53,10 @@ BuildWorkflow:
     - Build_NestedModules_ModuleBuilder
     - Create_changelog_release_output
 
-
   pack:
     - build
     - package_module_nupkg
 
-
-
   # Defining test task to be run when invoking `./build.ps1 -Tasks test`
   test:
     # Uncomment to modify the PSModulePath in the test pipeline (also requires the build configuration section SetPSModulePath).
@@ -73,10 +70,9 @@ BuildWorkflow:
   # Use this task when you have multiple parallel tests, which produce multiple
   # code coverage files and needs to get merged into one file.
   #merge:
-    #- Merge_CodeCoverage_Files
+  #- Merge_CodeCoverage_Files
 
   publish:
-
     - Publish_Release_To_GitHub # Runs first, if token is expired it will fail early
     - publish_module_to_gallery
 
@@ -99,9 +95,9 @@ Pester:
   # - tests/Unit
   # - tests/Integration
   ExcludeTag:
-  #  - helpQuality
-    - FunctionalQuality
-    - TestQuality
+    #  - helpQuality
+    #- FunctionalQuality
+    #- TestQuality
   Tag:
   CodeCoverageThreshold: 85 # Set to 0 to bypass
   #CodeCoverageOutputFile: JaCoCo_$OsShortName.xml
@@ -117,20 +113,18 @@ Pester:
 # CodeCoverageMergedOutputFile - the file that is created by the merge build task and
 #                                is the file that should be uploaded to code coverage services.
 #CodeCoverage:
-  #CodeCoverageFilePattern: JaCoCo_Merge.xml # the pattern used to search all pipeline test job artifacts
-  #CodeCoverageMergedOutputFile: JaCoCo_coverage.xml # the file that is created for the merged code coverage
-
+#CodeCoverageFilePattern: JaCoCo_Merge.xml # the pattern used to search all pipeline test job artifacts
+#CodeCoverageMergedOutputFile: JaCoCo_coverage.xml # the file that is created for the merged code coverage
 
 # Import ModuleBuilder tasks from a specific PowerShell module using the build
 # task's alias. Wildcard * can be used to specify all tasks that has a similar
 # prefix and or suffix. The module contain the task must be added as a required
 # module in the file RequiredModules.psd1.
 ModuleBuildTasks:
   Sampler:
-    - '*.build.Sampler.ib.tasks'
+    - "*.build.Sampler.ib.tasks"
   Sampler.GitHubTasks:
-    - '*.ib.tasks'
-
+    - "*.ib.tasks"
 
 # Invoke-Build Header to be used to 'decorate' the terminal output of the tasks.
 TaskHeader: |
@@ -143,3 +137,10 @@ TaskHeader: |
   Write-Build DarkGray "  $Path"
   Write-Build DarkGray "  $($Task.InvocationInfo.ScriptName):$($Task.InvocationInfo.ScriptLineNumber)"
   ""
+
+GitHubConfig:
+  GitHubFilesToAdd:
+    - "CHANGELOG.md"
+  GitHubConfigUserName: LarryWisherMan
+  GitHubConfigUserEmail: [email protected]
+  UpdateChangelogOnPrerelease: false