Merge pull request #43 from vexx32/dev

v0.39: Objection!

Author: vexx32

Build/Build.ps1

@@ -7,12 +7,10 @@ if ($env:APPVEYOR_REPO_BRANCH -eq 'master' -and -not $env:APPVEYOR_PULL_REQUEST_
     $Task = 'Deploy'
 }
 
-# Grab nuget bits, install modules, set build variables, start build.
+# Grab nuget bits, set build variables, start build.
 Get-PackageProvider -Name NuGet -ForceBootstrap > $null
 
-Install-Module Psake, PSDeploy, BuildHelpers -Force -Scope CurrentUser
-Install-Module Pester -Force -SkipPublisherCheck -Scope CurrentUser
-Import-Module Psake, BuildHelpers
+Import-Module -Name Psake, BuildHelpers
 
 Set-BuildEnvironment
 

Build/Psake.ps1

@@ -1,87 +1,115 @@
-# PSake makes variables declared here available in other scriptblocks
+[CmdletBinding()]
+param()
+# Psake makes variables declared here available in other scriptblocks
 # Init some things
 Properties {
     # Find the build folder based on build system
     $ProjectRoot = $env:BHProjectPath
     if (-not $ProjectRoot) {
-        $ProjectRoot = Resolve-Path "$PSScriptRoot\.."
+        $ProjectRoot = Resolve-Path -Path "$PSScriptRoot\.."
     }
 
-    $Timestamp = Get-Date -UFormat "%Y%m%d-%H%M%S"
-    $PSVersion = $PSVersionTable.PSVersion.Major
-    $TestFile = "TestResults_PS$PSVersion`_$TimeStamp.xml"
-    $lines = '----------------------------------------------------------------------'
+    $Timestamp = Get-Date -Format "yyyyMMdd-hhmmss"
+    $PSVersion = $PSVersionTable.PSVersion
+    $TestFile = "TestResults_PS${PSVersion}_${TimeStamp}.xml"
+    $Lines = '-' * 70
 
-    $Verbose = @{}
+    $DeploymentParams = @{
+        Path    = "$ProjectRoot"
+        Force   = $true
+        Recurse = $false # We keep psdeploy artifacts, avoid deploying those
+    }
     if ($ENV:BHCommitMessage -match "!verbose") {
-        $Verbose = @{Verbose = $True}
+        $DeploymentParams.Add('Verbose', $true)
+    }
+
+    $Continue = @{
+        InformationAction = if ($PSBoundParameters['InformationAction']) {
+                $PSBoundParameters['InformationAction']
+            }
+            else {
+                'Continue'
+            }
     }
 }
 
-Task Default -Depends Test
+Task 'Default' -Depends 'Test'
 
