Add -PassThru support for methods to persist to disk (#32)

* Add -PassThru to Get-BloggerPost #26

* Added -PassThru to ConvertTo-HtmlFromMarkdown and tests

* Add -PassThru to ConvertTo-MarkdownFromHtml

Author: bryanbcook

README.md

@@ -55,11 +55,11 @@ A PowerShell library for publishing markdown files authored in markdown to Blogg
 1. Fetch an individual post from your blog
 
    ```
-   Get-BloggerPost -PostId <postid>
+   $post = Get-BloggerPost -PostId <postid>
    ```
-   
-   You can also persist the post to disk as HTML or markdown in the current directory. 
-   
+
+   You can also persist the post to disk as HTML or markdown in the current directory.
+
    When using `HTML` format, files are saved as `<postid>.html`
 
    When using `Markdown` format, files are saved as `<title>.md`
@@ -84,6 +84,12 @@ A PowerShell library for publishing markdown files authored in markdown to Blogg
    Get-BloggerPost -PostId <postId> -OutDirectory ".\Blog" -FolderDateFormat "YYYY\\MM" -Format Markdown
    ```
 
+   When persisting to disk, the post object is not returned unless `-PassThru` is specified.
+
+   ```
+   $post = Get-BloggerPost -PostId <postid> -Format Markdown -PassThru
+   ```
+
 1. Publish a markdown file to your blog as draft
 
    ```

src/public/ConvertTo-HtmlFromMarkdown.ps1

@@ -8,20 +8,38 @@
 .PARAMETER OutFile
   The resulting html. If this parameter is not specified an HTML file with the same name of the markdown file will be created.
 
+.PARAMETER PassThru
+  If specified, the content of the HTML file will be returned as well as written to disk.
+
+.EXAMPLE
+  # obtain an HTML representation of the markdown file
+  $html = ConvertTo-HtmlFromMarkdown -File "C:\path\to\file.md"
+
+.EXAMPLE
+  # write the HTML representation of the markdown file to disk
+  ConvertTo-HtmlFromMarkdown -File "C:\path\to\file.md" -OutFile "C:\path\to\file.html"
+
+.EXAMPLE
+  # write the HTML representation of the markdown file to disk and return the content
+  $html = ConvertTo-HtmlFromMarkdown -File "C:\path\to\file.md" -OutFile "C:\path\to\file.html" -PassThru
 #>
 function ConvertTo-HtmlFromMarkdown {
+  [CmdletBinding(DefaultParameterSetName = "Default")]
   param(
-    [Parameter(Mandatory = $true, HelpMessage = "Path to Markdown file")]
+    [Parameter(Mandatory = $true, ParameterSetName = "Default")]
+    [Parameter(Mandatory = $true, ParameterSetName = "Persist")]
     [ValidateScript({ Test-Path $_ -PathType Leaf })]
     [string]$File,
 
-    [Parameter(HelpMessage = "File path to create")]
-    #[ValidateScript({ Test-Path $_ -Include "*.html" -PathType Container})]
-    [string]$OutFile
+    [Parameter(ParameterSetName = "Persist")]
+    [string]$OutFile,
+
+    [Parameter(ParameterSetName = "Persist")]
+    [switch]$PassThru
   )
 
   # ensure that the file is an absolute path because pandoc.exe doesn't like powershell relative paths
-  $File = (Resolve-Path $File).Path
+  $File = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($File)
 
   # Use pandoc to convert the markdown to Html 
   $pandocArgs = "`"{0}`" " -f $File
@@ -41,8 +59,10 @@ function ConvertTo-HtmlFromMarkdown {
 
   if (!($OutFile)) {
     $OutFile = Join-Path (Split-Path $File -Parent) ((Split-Path $File -LeafBase) + ".html")
+    # ensure that the file is an absolute path because pandoc.exe doesn't like powershell relative paths
     Write-Verbose "Using OutFile: $OutFile"
   }
+  $OutFile = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($OutFile)
 
   $pandocArgs += "-o `"{0}`" " -f $OutFile
 
@@ -60,7 +80,14 @@ function ConvertTo-HtmlFromMarkdown {
 
   Set-Content -Path $OutFile -Value $content
 
-  Remove-Item $OutFile
+  if (!($PSCmdlet.ParameterSetName -eq "Persist")) {
+    Write-Verbose "Removing temporary file: $OutFile"
+    Remove-Item $OutFile
 
-  return $content
+    return $content
+  }
+
+  if ($PassThru.IsPresent -and $PassThru) {
+    return $content
+  }
 }

src/public/ConvertTo-MarkdownFromHtml.ps1

@@ -11,6 +11,32 @@
 .PARAMETER OutFile
   The resulting markdown file, if specified.
 
+.PARAMETER PassThru
+  Return markdown content as output, in addition to writing it to disk.
+
+.EXAMPLE
+  # Convert HTML content to Markdown and save to a file
+  ConvertTo-MarkdownFromHtml -Content "<h1>Hello World</h1>" -OutFile "C:\path\to\file.md"
+
+.EXAMPLE
+  # Convert a HTML file to Markdown and save to a file
+  ConvertTo-MarkdownFromHtml -File "C:\path\to\file.html" -OutFile "C:\path\to\file.md"
+
+.EXAMPLE
+  # Convert a HTML file to Markdown and return the content
+  $content = ConvertTo-MarkdownFromHtml -File "C:\path\to\file.html"
+
+.EXAMPLE
+  # Convert HTML content to Markdown and return the content
+  $content = ConvertTo-MarkdownFromHtml -Content "<h1>Hello World</h1>"
+
+.EXAMPLE
+  # Convert HTML content to Markdown and save to a file, returning the content
+  $content = ConvertTo-MarkdownFromHtml -Content "<h1>Hello World</h1>" -OutFile "C:\path\to\file.md" -PassThru
+
+.EXAMPLE
+  # Convert a HTML file to Markdown and save to a file, returning the content
+  $content = ConvertTo-MarkdownFromHtml -File "C:\path\to\file.html" -OutFile "C:\path\to\file.md" -PassThru
 #>
 function ConvertTo-MarkdownFromHtml {
   param(
@@ -22,8 +48,12 @@ function ConvertTo-MarkdownFromHtml {
     [string]$Content,
 
     [Parameter(ParameterSetName = "FromFile")]
-    [Parameter(Mandatory=$false, ParameterSetName = "FromContent")]
-    [string]$OutFile
+    [Parameter(ParameterSetName = "FromContent")]
+    [string]$OutFile,
+
+    [Parameter(ParameterSetName = "FromFile")]
+    [Parameter(ParameterSetName = "FromContent")]
+    [switch]$PassThru
   )
 
   # when FromContent is specified, write the content to a temporary file
@@ -69,5 +99,9 @@ function ConvertTo-MarkdownFromHtml {
     Remove-Item $OutFile
   } 
 
-  return $content
+  # return output if not persisting to disk or PassThru is specified
+  if (!$PSBoundParameters.ContainsKey("OutFile") -or ($PassThru.IsPresent -and $PassThru)) {
+    Write-Verbose "Returning content"
+    return $content
+  }
 }

src/public/Get-BloggerPost.ps1

@@ -18,14 +18,28 @@
 .PARAMETER OutDirectory
   The directory where the HTML file will be saved. If not specified, uses the current directory.
 
+.PARAMETER PassThru
+  If specified, the function will return the post object instead of just saving it to a file
+
 .EXAMPLE
-  Get-BloggerPost -PostId "1234567890123456789"
+  # obtain a post from the blog defined in the user preferences
+  $post = Get-BloggerPost -PostId "1234567890123456789"
 
 .EXAMPLE
+  # obtain a post from a specified blog and save it as HTML in a specific directory
   Get-BloggerPost -BlogId "9876543210987654321" -PostId "1234567890123456789" -Format HTML -OutDirectory "C:\temp"
 
 .EXAMPLE
+  # obtain a post from a specified blog and save it as Markdown in a specific directory with a date-based folder structure
   Get-BloggerPost -BlogId "9876543210987654321" -PostId "1234567890123456789" -Format Markdown -DateFormat "YYYY\\MM" -OutDirectory "C:\blogposts"
+
+.EXAMPLE
+  # obtain a post from a specified blog and save it as JSON in the current directory
+  Get-BloggerPost -BlogId "9876543210987654321" -PostId "1234567890123456789" -Format JSON
+
+.EXAMPLE
+  # obtain a post from a specified blog, write it to disk and return the post object
+  $post = Get-BloggerPost -BlogId "9876543210987654321" -PostId "1234567890123456789" -Format Markdown -PassThru
 #>
 Function Get-BloggerPost {
   [CmdletBinding()]
@@ -46,7 +60,10 @@ Function Get-BloggerPost {
     [string]$FolderDateFormat,
 
     [Parameter(ParameterSetName = "Persist")]
-    [string]$OutDirectory = (Get-Location).Path
+    [string]$OutDirectory = (Get-Location).Path,
+
+    [Parameter(ParameterSetName = "Persist")]
+    [switch]$PassThru
   )
 
   if (!$PSBoundParameters.ContainsKey("BlogId")) {
@@ -56,10 +73,6 @@ Function Get-BloggerPost {
     }
   }
 
-  if ([string]::IsNullOrEmpty($PostId)) {
-    throw "PostId is required."
-  }
-
   try {
     $uri = "https://www.googleapis.com/blogger/v3/blogs/$BlogId/posts/$PostId"
 
@@ -130,7 +143,7 @@ Function Get-BloggerPost {
           $file = "$title.md"
 
           $filePath = Join-Path -Path $OutDirectory -ChildPath $file
-          ConvertTo-MarkdownFromHtml -Content $result.content -OutFile $filePath > $null
+          ConvertTo-MarkdownFromHtml -Content $result.content -OutFile $filePath
           Set-MarkdownFrontMatter -File $filePath -Replace $frontMatter
           Write-Verbose "Post content saved to: $filePath"
         }
@@ -144,7 +157,10 @@ Function Get-BloggerPost {
       }  
 
       # Return the post object for further processing if needed
-      return $result
+      if (!($PSCmdlet.ParameterSetName -eq "Persist") -or ($PassThru.IsPresent -and $PassThru)) {
+        Write-Verbose "Returning blog post object"
+        return $result
+      }
     }
     catch {
       throw "Failed to save post content: $($_.Exception.Message)"

src/tests/ConvertTo-HtmlFromMarkdown.Tests.ps1

@@ -0,0 +1,64 @@
+Describe "ConvertTo-HtmlFromMarkdown" {
+  BeforeAll {
+    Import-Module $PSScriptRoot\_TestHelpers.ps1 -Force
+
+    $script:InFile = "TestDrive:\123.md"
+    $script:OutFile = "TestDrive:\123.html"
+
+    Set-MarkdownFile -Path $script:InFile -Content "# Hello World"
+  }
+
+  BeforeEach {
+    Import-Module $PSScriptRoot\..\PSBlogger.psm1 -Force
+  }
+
+  AfterEach {
+    if (Test-Path $script:OutFile) {
+      Remove-Item $script:OutFile -Force
+    }
+  }
+
+  It "Should convert Markdown file to HTML" {
+    # act
+    $result = ConvertTo-HtmlFromMarkdown -File $script:InFile
+
+    # assert
+    $result | Should -Not -BeNullOrEmpty
+    $result | Should -BeLike "<h1*>Hello World</h1>*"
+  }
+
+  It "Should not produce an HTML file if OutFile is not specified" {
+    # act
+    $result = ConvertTo-HtmlFromMarkdown -File $script:InFile
+
+    # assert
+    $result | Should -Not -BeNullOrEmpty
+    Test-Path $script:OutFile | Should -BeFalse
+  }
+
+  It "Should create an HTML file when OutFile is specified" {
+    # act
+    ConvertTo-HtmlFromMarkdown -File $script:InFile -OutFile $script:OutFile
+
+    # assert
+    Test-Path $script:OutFile | Should -BeTrue
+  }
+
+  It "Should not return content if OutFile is specified without PassThru" {
+    # act
+    $result = ConvertTo-HtmlFromMarkdown -File $script:InFile -OutFile $script:OutFile
+
+    # assert
+    $result | Should -BeNullOrEmpty
+    Test-Path $script:OutFile | Should -BeTrue
+  }
+
+  It "Should return content if PassThru is specified with OutFile" {
+    # act
+    $result = ConvertTo-HtmlFromMarkdown -File $script:InFile -OutFile $script:OutFile -PassThru
+
+    # assert
+    $result | Should -Not -BeNullOrEmpty
+    Test-Path $script:OutFile | Should -BeTrue
+  }
+}