Symlink

0.1.1

Symlink.psm1

# Create module-wide variables.
$script:ModuleRoot = $PSScriptRoot
$script:ModuleVersion = (Import-PowerShellDataFile -Path "$($script:ModuleRoot)\Symlink.psd1").ModuleVersion
$script:DataPath = "$env:APPDATA\Powershell\Symlink\database.xml"

# For the debug output to be displayed, $DebugPreference must be set
# to 'Continue' within the current session.
Write-Debug "`e[4mMODULE-WIDE VARIABLES`e[0m"
Write-Debug "Module root folder: $($script:ModuleRoot)"
Write-Debug "Module version: $($script:ModuleVersion)"
Write-Debug "Database file: $($script:DataPath)"

# Create the module data-storage folder if it doesn't exist.
if (-not (Test-Path -Path "$env:APPDATA\Powershell\Symlink" -ErrorAction Ignore)) {
    New-Item -ItemType Directory -Path "$env:APPDATA" -Name "Powershell\Symlink" -Force -ErrorAction Stop
    Write-Debug "Created database folder!"
}

# Potentially force this module script to dot-source the files, rather than
# load them in an alternative method.
$doDotSource = $global:ModuleDebugDotSource
$doDotSource = $true # Needed to make code coverage tests work

function Resolve-Path_i {
    <#
    .SYNOPSIS
        Resolves a path, gracefully handling a non-existent path.
         
    .DESCRIPTION
        Resolves a path into the full path. If the path is invalid,
        an empty string will be returned instead.
         
    .PARAMETER Path
        The path to resolve.
         
    .EXAMPLE
        PS C:\> Resolve-Path_i -Path "~\Desktop"
         
        Returns 'C:\Users\...\Desktop"
 
    #>
    [CmdletBinding()]
    Param (
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [string]
        $Path
    )
    
    # Run the command, silencing errors.
    $resolvedPath = Resolve-Path -Path $Path -ErrorAction Ignore
    
    # If NULL, then just return an empty string.
    if ($null -eq $resolvedPath) {
        $resolvedPath = ""
    }
    
    Write-Output $resolvedPath
}
function Import-ModuleFile {
    <#
    .SYNOPSIS
        Loads files into the module on module import.
        Only used in the project development environment.
        In built module, compiled code is within this module file.
         
    .DESCRIPTION
        This helper function is used during module initialization.
        It should always be dot-sourced itself, in order to properly function.
         
    .PARAMETER Path
        The path to the file to load.
         
    .EXAMPLE
        PS C:\> . Import-ModuleFile -File $function.FullName
         
        Imports the code stored in the file $function according to import policy.
         
    #>
    [CmdletBinding()]
    Param (
        [Parameter(Mandatory = $true, Position = 0)]
        [string]
        $Path
    )
    
    # Get the resolved path to avoid any cross-OS issues.
    $resolvedPath = $ExecutionContext.SessionState.Path.GetResolvedPSPathFromPSPath($Path).ProviderPath
    
    if ($doDotSource) {
        # Load the file through dot-sourcing.
        . $resolvedPath    
        Write-Debug "Dot-sourcing file: $resolvedPath"
    }
    else {
        # Load the file through different method (unknown atm?).
        $ExecutionContext.InvokeCommand.InvokeScript($false, ([scriptblock]::Create([io.file]::ReadAllText($resolvedPath))), $null, $null) 
        Write-Debug "Importing file: $resolvedPath"
    }
}

# ISSUE WITH BUILT MODULE FILE
# ----------------------------
# If this module file contains the compiled code below, as this is a "packaged"
# build, then that code *must* be loaded, and you cannot individually import
# and of the code files, even if they are there.
#
#
# If this module file is built, then it contains the class definitions below,
# and on Import-Module, this file is AST analysed and those class definitions
# are read-in and loaded.
#
# It's only once a command is run that this module file is executed, and if at
# that point this file starts to individually import the project files, it will
# end up re-defining the classes, and apparently that seems to cause issues
# later down the line.
#
#
# Therefore to prevent this issue, if this module file has been built and it
# contains the compile code below, that code will be used, and nothing else.
#
# The build script should also not package the individual files, so that the
# *only* possibility is to load the compiled code below and there is no way
# the individual files can be imported, as they don't exist.


