Introducing the Uri module

README.md

@@ -1,69 +1,111 @@
-# {{ NAME }}
+# URI
 
-{{ DESCRIPTION }}
+URI is a PowerShell module that provides robust functions for parsing, constructing, and manipulating URIs. It offers easy-to-use commands to:
+
+- Parse URL query strings into hashtables.
+- Convert hashtables (or dictionaries) into properly URL-encoded query strings.
+- Build complete URIs from base addresses, path segments, query parameters, and fragments—with automatic handling of URL encoding per [RFC3986](https://datatracker.ietf.org/doc/html/rfc3986).
 
 ## Prerequisites
 
-This uses the following external resources:
-- The [PSModule framework](https://github.com/PSModule) for building, testing and publishing the module.
+This module uses the following external resources:
+- The [PSModule framework](https://github.com/PSModule) for building, testing, and publishing the module.
 
 ## Installation
 
-To install the module from the PowerShell Gallery, you can use the following command:
+To install the module from the PowerShell Gallery, run the following commands:
 
 ```powershell
-Install-PSResource -Name {{ NAME }}
-Import-Module -Name {{ NAME }}
+Install-PSResource -Name Uri
+Import-Module -Name Uri
 ```
 
 ## Usage
 
-Here is a list of example that are typical use cases for the module.
+The **URI** module includes several functions to work with URIs. Below are common use cases and examples:
 
-### Example 1: Greet an entity
+### 1. Parsing a Query String
 
-Provide examples for typical commands that a user would like to do with the module.
+Use `ConvertFrom-UriQueryString` to convert a URL query string into a hashtable of parameters. This function decodes percent-encoded characters and handles duplicate keys by returning an array of values.
 
 ```powershell
-Greet-Entity -Name 'World'
-Hello, World!
+# Example: Parsing a query string with multiple values for the same key.
+$parsed = ConvertFrom-UriQueryString -Query 'name=John%20Doe&age=30&age=40'
+$parsed
 ```
 
-### Example 2
+Expected Output:
+
+```powershell
+Name                           Value
+----                           -----
+name                           John Doe
+age                            {30, 40}
+```
+
+### 2. Constructing a Query String
+
+Use `ConvertTo-UriQueryString` to convert a hashtable (or dictionary) of parameters into a URL-encoded query string. If a value is an array, multiple key-value pairs will be generated.
+
+```powershell
+# Example: Converting a hashtable of parameters into a query string.
+$queryString = ConvertTo-UriQueryString -Query @{ foo = 'bar'; search = 'hello world'; ids = 1,2,3 }
+$queryString
+```
 
-Provide examples for typical commands that a user would like to do with the module.
+Expected Output:
 
 ```powershell
-Import-Module -Name PSModuleTemplate
+foo=bar&search=hello%20world&ids=1&ids=2&ids=3
 ```
 
-### Find more examples
+### 3. Building a Complete URI
 
-To find more examples of how to use the module, please refer to the [examples](examples) folder.
+Use `New-Uri` to construct a URI by combining a base URI with optional path segments, query parameters, and a fragment.
 
-Alternatively, you can use the Get-Command -Module 'This module' to find more commands that are available in the module.
-To find examples of each of the commands you can use Get-Help -Examples 'CommandName'.
+```powershell
+# Example 1: Building a URI with a base and a path.
+$uri = New-Uri -BaseUri 'https://example.com' -Path 'products/item'
+$uri
+```
+
+Expected Output (as a `[System.Uri]` object):
+
+```powershell
+AbsoluteUri : https://example.com/products/item
+...
+```
+
+```powershell
+# Example 2: Constructing a URI while merging existing query parameters.
+$uriString = New-Uri 'https://example.com/data?year=2023' -Query @{ year = 2024; sort = 'asc' } -MergeQueryParameters -AsString
+$uriString
+```
+
+Expected Output:
+
+```powershell
+https://example.com/data?sort=asc&year=2023&year=2024
+```
 
 ## Documentation
 
-Link to further documentation if available, or describe where in the repository users can find more detailed documentation about
-the module's functions and features.
+For more detailed documentation about each function and additional examples, please refer to the [documentation](docs) folder in the repository or view the detailed help in PowerShell:
+
+```powershell
+Get-Help ConvertFrom-UriQueryString -Detailed
+Get-Help ConvertTo-UriQueryString -Detailed
+Get-Help New-Uri -Detailed
+```
 
 ## Contributing
 
-Coder or not, you can contribute to the project! We welcome all contributions.
+Contributions are welcome—whether you're a user or a developer!
 
 ### For Users
 
-If you don't code, you still sit on valuable information that can make this project even better. If you experience that the
-product does unexpected things, throw errors or is missing functionality, you can help by submitting bugs and feature requests.
-Please see the issues tab on this project and submit a new issue that matches your needs.
+If you encounter issues, unexpected behavior, or have feature requests, please submit a new issue via the repository's Issues tab.
 
 ### For Developers
 
-If you do code, we'd love to have your contributions. Please read the [Contribution guidelines](CONTRIBUTING.md) for more information.
-You can either help by picking up an existing issue or submit a new one if you have an idea for a new feature or improvement.
-
-## Acknowledgements
-
-Here is a list of people and projects that helped this project in some way.
+We appreciate your help in making this module even better. Please review our [Contribution Guidelines](CONTRIBUTING.md) before submitting pull requests. You can start by picking up an existing issue or proposing new features or improvements.

examples/General.md

@@ -0,0 +1,145 @@
+# Advanced Examples for the URI Module
+
+This document demonstrates advanced usage scenarios for the **URI** module. These examples cover more complex cases, including handling duplicate query parameters, merging queries, and constructing URIs with multiple path segments and fragments.
+
+---
+
+## Example 1: Parsing a Complex Query String
+
+When a query string includes duplicate keys and URL-encoded characters, the `ConvertFrom-UriQueryString` function returns arrays for keys with multiple values.
+
+```powershell
+# A query string with duplicate keys and an empty value.
+$query = 'filter=active&filter=recent&search=PowerShell%20URI&empty'
+$result = ConvertFrom-UriQueryString -Query $query
+$result
+```
+
+**Expected Output:**
+
+```none
+Name                           Value
+----                           -----
+empty
+search                         PowerShell URI
+filter                         {active, recent}
+```
+
+---
+
+## Example 2: Converting a Hashtable with Array Values to a Query String
+
+The `ConvertTo-UriQueryString` function handles hashtables where some keys have array values by generating multiple key-value pairs.
+
+```powershell
+# A hashtable where 'tags' contains multiple values.
+$params = @{
+    category  = 'books'
+    tags      = @('fiction', 'bestseller', '2023')
+    available = $true
+}
+$queryString = ConvertTo-UriQueryString -Query $params
+$queryString
+```
+
+**Expected Output:**
+
+```none
+category=books&tags=fiction&tags=bestseller&tags=2023&available=True
+```
+
+---
+
+## Example 3: Merging Existing and New Query Parameters
+
+Use `New-Uri` with the `-MergeQueryParameters` switch to merge new query parameters into a base URI that already includes a query string.
+
+```powershell
+# Base URI with an existing 'page' parameter.
+$baseUri = 'https://example.com/api/items?page=1'
+$newParams = @{ page = @(2,3); sort = 'desc' }
+$uri = New-Uri -BaseUri $baseUri -Query $newParams -MergeQueryParameters -AsUri
+$uri
+```
+
+**Expected Output:**
+
+The resulting URI should merge the original and new query parameters, producing duplicate `page` keys:
+
+```none
+Scheme   : https
+UserName :
+Password :
+Host     : example.com
+Port     : 443
+Path     : /api/items
+Query    : ?page=1&page=2&page=3&sort=desc
+Fragment :
+Uri      : https://example.com/api/items?page=1&page=2&page=3&sort=desc
+```
+
+---
+
+## Example 4: Constructing a URI with Multiple Path Segments and a Fragment
+
+`New-Uri` accepts an array of path segments and a fragment, constructing a well-formed URI.
+
+```powershell
+# Combining multiple path segments and appending a fragment.
+$uri = New-Uri -BaseUri 'https://example.com' -Path @('catalog', 'books', 'fiction') -Fragment 'section2'
+$uri
+```
+
+**Expected Output:**
+
+A URI similar to:
+
+```none
+AbsolutePath   : /catalog/books/fiction
+AbsoluteUri    : https://example.com/catalog/books/fiction#section2
+LocalPath      : /catalog/books/fiction
+Authority      : example.com
+HostNameType   : Dns
+IsDefaultPort  : True
+IsFile         : False
+IsLoopback     : False
+PathAndQuery   : /catalog/books/fiction
+Segments       : {/, catalog/, books/, fiction}
+IsUnc          : False
+Host           : example.com
+Port           : 443
+Query          :
+Fragment       : #section2
+Scheme         : https
+OriginalString : https://example.com:443/catalog/books/fiction#section2
+DnsSafeHost    : example.com
+IdnHost        : example.com
+IsAbsoluteUri  : True
+UserEscaped    : False
+UserInfo       :
+```
+
+---
+
+## Example 5: Producing a Custom-Formatted URI String
+
+If you prefer the final URI as a string, use the `-AsString` switch. In this advanced example, notice how the fragment is appended after custom formatting.
+
+```powershell
+# Create a URI string with a custom formatted fragment.
+$uriString = New-Uri -BaseUri 'https://example.com/store' -Path 'items/special offers/' -Fragment 'limited edition' -AsString
+$uriString
+```
+
+**Expected Output:**
+
+The output will be a formatted URI string with the fragment adjusted (e.g., spaces replaced with hyphens):
+
+```none
+https://example.com/store/items/special%20offers/#limited-edition
+```
+
+---
+
+These advanced examples illustrate how to leverage the full power of the **URI** module for complex scenarios.
+For additional details or further use cases, consult the module’s documentation or source code.