Update readme - reference version 2.0

- use manual format validation for MacAddress so that ErrorAction works
correctly instead of throwing ParameterBindingError which requires
Try/Catch blocks

BREAKING CHANGES:
- remove parameter validation check for MacAddress,
validate while processing
- change all warnings to errors

Closes #1

.gitattributes

@@ -0,0 +1,100 @@
+# Common settings that generally should always be used with your language specific settings
+
+# Auto detect text files and perform LF normalization
+# https://www.davidlaing.com/2012/09/19/customise-your-gitattributes-to-become-a-git-ninja/
+*          text=auto
+
+#
+# The above will handle all files NOT found below
+#
+
+# Documents
+*.bibtex   text diff=bibtex
+*.doc      diff=astextplain
+*.DOC      diff=astextplain
+*.docx     diff=astextplain
+*.DOCX     diff=astextplain
+*.dot      diff=astextplain
+*.DOT      diff=astextplain
+*.pdf      diff=astextplain
+*.PDF      diff=astextplain
+*.rtf      diff=astextplain
+*.RTF      diff=astextplain
+*.md       text diff=markdown
+*.tex      text diff=tex
+*.adoc     text
+*.textile  text
+*.mustache text
+*.csv      text
+*.tab      text
+*.tsv      text
+*.txt      text
+*.sql      text
+*.ps1      text eol=crlf
+
+# Graphics
+*.png      binary
+*.jpg      binary
+*.jpeg     binary
+*.gif      binary
+*.tif      binary
+*.tiff     binary
+*.ico      binary
+# SVG treated as an asset (binary) by default.
+*.svg      text
+# If you want to treat it as binary,
+# use the following line instead.
+# *.svg    binary
+*.eps      binary
+
+# Scripts
+*.bash     text eol=lf
+*.fish     text eol=lf
+*.sh       text eol=lf
+# These are explicitly windows files and should use crlf
+*.bat      text eol=crlf
+*.cmd      text eol=crlf
+
+# web frontend stack -- force LF so SRI hashes are always correct
+*.html     text eol=lf
+*.htm      text eol=lf
+*.css      text eol=lf
+*.min.css  text eol=lf
+*.js       text eol=lf
+*.min.js   text eol=lf
+*.php      text eol=lf
+
+# Visual Studio projects (Rider also)
+*.cs     diff=csharp
+*.sln    merge=union
+*.csproj merge=union
+*.vbproj merge=union
+*.fsproj merge=union
+*.dbproj merge=union
+
+# Serialisation
+*.json     text
+*.toml     text
+*.xml      text
+*.yaml     text
+*.yml      text
+
+# Archives
+*.7z       binary
+*.gz       binary
+*.tar      binary
+*.tgz      binary
+*.zip      binary
+
+# Text files where line endings should be preserved
+*.patch    -text
+
+#
+# Exclude files from exporting
+#
+
+.gitattributes  export-ignore
+.gitignore      export-ignore
+.gitkeep        export-ignore
+.idea           export-ignore
+.vscode         export-ignore

.gitignore