# If this module file contains the compiled code, import that, but if it
# doesn't, then import the individual files instead.
$importIndividualFiles = $false
if ("<was built>" -eq '<was not built>') {
    $importIndividualFiles = $true
    Write-Debug "Module not compiled! Importing individual files."
}

Write-Debug "`e[4mIMPORT DECISION`e[0m"
Write-Debug "Dot-sourcing: $doDotSource"
Write-Debug "Importing individual files: $importIndividualFiles"

# If importing code as individual files, perform the importing.
# Otherwise, the compiled code below will be loaded.
if ($importIndividualFiles) {
    Write-Debug "!IMPORTING INDIVIDUAL FILES!"
    
    # Execute Pre-import actions.
    . Import-ModuleFile -Path "$ModuleRoot\internal\preimport.ps1"
    
    # Import all internal functions.
    foreach ($file in (Get-ChildItem "$ModuleRoot\internal\functions" -Filter "*.ps1" -Recurse -ErrorAction Ignore)) {
        . Import-ModuleFile -Path $file.FullName
    }
    
    # Import all public functions.
    foreach ($file in (Get-ChildItem "$ModuleRoot\functions" -Filter "*.ps1" -Recurse -ErrorAction Ignore)) {    
        . Import-ModuleFile -Path $file.FullName
    }
    
    # Execute Post-import actions.
    . Import-ModuleFile -Path "$ModuleRoot\internal\postimport.ps1"
    
    # End execution here, do not load compiled code below (if there is any).
    return
}

Write-Debug "!LOADING COMPILED CODE!"

#region Load compiled code
enum SymlinkState {
    True
    False
    NeedsCreation
    NeedsDeletion
    Error
}

class Symlink {
    [string]$Name
    hidden [string]$_Path
    hidden [string]$_Target
    hidden [scriptblock]$_Condition
        
    # Constructor with no creation condition.
    Symlink([string]$name, [string]$path, [string]$target) {
        $this.Name = $name
        $this._Path = $path
        $this._Target = $target
        $this._Condition = $null
    }
    
    # Constructor with a creation condition.
    Symlink([string]$name, [string]$path, [string]$target, [scriptblock]$condition) {
        $this.Name = $name
        $this._Path = $path
        $this._Target = $target
        $this._Condition = $condition
    }
    
    [string] ShortPath() {
        # Return the path after replacing common variable string.
        $path = $this._Path.Replace($env:APPDATA, "%APPDATA%")
        $path = $path.Replace($env:LOCALAPPDATA, "%LOCALAPPDATA%")
        $path = $path.Replace($env:USERPROFILE, "~")
        return $path
    }
    
    [string] FullPath() {
        # Return the path after expanding any environment variables encoded as %VAR%.
        return [System.Environment]::ExpandEnvironmentVariables($this._Path)
    }
    
    [string] ShortTarget() {
        # Return the path after replacing common variable string.
        $path = $this._Target.Replace($env:APPDATA, "%APPDATA%")
        $path = $path.Replace($env:LOCALAPPDATA, "%LOCALAPPDATA%")
        $path = $path.Replace($env:USERPROFILE, "~")
        return $path
    }
    
    [string] FullTarget() {
        # Return the target after expanding any environment variables encoded as %VAR%.
        return [System.Environment]::ExpandEnvironmentVariables($this._Target)
    }
    
    [bool] Exists() {
        # Check if the item even exists.
        if ($null -eq (Get-Item -Path $this.FullPath() -ErrorAction Ignore)) {
            return $false
        }
        # Checks if the symlink item and has the correct target.
        if ((Get-Item -Path $this.FullPath() -ErrorAction Ignore).Target -eq $this.FullTarget()) {
            return $true
        }else {
            return $false
        }
    }
    