-Task Init {
-    $lines
-    Set-Location $ProjectRoot
-    "Build System Details:"
-    Get-Item ENV:BH*
-    "`n"
+Task 'Init' {
+    Set-Location -Path $ProjectRoot
+    Write-Information @Continue @"
+$Lines
+Build System Details:
+"@
+    Get-Item 'ENV:BH*'
 }
 
-Task Test -Depends Init {
-    $lines
-    "`n`tSTATUS: Testing with PowerShell $PSVersion"
-
+Task 'Test' -Depends 'Init' {
+    Write-Information @Continue @"
+$Lines
+STATUS: Testing with PowerShell $PSVersion
+"@
     # Testing links on github requires >= tls 1.2
     $SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol
     [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
 
+    # Import the module
+    Import-Module "$ProjectRoot\PSKoans\PSKoans.psd1"
+
     # Gather test results. Store them in a variable and file
-    $TestResults = Invoke-Pester -Path $ProjectRoot\Tests -PassThru -OutputFormat NUnitXml -OutputFile "$ProjectRoot\$TestFile"
+    $PesterParams = @{
+        Path         = "$ProjectRoot\Tests"
+        PassThru     = $true
+        OutputFormat = 'NUnitXml'
+        OutputFile   = "$ProjectRoot\$TestFile"
+    }
+    $TestResults = Invoke-Pester @PesterParams
+
     [Net.ServicePointManager]::SecurityProtocol = $SecurityProtocol
 
-    # In Appveyor?  Upload our tests! #Abstract this into a function?
+    # In Appveyor?  Upload our tests!
     If ($ENV:BHBuildSystem -eq 'AppVeyor') {
         (New-Object 'System.Net.WebClient').UploadFile(
             "https://ci.appveyor.com/api/testresults/nunit/$($env:APPVEYOR_JOB_ID)",
-            "$ProjectRoot\$TestFile" )
+            "$ProjectRoot\$TestFile"
+        )
     }
 
-    Remove-Item "$ProjectRoot\$TestFile" -Force -ErrorAction SilentlyContinue
+    Remove-Item -Path "$ProjectRoot\$TestFile" -Force -ErrorAction SilentlyContinue
+
     # Failed tests?
     # Need to tell psake or it will proceed to the deployment. Danger!
     if ($TestResults.FailedCount -gt 0) {
-        Write-Error "Failed '$($TestResults.FailedCount)' tests, build failed"
+        Write-Error "Failed $($TestResults.FailedCount) tests; build failed!"
     }
-    "`n"
 }
 
-Task Build -Depends Test {
-    $lines
+Task 'Build' -Depends 'Test' {
+    Write-Information @Continue @"
 
+$Lines
+"@
     # Load the module, read the exported functions, update the psd1 FunctionsToExport
     Set-ModuleFunctions
 
     # Bump the module version if we didn't already
-    Try {
-        $GalleryVersion = Get-NextPSGalleryVersion -Name $env:BHProjectName -ErrorAction Stop
+    try {
+        $GalleryVersion = Get-NextNugetPackageVersion -Name $env:BHProjectName -ErrorAction Stop
         $GithubVersion = Get-MetaData -Path $env:BHPSModuleManifest -PropertyName ModuleVersion -ErrorAction Stop
         if ($GalleryVersion -ge $GithubVersion) {
             Update-Metadata -Path $env:BHPSModuleManifest -PropertyName ModuleVersion -Value $GalleryVersion -ErrorAction stop
         }
     }
-    Catch {
-        "Failed to update version for '$env:BHProjectName': $_.`nContinuing with existing version"
+    catch {
+        Write-Information @Continue @"
+Failed to update version for '$env:BHProjectName': $_.
+Continuing with existing version.
+"@
     }
 }
 
 Task Deploy -Depends Build {
-    $lines
+    Write-Information $Lines @Continue
 
-    $Params = @{
-        Path    = "$ProjectRoot"
-        Force   = $true
-        Recurse = $false # We keep psdeploy artifacts, avoid deploying those : )
-    }
-    Invoke-PSDeploy @Verbose @Params
+    Invoke-PSDeploy @DeploymentParams
 }

PSKoans/Koans/Advanced Techniques/AboutRedirection.Koans.ps1

@@ -1,5 +1,5 @@
 #Requires -Module PSKoans
-[Koan(601)]
+[Koan(Position = 601)]
 param()
 <#
     Redirection

PSKoans/Koans/Cmdlets 1/AboutCompareObject.Koans.ps1

@@ -0,0 +1,33 @@
+#Requires -Module PSKoans
+[Koan(Position = 205)]
+param()
+<#
+    Compare-Object
+
+    Compare-Object is primarily for comparing collections of objects rather than individual
+    items, and is usually used to display data comparisons to the user.
+#>
+Describe 'Compare-Object' {
+
+    It 'compares collections of objects' {
+        $Comparison = @{
+            ReferenceObject  = 'this', 'is', 'the', 'reference'
+            DifferenceObject = 'these', 'is', 'the', 'difference'
+        }
+        $CompareData = Compare-Object @Comparison
+        $CompareData[0].InputObject | Should -Be '__'
+        $CompareData[0].SideIndicator | Should -Be '__'
+        $CompareData[0] | Should -BeOfType __
+    }
+
+    It 'can display items that occur in both sets' {
+        # By default, items that are the same in both collections are hidden.
+        $Comparison = @{
+            ReferenceObject  = 'this', 'is', 'the', 'reference'
+            DifferenceObject = 'these', 'is', 'the', 'difference'
+        }
+        $CompareData = Compare-Object @Comparison -IncludeEqual
+        $CompareData.SideIndicator -contains '==' | Should -BeTrue
+        $CompareData.Where{$_.InputObject -eq 'the'}.SideIndicator | Should -Be '__'
+    }
+}

PSKoans/Koans/Cmdlets 1/AboutGetHelpAndGetMember.Koans.ps1 renamed to PSKoans/Koans/Cmdlets 1/AboutDiscovery.Koans.ps1

@@ -1,28 +1,26 @@
 #Requires -Module PSKoans
-[Koan(201)]
+[Koan(Position = 201)]
 param()
 <#
-    Get-Help
+    Help & Discovery
 
-    Get-Help is a built-in PowerShell cmdlet that is used to retrieve help data for
-    cmdlets and functions. It contains usage examples, parameter information,
-    and a significant amount of otherwise difficult to discover tidbits.
+    PowerShell's help and discovery systems are a key component to its ecosystem. A great
+    many things can be learned simply by knowing where to look and which few cmdlets to
+    use in order to find what you're looking for.
 
-    Get-Member
-
-    Get-Member is another built-in cmdlet that is invaluable in retrieving
-    information about any object in PowerShell. It can be used to inspect the type
-    name of an object, as well as all available methods and properties that can be
-    accessed for that object.
-
-    These cmdlets are quintessential discovery tools, and regular use of them will
-    vastly expedite any unfamiliar task in PowerShell. Combined with well-placed
-    Google searches, it is possible to learn a significant amount about native
-    PowerShell cmdlets and functions, and more advanced .NET classes, and methods.
+    Discovery cmdlets are quintessential learning tools, and regular use of them will
+    vastly expedite any unfamiliar task in PowerShell. Combined with targeted online
+    searches, it is straightforward to learn a significant amount about native PowerShell
+    cmdlets and functions, as well as more advanced .NET classes, and methods.
 #>
-
 Describe 'Get-Help' {
+    <#
+        Get-Help
 
+        Get-Help is a built-in PowerShell cmdlet that is used to retrieve help data for
+        cmdlets and functions. It contains usage examples, parameter information, and
+        a significant amount of otherwise difficult to discover tidbits.
+    #>
     Context 'shows help information about cmdlets' {
         # Try calling 'Get-Help Get-Help' in a console to see the built in help available
         # for the help command.
@@ -55,11 +53,27 @@ Describe 'Get-Help' {
             $ParameterInfo.PipelineInput | Should -Be __
         }
         # Remember: if 'Get-Help Cmdlet-Name' doesn't show you all you need, try -Full. You'll need it.
+
+        It 'can search for commands by parameter names' {
+            $RemoteCommands = Get-Help -Name * -Parameter ComputerName |
+                Select-Object -ExpandProperty Name
+
+            $RemoteCommands.Count | Should -Be __
+
+            $RemoteCommands[4] | Should -Be __
+        }
     }
 }
 
 Describe 'Get-Member' {
-
+    <#
+        Get-Member
+
+        Get-Member is another built-in cmdlet that is invaluable in retrieving
+        information about any object in PowerShell. It can be used to inspect the type
+        name of an object, as well as all available methods and properties that can be
+        accessed for that object.
+    #>
     Context 'Members and methods of objects' {
 
         It 'can help you find useful properties' {
@@ -117,8 +131,8 @@ Describe 'Get-Member' {
     Context 'Members of objects returned from cmdlets' {
 
         It 'can help you discover information about unfamiliar objects' {
-            # Cmdlets also return objects! This cmdlet creates an empty .tmp file in a random location,
-            # and returns the object representation of this file.
+            # Cmdlets also return objects! This cmdlet creates an empty .tmp file in a random
+            # location, and returns the object representing this file.
             $TempFile = New-TemporaryFile
             Test-Path -Path $TempFile.FullName | Should -BeTrue
 
@@ -139,4 +153,66 @@ Describe 'Get-Member' {
             $MemberData | Should -BeOfType __
         }
     }
+}
+
+Describe 'Get-Command' {
+    <#
+        Get-Command
+
+        Get-Command is one of the most useful cmdlets for discovery. It allows you to
+        list all available commands, specify a module to look for available commands in,
+        and filter based on command name, module name, etc.
+
+        As the vast majority of PowerShell commands are packaged with help files, it is
+        also an invaluable tool in finding possible help topics to look up in the first
+        place!
+
+        When looking for related commands, use of the -Verb and -Noun search options
+        is often easier than figuring out how many wildcards you need in a -Name search.
+    #>
+    BeforeAll {
+        # Try calling Get-Command in a PowerShell console to see the typical output!
+        $Commands = Get-Command
+    }
+
+    It 'lists available commands' {
+        $Commands.Count | Should -Be __
+        $Commands[7].Name | Should -Be '__'
+    }
+
+    It 'indicates the type of command' {
+        $CommandTypes = $Commands | Select-Object -ExpandProperty CommandType | Sort-Object -Unique
+
+        @('__', '__', 'Cmdlet') | Should -Be $CommandTypes
+    }
+
+    It 'can filter the output by keywords' {
+        $Command = Get-Command -Name "*-Child*"
+        $CimCommand = Get-Command -Name '__'
+
+        $Command.CommandType | Should -Be 'Cmdlet'
+        $Command.Name | Should -Be '__'
+        $CimCommand.Name | Should -Be 'Get-CimClass'
+    }
+
+    It 'can look for commands by verb' {
+        $GetCommands = Get-Command -Verb 'Get'
+        $GetCommands.Count | Should -Be __
+
+        $GetCommands[4].Name | Should -Be '__'
+    }
+
+    It 'can look for commands by noun' {
+        $DateCommands = Get-Command -Noun 'Date'
+
+        $DateCommands.Count | Should -Be __
+        $DateCommands[0].Name | Should -Be '__'
+    }
+
+    It 'can look for commands by module' {
+        $KoanCommands = Get-Command -Module 'PSKoans'
+
+        $KoanCommands.Count | Should -Be __
+        $KoanCommands.Name | Should -Be @('__', '__', '__', '__')
+    }
 }

PSKoans/Koans/Cmdlets 1/AboutFindAndGetModule.Koans.ps1

@@ -0,0 +1,3 @@
+#Requires -Module PSKoans
+[Koan(Position = 212)]
+param()