@@ -1,11 +1,73 @@
-# ---> VisualStudioCode
+### JetBrains template
-.vscode/*
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
-!.vscode/settings.json
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
-!.vscode/tasks.json
-!.vscode/launch.json
-!.vscode/extensions.json
-*.code-workspace
 
-# Local History for Visual Studio Code
+# User-specific stuff
-.history/
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Gradle
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# Gradle and Maven with auto-import
+# When using Gradle or Maven with auto-import, you should exclude module files,
+# since they will be recreated, and may cause churn.  Uncomment if using
+# auto-import.
+# .idea/artifacts
+# .idea/compiler.xml
+# .idea/jarRepositories.xml
+# .idea/modules.xml
+# .idea/*.iml
+# .idea/modules
+# *.iml
+# *.ipr
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based Rest Client
+.idea/httpRequests
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
 

README.md

@@ -3,14 +3,69 @@
 PowerShell cmdlet (module/function) to send a *magic packet* based on provided MAC address(es). Comment-based help is
 included in the source-code: `Get-Help Send-MagicPacket -Full`
 
+## Contents
+
+<!-- toc -->
+
+- [Installation and verification](#installation-and-verification)
+    * [Example: Auto-load for current user](#example-auto-load-for-current-user)
+- [Overview](#overview)
+- [Broadcast considerations](#broadcast-considerations)
+- [Pipeline](#pipeline)
+- [Module or Function](#module-or-function)
+- [Feedback](#feedback)
+
+<!-- tocstop -->
+
 ## Installation and verification
 
-Downloads are available
+Downloads are available via [my git server](https://git.asifbacchus.dev/asif/ps-cmdlet-wol/releases/latest)
-via [my git server (https://git.asifbacchus.dev/asif/ps-cmdlet-wol)](https://git.asifbacchus.dev/asif/ps-cmdlet-wol)
+and [GitHub](https://github.com/asifbacchus/ps-cmdlet-wol/releases/latest). You may verify the cmdlet's integrity
-and [GitHub (https://github.com/asifbacchus/ps-cmdlet-wol)](https://github.com/asifbacchus/ps-cmdlet-wol). You may
+using [CodeNotary](https://codenotary.io) via `vcn authenticate` or by dropping the downloaded script and/or manifest
-verify the cmdlet's integrity using [CodeNotary](https://codenotary.io) via `vcn authenticate` or by dropping the
+onto their verification webpage at [https://verify.codenotary.io](https://verify.codenotary.io). Please always try to
-downloaded script onto their verification webpage at [https://verify.codenotary.io](https://verify.codenotary.io).
+verify downloaded scripts and software regardless of the source!
-Please always try to verify downloaded scripts and software regardless of the source!
+
+If you are integrating this function with your own project or want to manually load the module as needed, then save the
+module and manifest file wherever it is convenient for you. If you want to auto-load this function so it is available
+automatically in any PowerShell session then you *must* extract it to a directory named **wol-magicPacket** somewhere
+defined in your `PSModulePath` depending on your use-case. More information can be found directly from
+Microsoft [here](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_modules?view=powershell-7.1#short-description)
+.
+
+### Example: Auto-load for current user
+
+Here's a complete example assuming I want the module automatically available for all sessions running under my user
+account:
+
+```powershell
+# download version 2.0
+Invoke-WebRequest -Uri https://git.asifbacchus.dev/asif/ps-cmdlet-wol/archive/v2.0.zip -OutFile "$Env:DOWNLOADS\ps-cmdlet-wol.zip"
+
+# Get PSModulePath
+# You should see a user-level modules path in the form of either:
+#  C:\Users\Username\Documents\WindowsPowerShell\Modules  -OR-
+#  C:\Users\Username\Documents\PowerShell\Modules
+$Env:PSModulePath
+
+# change directory to the appropriate path from above
+Set-Location "C:\Users\Username\Documents\WindowsPowerShell\Modules"
+
+# extract files and rename directory
+Expand-Archive -Path "$Env:DOWNLOADS\ps-cmdlet-wol.zip" -DestinationPath .\
+Rename-Item -Path ps-cmdlet-wol -NewName wol-magicPacket
+
+# confirm: you should see a directory named 'wol-magicPacket'
+gci
+
+# confirm: you should see the manifest and module within the wol-magicPacket folder
+gci .\wol-magicPacket
+```
+
+Now, close and re-open PowerShell and the `Send-MagicPacket` function should be available:
+
+```powershell
+Get-Command Send-MagicPacket
+```
 
 ## Overview
 

wol-magicPacket.psm1

@@ -50,7 +50,6 @@ function Send-MagicPacket
                 ValueFromPipelineByPropertyName,
                 HelpMessage = "Please provide one or more MAC addresses. You may use a colon (:) or a hypen (-) to separate hex values."
         )]
-        [ValidatePattern('^([0-9A-F]{2}[:-]){5}([0-9A-F]{2})$')]
         [String[]]
         $MacAddress,
 
@@ -83,6 +82,13 @@ function Send-MagicPacket
     {
         foreach ($addr in $MacAddress)
         {
+            # validate MAC address format or write error and continue
+            if (!($addr -match '^([0-9A-F]{2}[:-]){5}([0-9A-F]{2})$'))
+            {
+                Write-Error "Invalid MAC address: $addr"
+                continue
+            }
+
             # convert MAC address to magic packet
             try
             {
@@ -97,7 +103,7 @@ function Send-MagicPacket
             }
             catch
             {
-                Write-Warning "Unable to process MAC address: $thisMacAddress"
+                Write-Error "Unable to process MAC address: $thisMacAddress"
                 continue
             }
 
@@ -112,7 +118,7 @@ function Send-MagicPacket
             }
             catch
             {
-                Write-Warning "Unable to send magic packet for '$addr'"
+                Write-Error "Unable to send magic packet for '$addr'"
                 continue
             }
         }
@@ -125,3 +131,5 @@ function Send-MagicPacket
         $UdpClient.Dispose()
     }
 }
+
+Export-ModuleMember -Function Send-MagicPacket