    [bool] ShouldExist() {
        # If the condition is null, i.e. no condition,
        # assume true by default.
        if ($null -eq $this._Condition) { return $true }
        
        # An if check is here just in case the creation condition doesn't
        # return a boolean, which could cause issues down the line.
        # This is done because the scriptblock can't be validated whether
        # it always returns true/false, since it is not a "proper" method with
        # typed returns.
        if (Invoke-Command -ScriptBlock $this._Condition) {
            return $true
        }
        return $false
    }
    
    [SymlinkState] State() {
        # Return the appropiate state depending on whether the symlink
        # exists and whether it should exist.
        if ($this.Exists() -and $this.ShouldExist()) {
            return [SymlinkState]::True
        }elseif ($this.Exists() -and -not $this.ShouldExist()) {
            return [SymlinkState]::NeedsDeletion
        }elseif (-not $this.Exists() -and $this.ShouldExist()) {
            return [SymlinkState]::NeedsCreation
        }elseif (-not $this.Exists() -and -not $this.ShouldExist()) {
            return [SymlinkState]::False
        }
        return [SymlinkState]::Error
    }
    
    [void] CreateFile() {
        switch ($this.State()) {
            "True" {
                # There is an existing symlink and it points to the correct target.
                Write-Verbose "Existing symbolic-link item is correct. No change required."
                return
            }
            { $_ -in "NeedsDeletion","False" } {
                # If the symlink condition isn't met, skip creating it.
                Write-Verbose "Skipping the creation of a symbolic-link item, as the creation condition is false."
                return
            }
            "NeedsCreation" {
                # Determine whether there is an item at the location, and if so,
                # whether it's a normal item or a symlink, as they require
                # slightly different logic, and different verbose logging.
                $target = (Get-Item -Path $this.FullPath() -ErrorAction Ignore).Target
                
                if ($null -eq (Get-Item -Path $this.FullPath() -ErrorAction Ignore)) {
                    # There is no existing item or symlink, so just create the new symlink.
                }
                elseif ([System.String]::IsNullOrWhiteSpace($target)) {
                    # There is an existing item, so remove it.
                    Write-Verbose "Deleting existing folder/file first."
                    try {
                        Remove-Item -Path $this.FullPath() -Force -Recurse -WhatIf:$false -Confirm:$false
                    }
                    catch {
                        Write-Warning "The existing item could not be deleted. It may be in use by another program."
                        Write-Warning "Please close any programs which are accessing files via this folder/file."
                        Read-Host -Prompt "Press any key to continue..."
                        Remove-Item -Path $this.FullPath() -Force -Recurse -WhatIf:$false -Confirm:$false
                    }
                }
                elseif ($target -ne $this.FullTarget()) {
                    # There is an existing symlink, so remove it.
                    # Must be done by calling the 'Delete()' method, rather than 'Remove-Item'.
                    Write-Verbose "Changing the existing symbolic-link item target (deleting and re-creating)."
                    try {
                        (Get-Item -Path $this.FullPath()).Delete()
                    }
                    catch {
                        Write-Warning "The symlink could not be deleted. It may be in use by another program."
                        Write-Warning "Please close any programs which are accessing files via this symlink."
                        Read-Host -Prompt "Press any key to continue..."
                        (Get-Item -Path $this.FullPath()).Delete()
                    }
                }
                
                # Create the new symlink.
                New-Item -ItemType SymbolicLink -Force -Path $this.FullPath() -Value $this.FullTarget() `
                    -WhatIf:$false -Confirm:$false | Out-Null
            }
        }
    }
    
    [void] DeleteFile() {
        # Check that the actual symlink item exists first.
        if ($this.Exists()) {
            # Loop until the symlink item can be successfuly deleted.
            $state = $true
            while ($state -eq $true) {
                try {
                    (Get-Item -Path $this.FullPath()).Delete()
                }
                catch {
                    Write-Warning "The symlink: '$($this.Name)' could not be deleted. It may be in use by another program."
                    Write-Warning "Please close any programs which are accessing files via this symlink."
                    Read-Host -Prompt "Press any key to continue..."
                }
                $state = $this.Exists()
            }
        }
    }
}

<#
.SYNOPSIS
    Read the symlink objects in.
     
.DESCRIPTION
    Deserialise the symlink objects from the database file.
     
.EXAMPLE
    PS C:\> $list = $Read-Symlinks
     
    Reads all of the symlink objects into a variable, for maniuplation.
     
.INPUTS
    None
     
.OUTPUTS
    System.Collections.Generic.List[Symlink]
     
.NOTES
     
#>
function Read-Symlinks {
    # Create an empty symlink list.
    $linkList = New-Object -TypeName System.Collections.Generic.List[Symlink]
    
    # If the file doesn't exist, skip any importing.
    if (Test-Path -Path $script:DataPath -ErrorAction SilentlyContinue) {
        # Read the xml data in.
        $xmlData = Import-Clixml -Path $script:DataPath
        
        # Iterate through all the objects.
        foreach ($item in $xmlData) {
            # Rather than extracting the deserialised objects, which would create a mess
            # of serialised and non-serialised objects, create new identical copies from scratch.
            if ($item.pstypenames[0] -eq "Deserialized.Symlink") {
                
                # Create using the appropiate constructor.
                $link = if ($null -eq $item._Condition) {
                    [Symlink]::new($item.Name, $item._Path, $item._Target)
                }else {
                    [Symlink]::new($item.Name, $item._Path, $item._Target, [scriptblock]::Create($item._Condition))
                }
                
                $linkList.Add($link)
            }
        }
    }
    
    # Return the list as a <List> object, rather than as an array (ps converts by default).
    Write-Output $linkList -NoEnumerate
}


<#
.SYNOPSIS
    Builds all of the symbolic-links.
     
.DESCRIPTION
    Creates the symbolic-link items on the filesystem. Non-existent items will
    be created, whilst existing items will be updated (if necessary).
     
.PARAMETER Names
    The name(s)/identifier(s) of the symlinks to create. Multiple values
    are accepted to build multiple links at once.
  ! This parameter tab-completes valid symlink names.
     
.PARAMETER All
    Specifies to create all symlinks.
     
.PARAMETER WhatIf
    Prints what actions would have been done in a proper run, but doesn't
    perform any of them.
     
.PARAMETER Confirm
    Prompts for user input for every "altering"/changing action.
     
.INPUTS
    Symlink[]
    System.String[]
     
.OUTPUTS
    None
     
.NOTES
    -Names supports tab-completion.
     
.EXAMPLE
    PS C:\> Build-Symlink -All
     
    This command will go through all of the symlink definitions, and create
    the symbolic-link items on the filesystem, assuming the creation condition
    for them is met.
     
.EXAMPLE
    PS C:\> Build-Symlink -Names "data","files"
     
    This command will only go through the symlinks given in, and create the
    items on the filesystem.
  ! You can pipe the names to this command instead.
     
#>
function Build-Symlink {
    
    [CmdletBinding(DefaultParameterSetName = "All", SupportsShouldProcess = $true)]
    param (
        
        # Tab completion.
        [Parameter(Position = 0, Mandatory = $true, ValueFromPipelineByPropertyName, ParameterSetName = "Specific")]
        [Alias("Name")]
        [string[]]
        $Names,
        
        [Parameter(Position = 0, Mandatory = $true, ParameterSetName = "All")]
        [switch]
        $All
        
    )
    
    begin {
        # Store lists to notify user which symlinks were created/modified/etc.
        $newList = New-Object System.Collections.Generic.List[Symlink] 
        $modifiedList = New-Object System.Collections.Generic.List[Symlink]
    }
    
    process {
        if ($All) {
            # Read in all of the existing symlinks.
            $linkList = Read-Symlinks
            
            foreach ($link in $linkList) {
                Write-Verbose "Creating the symbolic-link item for: '$($link.Name)'."
                
                # Record the state for displaying at the end.
                if ($link.Exists() -eq $false) {
                    $newList.Add($link)
                }
                elseif ($link.State() -eq "NeedsDeletion" -or $link.State() -eq "NeedsCreation") {
                    $modifiedList.Add($link)
                }
                
                # Create the symlink item on the filesystem.
                if ($PSCmdlet.ShouldProcess($link.FullPath(), "Create Symbolic-Link")) {
                    $link.CreateFile()
                }
            }
        }
        else {
            # Read in the specified symlinks.
            $linkList = Get-Symlink -Names $Names -Verbose:$false
            
            foreach ($link in $linkList) {
                Write-Verbose "Creating the symbolic-link item for: '$($link.Name)'."
                
                # Record the state for displaying at the end.
                if ($link.Exists() -eq $false) {
                    $newList.Add($link)
                }
                elseif ($link.State() -eq "NeedsDeletion" -or $link.State() -eq "NeedsCreation") {
                    $modifiedList.Add($link)
                }
                
                # Create the symlink item on the filesystem.
                if ($PSCmdlet.ShouldProcess($link.FullPath(), "Create Symbolic-Link")) {
                    $link.CreateFile()
                }
            }
        }
    }
    
    end {
        # By default, outputs in List formatting.
        if ($newList.Count -gt 0) {
            Write-Host "Created the following new symlinks:"
            Write-Output $newList
        }
        if ($modifiedList.Count -gt 0) {
            Write-Host "Modified the following existing symlinks:"
            Write-Output $modifiedList
        }
    }
}

<#
.SYNOPSIS
    Gets the details of a symlink.
     
.DESCRIPTION
    Retrieves the details of symlink definition(s).
     
.PARAMETER Names
    The name(s)/identifier(s) of the symlinks to retrieve. Multiple values
    are accepted to retrieve the data of multiple links.
  ! This parameter tab-completes valid symlink names.
     
.PARAMETER All
    Specifies to retrieve details for all symlinks.
     
.INPUTS
    System.String[]
     
.OUTPUTS
    Symlink[]
     
.NOTES
    -Names supports tab-completion.
     
.EXAMPLE
    PS C:\> Get-Symlink -Name "data"
     
    This command will retrieve the details of the symlink named "data", and
    output the information to the screen.
     
.EXAMPLE
    PS C:\> Get-Symlink -Names "data","files"
     
    This command will retrieve the details of the symlinks named "data" and
    "files", and output both to the screen, one after another.
  ! You can pipe the names to this command instead.
     
.EXAMPLE
    PS C:\> Get-Symlink -All
         
    This command will retrieve the details of all symlinks, and output the
    information to the screen.
     
#>
function Get-Symlink {
    
    [CmdletBinding(DefaultParameterSetName = "Specific")]
    param (
        
        # Tab completion.
        [Parameter(Position = 0, Mandatory = $true, ValueFromPipeline, ParameterSetName = "Specific")]
        [Alias("Name")]
        [string[]]
        $Names,
        
        [Parameter(Position = 0, Mandatory = $true, ParameterSetName = "All")]
        [switch]
        $All
        
    )
    
    begin {
        # Store the retrieved symlinks, to output together in one go at the end.
        $outputList = New-Object System.Collections.Generic.List[Symlink]
    }
    
    process {
        if (-not $All) {
            # Read in the existing symlinks.
            $linkList = Read-Symlinks
            
            # Iterate through all the passed in names.
            foreach ($name in $Names) {
                Write-Verbose "Retrieving the symlink: '$name'."
                # If the link doesn't exist, warn the user.
                $existingLink = $linkList | Where-Object { $_.Name -eq $name }
                if ($null -eq $existingLink) {
                    Write-Warning "There is no symlink called: '$name'."
                    continue
                }
                
                # Add the symlink object.
                $outputList.Add($existingLink)
            }
        }
        else {
            Write-Verbose "Retrieving all symlinks."
            # Read in all of the symlinks.
            $outputList = Read-Symlinks
        }
    }
    
    end {
        # By default, outputs in List formatting.
        $outputList | Sort-Object -Property Name
    }
}

<#
.SYNOPSIS
    Creates a new symlink.
     
.DESCRIPTION
    Creates a new symlink definition in the database, and then creates the
    symbolic-link item on the filesystem.
     
.PARAMETER Name
    The name/identifier of this symlink (must be unique).
     
.PARAMETER Path
    The location of the symbolic-link item on the filesystem. If any parent
    folders defined in this path don't exist, they will be created.
     
.PARAMETER Target
    The location which the symbolic-link will point to. This defines whether
    the link points to a folder or file.
     
.PARAMETER CreationCondition
    A scriptblock which decides whether the symbolic-link is actually
    created or not. This does not affect the creation of the symlink
    definition within the database. For more details about this, see the
    help at: about_Symlink.
     
.PARAMETER DontCreateItem
    Skips the creation of the symbolic-link item on the filesystem.
     
.PARAMETER WhatIf
    Prints what actions would have been done in a proper run, but doesn't
    perform any of them.
     
.PARAMETER Confirm
    Prompts for user input for every "altering"/changing action.
     
.INPUTS
    None
     
.OUTPUTS
    Symlink
     
.NOTES
    For detailed help regarding the 'Creation Condition' scriptblock, see
    the help at: about_Symlink.
     
.EXAMPLE
    PS C:\> New-Symlink -Name "data" -Path ~\Documents\Data -Target D:\Files
     
    This command will create a new symlink definition, named "data", and a
    symbolic-link located in the user's document folder under a folder also
    named "data", pointing to a folder on the D:\ drive.
     
.EXAMPLE
    PS C:\> New-Symlink -Name "data" -Path ~\Documents\Data -Target D:\Files
                -CreationCondition $script -DontCreateItem
     
    This command will create a new symlink definition, named "data", but it
    will not create the symbolic-link on the filesystem. A creation condition
    is also defined, which will be evaluated when the 'Build-Symlink' command
    is run in the future.
     
#>
function New-Symlink {
    
    [CmdletBinding(SupportsShouldProcess = $true)]
    param (
        
        [Parameter(Position = 0, Mandatory = $true)]
        [string]
        $Name,
        
        [Parameter(Position = 1, Mandatory = $true)]
        [string]
        $Path,
        
        [Parameter(Position = 2, Mandatory = $true)]
        [string]
        $Target,
        
        [Parameter(Position = 3)]
        [scriptblock]
        $CreationCondition,
        
        [Parameter(Position = 4)]
        [switch]
        $DontCreateItem
        
    )
    
    Write-Verbose "Validating name."
    # Validate that the name isn't empty.
    if ([System.String]::IsNullOrWhiteSpace($Name)) {
        Write-Error "The name cannot be blank or empty!"
        return
    }
    
    # Validate that the target location exists.
    if (-not (Test-Path -Path ([System.Environment]::ExpandEnvironmentVariables($Target)) `
            -ErrorAction Ignore)) {
        Write-Error "The target path: '$Target' points to an invalid/non-existent location!"
        return
    }
    
    # Read in the existing symlink collection.
    $linkList = Read-Symlinks
    
    # Validate that the name isn't already taken.
    $existingLink = $linkList | Where-Object { $_.Name -eq $Name }
    if ($null -ne $existingLink) {
        Write-Error "The name: '$Name' is already taken!"
        return
    }
    
    Write-Verbose "Creating new symlink object."
    # Create the new symlink object.
    if ($null -eq $CreationCondition) {
        $newLink = [Symlink]::new($Name, $Path, $Target)
    }
    else {
        $newLink = [Symlink]::new($Name, $Path, $Target, $CreationCondition)
    }
    # Add the new link to the list, and then re-export the list.
    $linkList.Add($newLink)
    if ($PSCmdlet.ShouldProcess("$script:DataPath", "Overwrite database with modified one")) {
        Export-Clixml -Path $script:DataPath -InputObject $linkList -WhatIf:$false -Confirm:$false | Out-Null
    }
    
    # Build the symlink item on the filesytem.
    if (-not $DontCreateItem -and $PSCmdlet.ShouldProcess($newLink.FullPath(), "Create Symbolic-Link")) {
        $newLink.CreateFile()
    }
    
    Write-Output $newLink
}

<#
.SYNOPSIS
    Removes an symlink.
     
.DESCRIPTION
    Deletes symlink definition(s) from the database, and also deletes the
    symbolic-link item from the filesystem.
     
.PARAMETER Names
    The name(s)/identifier(s) of the symlinks to remove. Multiple values
    are accepted to retrieve the data of multiple links.
  ! This parameter tab-completes valid symlink names.
     
.PARAMETER DontDeleteItem
    Skips the deletion of the symbolic-link item on the filesystem. The
    link will remain afterwads.
     
.PARAMETER WhatIf
    Prints what actions would have been done in a proper run, but doesn't
    perform any of them.
     
.PARAMETER Confirm
    Prompts for user input for every "altering"/changing action.
     
.INPUTS
    Symlink[]
    System.String[]
     
.OUTPUTS
    None
     
.NOTES
    -Names supports tab-completion.
     
.EXAMPLE
    PS C:\> Remove-Symlink -Name "data"
     
