updates docs, adds unzip func for bz2 gz tar msu¬

- Added functionality for unzipping/decompressing bzip gzip tar exe (self extracting) and msu (ms update) files to coincide with added functionality to win_zip¬
  - Added functionality requires PSCX (it will be installed if it can't be imported)¬¬
    - First try with chocolatey, if fail, direct install from msi
- Added recurse param to recursively unzip files from a compressed folder¬
  - useful for example: unzipping a Log.zip file that contains a load of .gz files¬
    - setting rm param to true will remove all compressed files after decompressing¬

windows/win_unzip.ps1

@@ -26,15 +26,17 @@ $result = New-Object psobject @{
     changed = $false
 }
 
-If ($params.zip) {
+If ($params.src) {
-    $zip = $params.zip.toString()
+    $src = $params.src.toString()
 
-    If (-Not (Test-Path -path $zip)){
+    If (-Not (Test-Path -path $src)){
-        Fail-Json $result "zip file: $zip does not exist."
+        Fail-Json $result "src file: $src does not exist."
     }
+
+    $ext = [System.IO.Path]::GetExtension($dest)
 }
 Else {
-    Fail-Json $result "missing required argument: zip"
+    Fail-Json $result "missing required argument: src"
 }
 
 If (-Not($params.dest -eq $null)) {
@@ -53,22 +55,120 @@ Else {
     Fail-Json $result "missing required argument: dest"
 }
 
-Try {
+If ($params.recurse -eq "true" -Or $params.recurse -eq "yes") {
-    $shell = New-Object -ComObject Shell.Application
+    $recurse = $true
-    $shell.NameSpace($dest).copyhere(($shell.NameSpace($zip)).items(), 20)
-    $result.changed = $true
 }
-Catch {
+Else {
-    # Used to allow reboot after exe hotfix extraction (Windows 2008 R2 SP1)
+    $recurse = $false
-    # This will have no effect in most cases.
-    If (-Not ([System.IO.Path]::GetExtension($zip) -match ".exe")){
-        $result.changed = $false
-        Fail-Json $result "Error unzipping $zip to $dest"
-    }
 }
 
 If ($params.rm -eq "true" -Or $params.rm -eq "yes"){
-    Remove-Item $zip -Recurse -Force
+    $rm = $true
+    Set-Attr $result.win_unzip "rm" "true"
+}
+Else {
+    $rm = $false
+}
+
+If ($ext -eq ".zip" -And $recurse -eq $false) {
+    Try {
+        $shell = New-Object -ComObject Shell.Application
+        $shell.NameSpace($dest).copyhere(($shell.NameSpace($src)).items(), 20)
+        $result.changed = $true
+    }
+    Catch {
+        Fail-Json $result "Error unzipping $src to $dest"
+    }
+}
+# Need PSCX
+Else {
+    # Requires PSCX, will be installed if it isn't found
+    # Pscx-3.2.0.msi
+    $url = "http://download-codeplex.sec.s-msft.com/Download/Release?ProjectName=pscx&DownloadId=923562&FileTime=130585918034470000&Build=20959"
+    $msi = "C:\Pscx-3.2.0.msi"
+
+    # Check if PSCX is installed
+    $list = Get-Module -ListAvailable
+    # If not download it and install
+    If (-Not ($list -match "PSCX")) {
+        # Try install with chocolatey
+        Try {
+            cinst -force PSCX
+            $choco = $true
+        }
+        Catch {
+            $choco = $false
+        }
+        # install from downloaded msi if choco failed or is not present
+        If ($choco -eq $false) {
+            Try {
+                $client = New-Object System.Net.WebClient
+                $client.DownloadFile($url, $msi)
+            }
+            Catch {
+                Fail-Json $result "Error downloading PSCX from $url and saving as $dest"
+            }
+            Try {
+                msiexec.exe /i $msi /qb
+                # Give it a chance to install, so that it can be imported
+                sleep 10
+            }
+            Catch {
+                Fail-Json $result "Error installing $msi"
+            }
+        }
+        Set-Attr $result.win_zip "pscx_status" "pscx was installed"
+        $installed = $true
+    }
+    Else {
+        Set-Attr $result.win_zip "pscx_status" "present"
+    }
+
+    # Import
+    Try {
+        If ($installed) {
+            Import-Module 'C:\Program Files (x86)\Powershell Community Extensions\pscx3\pscx\pscx.psd1'
+        }
+        Else {
+            Import-Module PSCX
+        }
+    }
+    Catch {
+        Fail-Json $result "Error importing module PSCX"
+    }
+
+    Try {
+        If ($recurse) {
+            Expand-Archive -Path $src -OutputPath $dest -Force
+
+            If ($rm) {
+                Get-ChildItem $dest -recurse | Where {$_.extension -eq ".gz" -Or $_.extension -eq ".zip" -Or $_.extension -eq ".bz2" -Or $_.extension -eq ".tar" -Or $_.extension -eq ".msu"} | % {
+                    Expand-Archive $_.FullName -OutputPath $dest  -Force
+                    Remove-Item $_.FullName -Force
+                }
+            }
+            Else {
+                Get-ChildItem $dest -recurse | Where {$_.extension -eq ".gz" -Or $_.extension -eq ".zip" -Or $_.extension -eq ".bz2" -Or $_.extension -eq ".tar" -Or $_.extension -eq ".msu"} | % {
+                    Expand-Archive $_.FullName -OutputPath $dest  -Force
+                }
+            }
+        }
+        Else {
+            Expand-Archive -Path $src -OutputPath $dest -Force
+        }
+    }
+    Catch {
+        If ($recurse) {
+            Fail-Json "Error recursively expanding $src to $dest"
+        }
+        Else {
+            Fail-Json "Error expanding $src to $dest"
+        }
+    }
+}
+
+If ($rm -eq $true){
+    Remove-Item $src -Recurse -Force
     Set-Attr $result.win_unzip "rm" "true"
 }
 
@@ -77,8 +177,17 @@ If ($params.restart -eq "true" -Or $params.restart -eq "yes") {
     Set-Attr $result.win_unzip "restart" "true"
 }
 
-
+# Fixes a fail error message (when the task actually succeeds) for a "Convert-ToJson: The converted JSON string is in bad format"
-Set-Attr $result.win_unzip "zip" $zip.toString()
+# This happens when JSON is parsing a string that ends with a "\", which is possible when specifying a directory to download to.
+# This catches that possible error, before assigning the JSON $result
+If ($src[$src.length-1] -eq "\") {
+    $src = $src.Substring(0, $src.length-1)
+}
+If ($dest[$dest.length-1] -eq "\") {
+    $dest = $dest.Substring(0, $dest.length-1)
+}
+Set-Attr $result.win_unzip "src" $src.toString()
 Set-Attr $result.win_unzip "dest" $dest.toString()
+Set-Attr $result.win_unzip "recurse" $recurse.toString()
 
 Exit-Json $result;

windows/win_unzip.py

@@ -27,11 +27,11 @@ module: win_unzip
 version_added: ""
 short_description: Unzips compressed files on the Windows node
 description:
-     - Unzips compressed files, and can force reboot (if needed, i.e. such as hotfixes). If the destination directory does not exist, it will be created before unzipping the file. Specifying rm parameter will allow removal of the zip file after extraction.
+     - Unzips compressed files, and can force reboot (if needed, i.e. such as hotfixes). Has ability to recursively unzip files within the src zip file provided using Read-Archive and piping to Expand-Archive (Using PSCX). If the destination directory does not exist, it will be created before unzipping the file. If a .zip file is specified as src and recurse is true then PSCX will be installed.  Specifying rm parameter will allow removal of the src file after extraction.
 options:
-  zip:
+  src:
     description:
-      - Zip file to be unzipped (provide absolute path)
+      - File to be unzipped (provide absolute path)
     required: true
     default: null
     aliases: []
@@ -45,14 +45,32 @@ options:
     description:
       - Remove the zip file, after unzipping
     required: no
+    choices:
+      - true
+      - false
+      - yes
+      - no
     default: false
     aliases: []
+  recurse:
+    description:
+      - Recursively expand zipped files within the src file.
+    required: no
+    default: false
+    choices:
+      - true
+      - false
+      - yes
+      - no
+    aliases: []
   restart:
     description:
       - Restarts the computer after unzip, can be useful for hotfixes such as http://support.microsoft.com/kb/2842230 (Restarts will have to be accounted for with wait_for module)
     choices:
       - true
       - false
+      - yes
+      - no
     required: false
     default: false
     aliases: []
@@ -60,11 +78,31 @@ author: Phil Schwartz
 '''
 
 EXAMPLES = '''
-# This unzips hotfix http://support.microsoft.com/kb/2842230 and forces reboot (for hotfix to take effect)
-$ ansible -i hosts -m win_unzip -a "zip=C:\\463984_intl_x64_zip.exe dest=C:\\Hotfix restart=true" all
 # This unzips a library that was downloaded with win_get_url, and removes the file after extraction
-$ ansible -i hosts -m win_unzip -a "zip=C:\\LibraryToUnzip.zip dest=C:\\Lib rm=true" all
+$ ansible -i hosts -m win_unzip -a "src=C:\\LibraryToUnzip.zip dest=C:\\Lib rm=true" all
 # Playbook example
+
+# Simple unzip
+---
+- name: Unzip a bz2 (BZip) file
+  win_unzip:
+    src: "C:\Users\Phil\Logs.bz2"
+    dest: "C:\Users\Phil\OldLogs"
+
+# This playbook example unzips a .zip file and recursively decompresses the contained .gz files and removes all unneeded compressed files after completion.
+---
+- name: Unzip ApplicationLogs.zip and decompress all GZipped log files
+  hosts: all
+  gather_facts: false
+  tasks:
+    - name: Recursively decompress GZ files in ApplicationLogs.zip
+      win_unzip:
+        src: C:\Downloads\ApplicationLogs.zip
+        dest: C:\Application\Logs
+        recurse: yes
+        rm: true
+
+# Install hotfix (self-extracting .exe)
 ---
 - name: Install WinRM PowerShell Hotfix for Windows Server 2008 SP1
   hosts: all
@@ -76,8 +114,9 @@ $ ansible -i hosts -m win_unzip -a "zip=C:\\LibraryToUnzip.zip dest=C:\\Lib rm=t
       dest: 'C:\\463984_intl_x64_zip.exe'
   - name: Unzip hotfix
     win_unzip:
-      zip: "C:\\463984_intl_x64_zip.exe"
+      src: "C:\\463984_intl_x64_zip.exe"
       dest: "C:\\Hotfix"
+      recurse: true
       restart: true
   - name: Wait for server reboot...
   local_action: