win_lineinfile backrefs bug fix and updated examples. (#20926)

* Bug Fix for win_lineinfile and updated examples.

- changed $backrefs to a bool so it works with true/false/yes/no. This also fixes idempotency.
- Updated Docs with an example of using backrefs.

* Made suggested updates and converted two more parameters to "bool"

* Updated the Exception message

- Now contains the Windows Exception message as well as a custom message to help point in the right direction of a failed write.

* Updated Exception Handling

- Added Exception checks for Creating and removing the temporary files.
- Changed the ErrorAction on the copy tmpfile and remove tmp file to "Stop" to
  cause the exception handler to catch all errors so we can fail gracefully
  every time.

lib/ansible/modules/windows/win_lineinfile.ps1

@@ -29,11 +29,11 @@ $path= Get-Attr $params "path" $FALSE;
 $regexp = Get-Attr $params "regexp" $FALSE;
 $state = Get-Attr $params "state" "present";
 $line = Get-Attr $params "line" $FALSE;
-$backrefs = Get-Attr $params "backrefs" "no";
+$backrefs = Get-Attr -obj $params -name "backrefs" -default "no" -type "bool"
 $insertafter = Get-Attr $params "insertafter" $FALSE;
 $insertbefore = Get-Attr $params "insertbefore" $FALSE;
-$create = Get-Attr $params "create" "no";
-$backup = Get-Attr $params "backup" "no";
+$create = Get-Attr $params -name "create" -default "no" -type "bool";
+$backup = Get-Attr $params -name "backup" -default "no" -type "bool";
 $validate = Get-Attr $params "validate" $FALSE;
 $encoding = Get-Attr $params "encoding" "auto";
 $newline = Get-Attr $params "newline" "windows";
@@ -67,7 +67,12 @@ If (Test-Path $path -pathType container) {
 # performing validation if a validation command was specified.
 
 function WriteLines($outlines, $path, $linesep, $encodingobj, $validate) {
+	Try {
 		$temppath = [System.IO.Path]::GetTempFileName();
+	}
+	Catch {
+		Fail-Json ("Cannot create temporary file! (" + $_.Exception.Message + ")")
+	}
 	$joined = $outlines -join $linesep;
 	[System.IO.File]::WriteAllText($temppath, $joined, $encodingobj);
 
@@ -98,8 +103,20 @@ function WriteLines($outlines, $path, $linesep, $encodingobj, $validate) {
 
 	# Commit changes to the path
 	$cleanpath = $path.Replace("/", "\");
-	Copy-Item $temppath $cleanpath -force;	
-	Remove-Item $temppath -force;
+	Try {
+		Copy-Item $temppath $cleanpath -force -ErrorAction Stop;
+	}
+	Catch {
+		Fail-Json ("Cannot write to: $cleanpath (" + $_.Exception.Message + ")")
+	}
+
+	Try {
+		Remove-Item $temppath -force -ErrorAction Stop;
+	}
+	Catch {
+		Fail-Json ("Cannot remove temporary file: $temppath (" + $_.Exception.Message + ")")
+	}
+
 }
 
 
@@ -124,7 +141,7 @@ function Present($path, $regexp, $line, $insertafter, $insertbefore, $create, $b
 	# Check if path exists. If it does not exist, either create it if create == "yes"
 	# was specified or fail with a reasonable error message.
 	If (!(Test-Path $path)) {
-		If ($create -eq "no") {
+		If (-not $create) {
 			Fail-Json (New-Object psobject) "Path $path does not exist !";
 		}
 		# Create new empty file, using the specified encoding to write correct BOM
@@ -195,7 +212,7 @@ function Present($path, $regexp, $line, $insertafter, $insertbefore, $create, $b
 	$msg = "";
 
 	If ($index[0] -ne -1) {
-		If ($backrefs -ne "no") {
+		If ($backrefs) {
 		    $new_line = [regex]::Replace($matched_line, $regexp, $line);
 		}
 		Else {
@@ -207,7 +224,7 @@ function Present($path, $regexp, $line, $insertafter, $insertbefore, $create, $b
 			$changed = $TRUE;
 		}
 	}
-	ElseIf ($backrefs -ne "no") {
+	ElseIf ($backrefs) {
 		# No matches - no-op
 	}
 	ElseIf ($insertbefore -eq "BOF" -or $insertafter -eq "BOF") {
@@ -229,7 +246,7 @@ function Present($path, $regexp, $line, $insertafter, $insertbefore, $create, $b
 	# Write backup file if backup == "yes"
     $backuppath = "";
 
-	If ($changed -eq $TRUE -and $backup -eq "yes") {
+	If ($changed -eq $TRUE -and $backup -eq $TRUE) {
 		$backuppath = BackupFile $path;
 	}
 
@@ -307,7 +324,7 @@ function Absent($path, $regexp, $line, $backup, $validate, $encodingobj, $linese
 	# Write backup file if backup == "yes"
     $backuppath = "";
 
-	If ($changed -eq $TRUE -and $backup -eq "yes") {
+	If ($changed -eq $TRUE -and $backup -eq $TRUE) {
 		$backuppath = BackupFile $path;
 	}
 
@@ -416,7 +433,7 @@ Elseif (Test-Path $path) {
 
 If ($state -eq "present") {
 
-	If ( $backrefs -ne "no" -and $regexp -eq $FALSE ) {
+	If ( $backrefs -and $regexp -eq $FALSE ) {
 	    Fail-Json (New-Object psobject) "regexp= is required with backrefs=true";
 	}
 

lib/ansible/modules/windows/win_lineinfile.py

@@ -147,4 +147,11 @@ EXAMPLES = r'''
     path: C:\temp\testfile.txt
     line: Line added to file
     newline: unix
+
+# Update a line using backrefs
+- win_lineinfile:
+    path: C:\temp\example.conf
+    backrefs: yes
+    regexp: '(^name=)'
+    line: '$1JohnDoe'
 '''