    This command will remove a symlink definition, named "data", and delete the
    symbolic-link item from the filesystem.
     
.EXAMPLE
    PS C:\> Remove-Symlink -Names "data","files"
     
    This command will remove the symlink definitions named "data" and "files",
    and delete the symbolic-link items of both.
  ! You can pipe the names to this command instead.
     
.EXAMPLE
    PS C:\> Remove-Symlink -Name "data" -DontDeleteItem
     
    This command will remove a symlink definition, named "data", but it will
    keep the symbolic-link item on the filesystem.
     
#>
function Remove-Symlink {
    
    [CmdletBinding(SupportsShouldProcess = $true)]
    param (
        
        # Tab completion.
        [Parameter(Position = 0, Mandatory = $true, ValueFromPipelineByPropertyName)]
        [Alias("Name")]
        [string[]]
        $Names,
        
        [Parameter(Position = 1)]
        [switch]
        $DontDeleteItem
        
    )
    
    process {
        # Read in the existing symlinks.
        $linkList = Read-Symlinks
        
        foreach ($name in $Names) {
            Write-Verbose "Removing the symlink: '$name'."
            # If the link doesn't exist, warn the user.
            $existingLink = $linkList | Where-Object { $_.Name -eq $name }
            if ($null -eq $existingLink) {
                Write-Warning "There is no symlink called: '$name'."
                continue
            }
            
            # Delete the symlink from the filesystem.
            if (-not $DontDeleteItem -and $PSCmdlet.ShouldProcess($existingLink.FullPath(), "Delete Symbolic-Link")) {
                $existingLink.DeleteFile()
            }
            
            # Remove the link from the list.
            $linkList.Remove($existingLink) | Out-Null
        }
        
        # Re-export the list.
        if ($PSCmdlet.ShouldProcess("$script:DataPath", "Overwrite database with modified one")) {
            Export-Clixml -Path $script:DataPath -InputObject $linkList -WhatIf:$false -Confirm:$false | Out-Null
        }
    }
}

<#
.SYNOPSIS
    Sets a property of a symlink.
     
.DESCRIPTION
    Changes the property of a symlink to a new value.
     
.PARAMETER Name
    The name/identifier of the symlink to edit.
  ! This parameter tab-completes valid symlink names.
 
.PARAMETER Property
    The property to edit on this symlink. Valid values include:
    "Name", "Path", "Target", and "CreationCondition".
  ! This parameter tab-completes valid options.
     
.PARAMETER Value
    The new value for the property to take.
     
.PARAMETER WhatIf
    Prints what actions would have been done in a proper run, but doesn't
    perform any of them.
     
.PARAMETER Confirm
    Prompts for user input for every "altering"/changing action.
     
.INPUTS
    Symlink[]
    System.String[]
     
.OUTPUTS
    None
     
.NOTES
    -Names supports tab-completion.
     
