#requires -version 2.0

# -----------------------------------------------------------------------------
# Script: Set-FileEncoding.ps1
# Version: 1.0
# Author: Jeffery Hicks
#    http://jdhitsolutions.com/blog
#    http://twitter.com/JeffHicks
# Date: 2/14/2011
# Keywords: File, Encoding
# Comments: DO NOT ATTEMPT TO USE THIS ON ANYTHING OTHER THAN TEXT FILES OR YOU 
# WILL END UP WITH CORRUPT FILES.
#
# "Those who neglect to script are doomed to repeat their work."
#
#  ****************************************************************
#  * DO NOT USE IN A PRODUCTION ENVIRONMENT UNTIL YOU HAVE TESTED *
#  * THOROUGHLY IN A LAB ENVIRONMENT. USE AT YOUR OWN RISK.  IF   *
#  * YOU DO NOT UNDERSTAND WHAT THIS SCRIPT DOES OR HOW IT WORKS, *
#  * DO NOT USE IT OUTSIDE OF A SECURE, TEST SETTING.             *
#  ****************************************************************
# -----------------------------------------------------------------------------

Function Set-FileEncoding {

<#
   .Synopsis
    Set file encoding on a text file.
    .Description
    This function will take an existing text file and re-save it using the specified file encoding. The default 
    coding is ASCII, but you can specify any encoding supported by the Out-File cmdlet such as Unicode or UTF8. 
    A new file will be created with the same contents. However you can use the -SaveTime parameter which will 
    take timestamps from the original file and apply them to the new file, thus retaining original file information.
    
    By default nothing is written to the pipeline unless you use -Passthru, which will then write the new file object.
    
    WARNING: DO NOT ATTEMPT TO USE THIS ON ANYTHING OTHER THAN TEXT FILES OR YOU WILL END UP WITH CORRUPT FILES.
    
    .Parameter Path
    The file name and path to encode.
    .Parameter Encoding
    The encoding format. The default is ASCII, but you can specify any of the Out-File
    encoding formats: "Unicode", "UTF7", "UTF8", "UTF32", "ASCII","BigEndianUnicode", 
    "Default" or "OEM".
    .Parameter SaveTime
    Retain original time stamp values. Otherwise you will get a new file.
    .Parameter Passthru
    Write the new file object to the pipeline.
   .Example
    PS C:\> Set-FileEncoding c:\files\data.txt -encoding unicode
    Set encoding on C:\files\data.txt to Unicode.
   .Example
    PS C:\> dir c:\work\*.txt | Set-FileEncoding -encoding ascii -saveTime -passthru
    Set encoding on all text files in C:\work to encoding, retaining the original time stamp values.
    Each file object will be written to the pipeline.
   .Example
    PS C:\> dir c:\scripts\*.ps1 | Set-FileEncoding -encoding Unicode
    Set encoding on all PowerShell scripts to Unicode. New files will be created and nothing will be written
    to the pipeline.
   .Notes
    NAME: Set-FileEncoding
    AUTHOR: Jeffery Hicks
    VERSION: 1.0
    LASTEDIT: 02/15/2011 
    
    Learn more with a copy of Windows PowerShell 2.0: TFM (SAPIEN Press 2010)
    
   .Link
    http://jdhitsolutions.com/blog/2011/02/set-file-encoding
    
    .Link
    Out-File
    
    .Inputs
    Strings
    
    .Outputs
    File Object when using -Passthru
#>

[cmdletBinding(SupportsShouldProcess=$True)]

Param (
    [Parameter(Position=0,Mandatory=$True,HelpMessage="Enter a file name and path.",
    ValueFromPipeline=$True,ValueFromPipelineByPropertyName=$True)]
    [ValidateNotNullorEmpty()]
    [Alias("PSPath","Name")]
    [string[]]$Path,

    [ValidateSet("Unicode", "UTF7", "UTF8", "UTF32", "ASCII","BigEndianUnicode", "Default","OEM")]
    [string]$Encoding="ASCII",

    [switch]$SaveTime,

    [switch]$Passthru
)

Begin
{
    Write-Verbose "$(Get-Date) Starting $($myinvocation.command)"
}

Process 
{
    foreach ($file in $path)
    {
        Write-Verbose "$(Get-Date) Setting encoding on $File to $Encoding"
        Write-Verbose "$(Get-Date) Getting content"
        $content=Get-Content -Path $file
        $filedata=Get-Item -Path $file
        Write-Verbose "$(Get-Date) Saving content"
        Out-File -FilePath $file -Encoding $Encoding -InputObject $content
        
        if ($SaveTime)
        {
             #get the "new" file
             $f=Get-Item -Path $file
             Write-Verbose "$(Get-Date) Retaining original time stamp values"
              if ($pscmdlet.ShouldProcess("Resetting Timestamp on $file")) 
              {
                 #revert timestamp values
                 $f.CreationTime=$filedata.CreationTime
                 $f.CreationTimeUtc=$filedata.CreationTimeUtc
                 $f.LastAccessTime= $filedata.LastAccessTime
                 $f.LastAccessTimeUtc=$filedata.LastAccessTimeUtc
                 $f.LastWriteTime=$filedata.LastWriteTime
                 $f.LastWriteTimeUtc=$filedata.LastWriteTimeUtc
             }
        }
        if ($PassThru)
        {
            Get-Item -Path $file
        }
        
     } #foreach
} #process

End
{
    Write-Verbose "$(Get-Date) Ending $($myinvocation.command)"
}

} #end function