<#
.SYNOPSIS
    Gets useful ACL properties and exports them to a CSV file.
.DESCRIPTION
    Gets Path, Owner, Access, Inheritance, and InheritanceFlags of an object(s) and export them to a CSV.
    The CSV format is desinged for user firendly read-ablitly.
    The first two columns of a row will be Path and Owner, then the next row(s) will be the Identity and Permissions of the left most object.
    Once the next object is enumerated, the Path and Owner will begin on the left most column.
    This gives a "Staggared" apperance, with the object(s) appering as "Sections"
    Example Output of 'Export-AclToCsv -Path "\\Server\Share" -ExportPath $env:HOMEPATH+"\test.csv" -FoldersOnly -Recurse':
    Path                     Owner                               FileSystemRights   IdentityReference   IsInherited   InheritanceFlags
    \\Server\Share\Folder1   mydomain.org\Owner_sAMAccountName
                                                                 FullControl        UserNameA           True          ContainerInherit, ObjectInherit
                                                                 FullControl        UserNameB           False         ContainerInherit, ObjectInherit
    \\Server\Share\Folder2   mydomain.org\Owner_SAMAccountName     
                                                                 Modify             UserNameC           True          ContainerInherit, ObjectInherit
    \\Server\Share\Folder3   mydomain.org\Owner_SAMAccountName
                                                                 FullControl        UserNameD           True          ContainerInherit, ObjectInherit

.EXAMPLE
    Export-AclToCsv -Path $env:HOMEPATH -ExportPath $env:HOMEPATH+"\HomePathPermissions.csv"
.EXAMPLE
    Export-AclToCsv -Path $env:HOMEPATH -ExportPath $env:HOMEPATH+"\HomePathPermissions.csv" -FilesOnly -Recurse
.NOTES
    Formating works best from within true spreadsheet application.
.LINKS
    https://github.com/necromorph1024
    https://gist.github.com/necromorph1024/9123328
#>
function Export-AclToCsv
{
    [CmdletBinding()]
    [OutputType([void])]
    Param
    (
        #Path, Type string, Object(s) to enumerate ACL entries against.
        [ValidateScript({ Test-Path $_ })]
        [Parameter(Mandatory=$true,
                   Position=0)]
        [string]
        $Path,

        #ExportPath, Type string, Fully Qualified Name of csv file to export to.
        [ValidateScript({ Test-Path (($_ -split '\\')[0..(($_ -split '\\').count -2)] -join '\') })]
        [Parameter(Mandatory=$true,
                   Position=1)]
        [string]
        $ExportPath,

        #FoldersOnly, Type switch, Only enumerate directorys in $Path.
        [Parameter(Position=2)]
        [switch]
        $FoldersOnly=$false,

        #FilesOnly, Type switch, Only enumerate files in $Path.
        [Parameter(Position=3)]
        [switch]
        $FilesOnly=$false,

        #Recurse, Type switch, Recursivly enumerate $Path.
        [Parameter(Position=4)]
        [switch]
        $Recurse=$false
    )

    if ($FoldersOnly -and $FilesOnly)
    {
        throw "Cannot use both -FoldersOnly and -FilesOnly cmdlet switches together."
    }

    $TableFormat=@{ Expression={ $_.Path.ToString().SubString($_.Path.ToString().IndexOf(":")+2) };Label="Path" },
                 @{ Expression={ $_.Owner };Label="Owner" },
                 @{ Expression={ $_.FileSystemRights };Label="FileSystemRights" },
                 @{ Expression={ $_.IdentityReference };Label="IdentityReference" },
                 @{ Expression={ $_.IsInherited };Label="IsInherited" },
                 @{ Expression={ $_.InheritanceFlags };Label="InheritanceFlags" }

    $gciParams=@{ Path=$Path;ErrorAction='SilentlyContinue'}
    if ($FoldersOnly)
    {
        $gciParams.Add('Directory',$true)
    }
    if ($FilesOnly)
    {
        $gciParams.Add('Files',$true)
    }
    if ($Recurse)
    {
        $gciParams.Add('Recurse',$true)
    }
    
    $items=Get-ChildItem @gciParams
    foreach ($item in $items)
    {
        try    
        {
            ($acl=Get-Acl -Path $item.FullName) | Select-Object $TableFormat | Export-Csv -Path $ExportPath -NoTypeInformation -Append
            foreach ($user in $acl.Access)
            {
                $user | Select-Object $TableFormat | Export-Csv -Path $ExportPath -NoTypeInformation -Append
            }
        }
        catch
        {
            $item | Select-Object @{ Name="Path";Expression={ $_.FullName }},
                                  @{ Name="Owner";Expression={ "UNABLE TO ENUMERATE" }},
                                  @{ Name="FileSystemRights";Expression={ "UNABLE TO ENUMERATE" }},
                                  @{ Name="IdentityReference";Expression={ "UNABLE TO ENUMERATE" }},
                                  @{ Name="IsInherited";Expression={ "UNABLE TO ENUMERATE" }},
                                  @{ Name="InheritanceFlags";Expression={ "UNABLE TO ENUMERATE" }} | Export-Csv -Path $ExportPath -NoTypeInformation -Append
        }
    }
}