    For detailed help regarding the 'Creation Condition' scriptblock, see
    the help at: about_Symlink.
     
.EXAMPLE
    PS C:\> Set-Symlink -Name "data" -Property "Name" -Value "WORK"
     
    This command will change the name of the symlink called "data", to the new
    name of "WORK". From now on, there is no symlink named "data" anymore.
     
.EXAMPLE
    PS C:\> Set-Symlink -Name "data" -Property "Path" -Value "~\Desktop\Files"
     
    This command will change the path of the symlink called "data", to the new
    location on the desktop. The old symbolic-link item from the original
    location will be deleted, and the a new symbolic-link item will be created
    at this new location.
     
#>
function Set-Symlink {
    
    [CmdletBinding(SupportsShouldProcess = $true)]
    param (
        
        # Tab completion.
        [Parameter(Position = 0, Mandatory = $true, ValueFromPipelineByPropertyName)]
        [string]
        $Name,
        
        [Parameter(Position = 1, Mandatory = $true)]
        [ValidateSet("Name", "Path", "Target", "CreationCondition")]
        [string]
        $Property,
        
        [Parameter(Position = 2, Mandatory = $true)]
        $Value
        
    )
    
    process {
        # Read in the existing symlinks.
        $linkList = Read-Symlinks
        
        Write-Verbose "Changing the symlink: '$Name'."
        # If the link doesn't exist, warn the user.
        $existingLink = $linkList | Where-Object { $_.Name -eq $Name }
        if ($null -eq $existingLink) {
            Write-Error "There is no symlink called: '$Name'."
            return
        }
        
        # Modify the property values.
        if ($Property -eq "Name") {
            Write-Verbose "Changing the name to: '$Value'."
            
            # Validate that the new name is valid.
            if ([System.String]::IsNullOrWhiteSpace($Name)) {
                Write-Error "The name cannot be blank or empty!"
                return
            }
            # Validate that the new name isn't already taken.
            $clashLink = $linkList | Where-Object { $_.Name -eq $Value }
            if ($null -ne $clashLink) {
                Write-Error "The name: '$Value' is already taken!"
                return
            }
            
            $existingLink.Name = $Value
        }
        elseif ($Property -eq "Path") {
            Write-Verbose "Changing the path to: '$Value'."
            # First delete the symlink at the original path.
            if ($PSCmdlet.ShouldProcess($existingLink.FullPath(), "Delete Symbolic-Link")) {
                $existingLink.DeleteFile()
            }
            
            # Then change the path property, and re-create the symlink
            # at the new location.
            $existingLink._Path = $Value
            if ($PSCmdlet.ShouldProcess($existingLink.FullPath(), "Create Symbolic-Link")) {
                $existingLink.CreateFile()
            }
        }
        elseif ($Property -eq "Target") {
            Write-Verbose "Changing the target to: '$Value'."
            
            # Validate that the target exists.
            if (-not (Test-Path -Path ([System.Environment]::ExpandEnvironmentVariables($Value)) `
                    -ErrorAction Ignore)) {
                Write-Error "The target path: '$Value' points to an invalid location!"
                return
            }
            
            # Change the target property, and edit the existing symlink (re-create).
            $existingLink._Target = $Value
            if ($PSCmdlet.ShouldProcess($existingLink.FullPath(), "Update Symbolic-Link target")) {
                $existingLink.CreateFile()
            }
        }
        elseif ($Property -eq "CreationCondition") {
            Write-Verbose "Changing the creation condition."
            
            $existingLink._Condition = $Value
            # TODO: Operate if condition result is different from previous state.
        }
        
        # Re-export the list.
        if ($PSCmdlet.ShouldProcess("$script:DataPath", "Overwrite database with modified one")) {
            Export-Clixml -Path $script:DataPath -InputObject $linkList -WhatIf:$false -Confirm:$false | Out-Null
        }
    }
}

# Tab expansion assignements for commands.

$argCompleter_SymlinkName = {
    param ($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)
    
    # Import all symlink objects from the database file.
    $linkList = Read-Symlinks
    
    if ($linkList.Count -eq 0) {
        Write-Output ""
    }
    
    # Return the names which match the currently typed in pattern
    $linkList.Name | Where-Object { $_ -like "$($wordToComplete.Replace(`"`'`", `"`"))*" } | ForEach-Object { "'$_'" }
    
}

Register-ArgumentCompleter -CommandName Get-Symlink -ParameterName Names -ScriptBlock $argCompleter_SymlinkName
Register-ArgumentCompleter -CommandName Set-Symlink -ParameterName Name -ScriptBlock $argCompleter_SymlinkName
Register-ArgumentCompleter -CommandName Remove-Symlink -ParameterName Names -ScriptBlock $argCompleter_SymlinkName
Register-ArgumentCompleter -CommandName Build-Symlink -ParameterName Names -ScriptBlock $argCompleter_SymlinkName
#endregion Load compiled code