Merge pull request #17 from isjwuk/Get-MatchingPostcodes

Get matching postcodes implemented

Posh-Postcodes.io.psd1

@@ -68,15 +68,17 @@ Copyright = ''
 # Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
 NestedModules = @(  '.\methods\Get-PostcodeInfo.psm1',
                     '.\methods\Test-Postcode.psm1',
-                    '.\methods\Get-NearestPostcode.psm1'
-                    '.\methods\Get-RandomPostcode.psm1'
+                    '.\methods\Get-NearestPostcode.psm1',
+                    '.\methods\Get-RandomPostcode.psm1',
+                    '.\methods\Get-MatchingPostcode.psm1'
                 )
 
 # Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.
 FunctionsToExport = @('Get-PostcodeInfo',
                 'Test-Postcode',
                 'Get-NearestPostcode',
-                'Get-RandomPostcode'
+                'Get-RandomPostcode',
+                'Get-MatchingPostcode'
                 )
 
 # Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.

README.md

@@ -78,7 +78,7 @@ Get-Help Get-NearestPostcode -ShowWindow
 ## Testing
 Pester is used for unit testing.
 ```powershell
-Invoke-Pester .\tests\*.Tests.ps1
+Invoke-Pester .\tests\*.Tests.ps1 -Output detailed
 ``` 
 
 PSScriptAnalyzer is used for identifying common issues

methods/Get-MatchingPostcode.psm1

@@ -1,24 +1,40 @@
-#TODO Complete this function
+$API_ROOT="https://api.postcodes.io"
 <#
 .SYNOPSIS
-    Convenience method to return an list of matching postcodes.
+    Submit a postcode query and receive a complete list of postcode matches and all associated postcode data.
 .DESCRIPTION
-    A longer description of the function, its purpose, common use cases, etc.
-.NOTES
-    Information or caveats about the function e.g. 'This function is not supported in Linux'
-.LINK
-    Specify a URI to a help page, this will show when Get-Help -Online is used.
+    This is essentially a postcode search which prefix matches and returns postcodes in sorted order (case insensitive)
 .EXAMPLE
-    Test-MyTestFunction -Verbose
-    Explanation of the function or its result. You can include multiple examples with additional .EXAMPLE lines
+    Get-MatchingPostcode -PostcodeStart "MK3 6E" | Select postcode
+    Return the 9 postcodes that start "MK3 6E"
+.EXAMPLE
+    Get-MatchingPostcode -PostcodeStart "N1 " -limit 30 | Select postcode
+    Return the first 30 postcodes (in alphabetical order) that have the N1 outcode
+.EXAMPLE
+    Get-MatchingPostcode -PostcodeStart "SW11 1A" -limit 20
+    Return the 18 postcodes that start "SW11 1A" including all the associated details.
 #>
 function Get-MatchingPostcode {
   [CmdletBinding()]
   param(
-#    [parameter(ValueFromPipeline)]
+        # Filters random postcodes by outcode. Returns null if invalid outcode.
+        [Parameter(Mandatory=$true,ValueFromPipeline=$true)]
+        [string]$PostcodeStart,
+        #(not required) Limits number of postcodes matches to return. Defaults to 10. Needs to be less than 100.
+        [Parameter(Mandatory=$false)]
+        [ValidateRange(1,99)]
+        [int]$limit=10
   )
 
   process {
-    #TODO
+    $result=Invoke-RestMethod -Uri "$API_ROOT/postcodes?query=$PostcodeStart&limit=$limit" -Method Get -SkipHttpErrorCheck
+    switch ($result.status) {
+        200 {
+           $result.result
+          }
+        Default {
+            throw $result.error
+        }
+    }
   }
 }

tests/Get-MatchingPostcode.Tests.ps1

@@ -0,0 +1,23 @@
+# Pester Tests for Get-MatchingPostcode
+BeforeAll {
+    Import-Module $PSScriptRoot/../Posh-Postcodes.io.psd1
+}
+Describe 'Get-MatchingPostcode' {
+    It 'Given a full postcode returns postcode data for that postcode' {
+        $result=Get-MatchingPostcode -PostcodeStart 'SW1A 1AA'
+        $result.count | Should -Be 1
+    }
+    It 'Given a partial postcode returns postcode data for many postcodes' {
+        $result=Get-MatchingPostcode -PostcodeStart 'SW1A 1A'
+        $result.count | Should -Be 4
+    }
+    It 'Given two valid outcode on the pipeline, it returns values for both' {
+        $result='GU2 7X','GU2 7Y' | Get-MatchingPostcode -limit 20
+        $result.count | Should -Be 24
+    }
+    It 'Given a nonsense partial it returns no data'{
+        $result=Get-MatchingPostcode -PostcodeStart 'banana'
+        $result | Should -Be $null
+    }
+
+}