GPALFile.cs

// =============================================================================
// GPAL - Generally Positive Automation Library
// Copyright © 2026 Software Decisions, Inc. All rights reserved.
//
// This file is part of GPAL.
// Licensed under the Business Source License 1.1
//
// Primary development, architecture, and vision by Michael B. Vederman,
// CEO of Software Decisions, Inc., Texas.
//
// Internal development maintained privately.
// Public releases appear on GitHub: https://github.com/SoftwareDecisionsInc/GPAL.
//
// See LICENSE for full terms, including Additional Use Grant.
// =============================================================================
 
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net.Http;
using System.Numerics;
using System.Text;
using System.Threading.Tasks;
using System.Windows;
using static GenerallyPositive.Enums;
 
 
namespace GenerallyPositive
{
    public class GPALFile : IGPALFile, IGPALFileInternal
    {

        GPALFileSettings IGPALFileInternal.FileSettings { get; set; }

        public GPALFile ToGPALObject()
        {
            return this;
        }

        internal GPALFile()
        {
            ((IGPALFileInternal)this).FileSettings = new GPALFileSettings();
            ((IGPALFileInternal)this).FileDictionary = new List<Dictionary<object, dynamic>>();
        }

        internal GPALFile(string fileName)
        {
            ((IGPALFileInternal)this).FileSettings = new GPALFileSettings();
            ((IGPALFileInternal)this).FileSettings.Filenames.Add(fileName);
            ((IGPALFileInternal)this).FileDictionary = new List<Dictionary<object, dynamic>>();
        }
        #region <Fluent Interface>
        public IAllowFileSettings WithOverwriteFile(bool overwriteFile = false)
        {
            ((IGPALFileInternal)this).FileSettings.OverwriteFile.Add(overwriteFile);
            return this;
        }

        public IAllowFileSettings WithFileSortOrder(Enums.FileSortOrder fileSortOrder)
        {
            ((IGPALFileInternal)this).FileSettings.FileSortOrder = fileSortOrder;
            return this;
        }

        public IAllowFileSettings WithNextFilePattern(Enums.NextFilePattern nextFilePattern = Enums.NextFilePattern.CounterPadded)
        {
            ((IGPALFileInternal)this).FileSettings.NextFilePattern = nextFilePattern;
            return this;
        }

        public IAllowFileSettings WithDelimiter(char delimiter)
        {
            ((IGPALFileInternal)this).FileSettings.Delimiter.Add(delimiter);
            return this;
        }

        public IAllowFileSettings WithColumnsEnclosedInQuotes(bool fieldsInQuotes)
        {
            ((IGPALFileInternal)this).FileSettings.FieldsEnclosedInQuotes.Add(fieldsInQuotes);
            return this;
        }

        public IAllowFileSettings WithFirstLineIsColumnNames(bool firstLineIsColumnNames)
        {
            ((IGPALFileInternal)this).FileSettings.FirstLineIsColumnNames.Add(firstLineIsColumnNames);
            return this;
        }

        public IAllowFileSettings WithIgnoreFirstLineColumnNames(bool ignoreFirstLine = true)
        {
            ((IGPALFileInternal)this).FileSettings.IgnoreFirstLineColumnNames.Add(ignoreFirstLine);
            return this;
        }

        public IAllowFileSettings WithUseSameColumnNamesForAllFiles(bool useHeaderForAllFiles)
        {
            ((IGPALFileInternal)this).FileSettings.UseOneHeaderForAllFiles = useHeaderForAllFiles;
            return this;
        }

        public IAllowFileSettings WithBrowser(Browser.IBrowser browser)
        {
            ((IGPALFileInternal)this).FileSettings.Browser = browser;
            return this;
        }

        public IAllowFileSettings WithFileName(string fileName)
        {
            fileName = Environment.ExpandEnvironmentVariables(fileName);
 
            // before the wildcard test, since a url's query string carries a "?" that would otherwise be read as one
            if (true == FileHelper.IsWebAddress(fileName))
            {
                Browser.IBrowser browser = ((IGPALFileInternal)this).FileSettings.Browser;
                string name = Path.GetFileName(new Uri(fileName).LocalPath);
                string localPath = Path.Combine(GPAL.TempDirectory(), true == string.IsNullOrWhiteSpace(name) ? "download" : name);
 
                ((IGPALFileInternal)this).FileSettings.SourceUrl = fileName;
 
                // supplying a browser is how a workflow says this file is behind something our own connection
                // cannot get past, so the browser gets it: fetched from inside the page, and downloaded in a tab
                // only if the page cannot hand it over.
                // Without a browser there is only our own connection, which works for anything public
                if (null != browser)
                    FileHelper.FetchOrDownloadInTab(fileName, localPath, browser);
                else
                    FileHelper.DownloadToFile(localPath, fileName);
 
                fileName = localPath;
            }
 
            if (true == fileName.Contains('*') || true == fileName.Contains('?'))
            {
                string directory = Path.GetDirectoryName(fileName);
                string filenamePart = Path.GetFileName(fileName);
                string[] matches = Directory.GetFiles(false == string.IsNullOrEmpty(directory) ? directory : @".\", filenamePart);
 
                if (0 == matches.Length)
                {
                    GPAL.PublishSimpleEvent(Enums.GPALEventType.WARNING, $"No files matched the wildcard pattern [{fileName}].", this, Enums.GPALObjectType.GPALFile);
                }
                else
                {
                    IEnumerable<string> sortedMatches;
 
                    switch (((IGPALFileInternal)this).FileSettings.FileSortOrder)
                    {
                        case Enums.FileSortOrder.NameDescending:
                            sortedMatches = matches.OrderByDescending(m => m, StringComparer.OrdinalIgnoreCase);
                            break;
                        case Enums.FileSortOrder.NaturalAscending:
                            sortedMatches = matches.OrderBy(m => m, NaturalFilenameComparer.Instance);
                            break;
                        case Enums.FileSortOrder.NaturalDescending:
                            sortedMatches = matches.OrderByDescending(m => m, NaturalFilenameComparer.Instance);
                            break;
                        case Enums.FileSortOrder.DateModifiedAscending:
                            sortedMatches = matches.OrderBy(m => File.GetLastWriteTimeUtc(m));
                            break;
                        case Enums.FileSortOrder.DateModifiedDescending:
                            sortedMatches = matches.OrderByDescending(m => File.GetLastWriteTimeUtc(m));
                            break;
                        case Enums.FileSortOrder.DateCreatedAscending:
                            sortedMatches = matches.OrderBy(m => File.GetCreationTimeUtc(m));
                            break;
                        case Enums.FileSortOrder.DateCreatedDescending:
                            sortedMatches = matches.OrderByDescending(m => File.GetCreationTimeUtc(m));
                            break;
                        case Enums.FileSortOrder.NameAscending:
                        default:
                            sortedMatches = matches.OrderBy(m => m, StringComparer.OrdinalIgnoreCase);
                            break;
                    }
 
                    foreach (string match in sortedMatches)
                    {
                        ((IGPALFileInternal)this).FileSettings.Filenames.Add(match);
                        ((IGPALFileInternal)this).FileSettings.FileCount++;
                    }
                }
            }
            else
            {
                ((IGPALFileInternal)this).FileSettings.Filenames.Add(fileName);
                ((IGPALFileInternal)this).FileSettings.FileCount++;
            }
 
            return this;
        }

        public IAllowFileSettings WithColumnName(string columnName)
        {
            if (((IGPALFileInternal)this).FileSettings.FileCount > ((IGPALFileInternal)this).FileSettings.ColumnList.Count())
                ((IGPALFileInternal)this).FileSettings.ColumnList.AddRow(new List<string>());
 
            ((IGPALFileInternal)this).FileSettings.ColumnList[((IGPALFileInternal)this).FileSettings.ColumnList.Count() - 1].Add(columnName);
 
            if (((IGPALFileInternal)this).FileSettings.FileCount > ((IGPALFileInternal)this).FileSettings.FirstLineIsColumnNames.Count)
                ((IGPALFileInternal)this).FileSettings.FirstLineIsColumnNames.Add(true);
            return this;
        }

        public IAllowFileSettings WithColumnNames(string columnNames)
        {
            if (((IGPALFileInternal)this).FileSettings.FileCount > ((IGPALFileInternal)this).FileSettings.ColumnList.Count())
                ((IGPALFileInternal)this).FileSettings.ColumnList.AddRow(new List<string>());
            else
            // we already have columns from .WithColumnName, add a new list for our entries
            {
                string oldColumns = string.Join(", ", ((IGPALFileInternal)this).FileSettings.ColumnList[((IGPALFileInternal)this).FileSettings.ColumnList.Count() - 1]);
                GPAL.PublishSimpleEvent(Enums.GPALEventType.WARNING, $"Overwriting existing column names [{oldColumns}] with new names [{columnNames}]");
                ((IGPALFileInternal)this).FileSettings.ColumnList.Clear();
            }
 
            foreach (string columnName in columnNames.Split(','))
                ((IGPALFileInternal)this).FileSettings.ColumnList[((IGPALFileInternal)this).FileSettings.ColumnList.Count() - 1].Add(columnName.Trim());
 
            // alway ensure we have a new empty list waiting to add columns too.
 
            if (((IGPALFileInternal)this).FileSettings.FileCount > ((IGPALFileInternal)this).FileSettings.FirstLineIsColumnNames.Count)
                ((IGPALFileInternal)this).FileSettings.FirstLineIsColumnNames.Add(true);
 
            return this;
        }

        public IAllowFileSettings WithColumnNames(string[] columnNames)
        {
            // we already have columns from .WithCOlumnName, add a new list for our entries
            if (((IGPALFileInternal)this).FileSettings.FileCount > ((IGPALFileInternal)this).FileSettings.ColumnList.Count())
                ((IGPALFileInternal)this).FileSettings.ColumnList.AddRow(new List<string>());
 
            foreach (string columnName in columnNames)
                ((IGPALFileInternal)this).FileSettings.ColumnList[((IGPALFileInternal)this).FileSettings.ColumnList.Count() - 1].Add(columnName);
 
            if (((IGPALFileInternal)this).FileSettings.FileCount > ((IGPALFileInternal)this).FileSettings.FirstLineIsColumnNames.Count)
                ((IGPALFileInternal)this).FileSettings.FirstLineIsColumnNames.Add(true);
 
            return this;
        }
        #endregion <Fluent Interface>
 
        #region <Getters/Setters>
        public string First
        {
            get
            {
                if (0 < ((IGPALFileInternal)this).FileSettings.FileCount)
                {
                    ((IGPALFileInternal)this).FileSettings.NextFileCount = 0;
                    return ((IGPALFileInternal)this).FileSettings.Filenames[0];
                }
                else
                    return null;
            }
        }

        public string Last
        {
            get
            {
                if (0 < ((IGPALFileInternal)this).FileSettings.FileCount)
                {
                    ((IGPALFileInternal)this).FileSettings.NextFileCount = ((IGPALFileInternal)this).FileSettings.Filenames.Count - 1;
                    return ((IGPALFileInternal)this).FileSettings.Filenames[((IGPALFileInternal)this).FileSettings.Filenames.Count - 1];
                }
                else
                    return null;
            }
        }

        public GPALFile Next
        {
            get
            {
                string fullPath = null;
                string newFilename = null;
                Enums.NextFilePattern nextPattern = ((IGPALFileInternal)this).FileSettings.NextFilePattern;
                int patternCounter = ((IGPALFileInternal)this).FileSettings.NextPatternCounter;
 
                if (0 == ((IGPALFileInternal)this).FileSettings.OverwriteFile.Count)    // default to not overwrite since user did not specify but called next
                {
                    if (((IGPALFileInternal)this).FileSettings.NextFileCount < ((IGPALFileInternal)this).FileSettings.FileCount) // otherwise get the next filename in the list
                    {
                        fullPath = FileHelper.CleanUpFileDestination(((IGPALFileInternal)this).FileSettings.Filenames[((IGPALFileInternal)this).FileSettings.NextFileCount], out newFilename, DeleteFileBeforeDownload: false, nextPattern, ref patternCounter);
                        ((IGPALFileInternal)this).FileSettings.NextPatternCounter = patternCounter;
                        // record it whether or not the name needed uniquifying. ReturnFilenames is the list of files
                        // we wrote, and a name that came back unchanged still gets written
                        ((IGPALFileInternal)this).FileSettings.ReturnFilenames.Add(fullPath);
                        ((IGPALFileInternal)this).FileSettings.NextFileCount++;
                        return fullPath;
                    }
                    else    // we are out of user defined files but they keep calling Next past user supplied filenames, so generate a new filename using the last user supplied entry as a pattern, can call next to keep getting a new filename
                    {
                        fullPath = FileHelper.CleanUpFileDestination(((IGPALFileInternal)this).FileSettings.Filenames[((IGPALFileInternal)this).FileSettings.NextFileCount-1], out newFilename, DeleteFileBeforeDownload: false, nextPattern, ref patternCounter);
                        ((IGPALFileInternal)this).FileSettings.NextPatternCounter = patternCounter;
                        ((IGPALFileInternal)this).FileSettings.ReturnFilenames.Add(fullPath);
                        //((IGPALFileInternal)this).FileSettings.NextFileCount++;
                        return fullPath;
                    }
                }
                // do the same but respect the overwrite flag settings
                else if (((IGPALFileInternal)this).FileSettings.NextFileCount < ((IGPALFileInternal)this).FileSettings.OverwriteFile.Count)
                {
                    if (true == ((IGPALFileInternal)this).FileSettings.OverwriteFile[((IGPALFileInternal)this).FileSettings.NextFileCount])   // file flagged to overwrite - always return the same filename
                    {
                        fullPath = FileHelper.CleanUpFileDestination(((IGPALFileInternal)this).FileSettings.Filenames[((IGPALFileInternal)this).FileSettings.NextFileCount++], out newFilename, DeleteFileBeforeDownload: true);
                        ((IGPALFileInternal)this).FileSettings.ReturnFilenames.Add(fullPath);
                        return fullPath;
                    }
                    // a remaining user-supplied filename takes priority over generating a new one
                    else if (((IGPALFileInternal)this).FileSettings.NextFileCount < ((IGPALFileInternal)this).FileSettings.FileCount)
                    {
                        fullPath = FileHelper.CleanUpFileDestination(((IGPALFileInternal)this).FileSettings.Filenames[((IGPALFileInternal)this).FileSettings.NextFileCount], out newFilename, DeleteFileBeforeDownload: false, nextPattern, ref patternCounter);
                        ((IGPALFileInternal)this).FileSettings.NextPatternCounter = patternCounter;
                        // record it whether or not the name needed uniquifying. ReturnFilenames is the list of files
                        // we wrote, and a name that came back unchanged still gets written
                        ((IGPALFileInternal)this).FileSettings.ReturnFilenames.Add(fullPath);
                        ((IGPALFileInternal)this).FileSettings.NextFileCount++;
                        return fullPath;
                    }
                }
 
                // default to generating a new filename if we fall thru. the pattern is the last filename the
                // workflow supplied once the cursor is past them, since Filenames only ever holds those now and
                // deriving from a generated name is what produced base_0001_0003 style names
                int patternIdx = Math.Min(((IGPALFileInternal)this).FileSettings.NextFileCount, ((IGPALFileInternal)this).FileSettings.FileCount - 1);
 
                fullPath = FileHelper.CleanUpFileDestination(((IGPALFileInternal)this).FileSettings.Filenames[patternIdx], out newFilename, DeleteFileBeforeDownload: false, nextPattern, ref patternCounter);
                ((IGPALFileInternal)this).FileSettings.NextPatternCounter = patternCounter;
                ((IGPALFileInternal)this).FileSettings.ReturnFilenames.Add(fullPath);
                //((IGPALFileInternal)this).FileSettings.NextFileCount++;
                return fullPath;
            }
        }

        public string Filename
        {
            get
            {
                // a wildcard that matched nothing leaves no filenames at all, and indexing the first one
                // there threw out of the implicit string conversion where no caller can see it coming.
                // WithFileName already published the warning naming the pattern
                List<string> filenames = ((IGPALFileInternal)this).FileSettings.Filenames;
 
                return 0 == filenames.Count ? string.Empty : filenames[0];
            }
        }

        public List<string> DirectoryParts
        {
            get
            {
                return ((IGPALFileInternal)this).FileSettings.Filenames.Select(filename => Path.GetDirectoryName(filename)).ToList();
            }
        }

        public List<string> FileParts
        {
            get
            {
                return ((IGPALFileInternal)this).FileSettings.Filenames.Select(filename => Path.GetFileName(filename)).ToList();
            }
        }

        public string DirectoryPart
        {
            get
            {
                // Path.GetDirectoryName throws on an empty path, which is what a no-match wildcard leaves
                string filename = Filename;
 
                return 0 == filename.Length ? string.Empty : Path.GetDirectoryName(filename);
            }
        }

        public string FilePart
        {
            get
            {
                string filename = Filename;
 
                return 0 == filename.Length ? string.Empty : Path.GetFileName(filename);
            }
        }

        public List<string> Filenames
        {
            get
            {
                return ((IGPALFileInternal)this).FileSettings.Filenames;
            }
        }

        public List<string> ReturnFilenames
        {
            get
            {
                return ((IGPALFileInternal)this).FileSettings.ReturnFilenames;
            }
        }

        public string SourceUrl
        {
            get
            {
                return ((IGPALFileInternal)this).FileSettings.SourceUrl;
            }
        }

        List<IGPALGrid<string>> IGPALFileInternal.TokenList
        {
            get
            {
                return ((IGPALFileInternal)this).FileSettings.TokenList;
            }
            set
            {
                ((IGPALFileInternal)this).FileSettings.TokenList = value;
            }
        }
        List<string> IGPALFileInternal.FileData
        {
            get
            {
                return ((IGPALFileInternal)this).FileSettings.FileData;
            }
            set
            {
                ((IGPALFileInternal)this).FileSettings.FileData = value;
            }
        }
        List<char?> IGPALFileInternal.Delimiter
        {
            get
            {
                return ((IGPALFileInternal)this).FileSettings.Delimiter;
            }
            set
            {
                ((IGPALFileInternal)this).FileSettings.Delimiter = value;
            }
        }
        List<bool> IGPALFileInternal.FieldsEnclosedInQuotes
        {
            get
            {
                return ((IGPALFileInternal)this).FileSettings.FieldsEnclosedInQuotes;
            }
            set
            {
                ((IGPALFileInternal)this).FileSettings.FieldsEnclosedInQuotes = value;
            }
        }
        List<bool> IGPALFileInternal.FirstLineIsColumnNames
        {
            get
            {
                return ((IGPALFileInternal)this).FileSettings.FirstLineIsColumnNames;
            }
            set
            {
                ((IGPALFileInternal)this).FileSettings.FirstLineIsColumnNames = value;
            }
        }
        List<bool> IGPALFileInternal.IgnoreFirstLineColumnNames
        {
            get
            {
                return ((IGPALFileInternal)this).FileSettings.IgnoreFirstLineColumnNames;
            }
            set
            {
                ((IGPALFileInternal)this).FileSettings.IgnoreFirstLineColumnNames = value;
            }
        }
        bool IGPALFileInternal.UseOneHeaderForAllFiles
        {
            get
            {
                return ((IGPALFileInternal)this).FileSettings.UseOneHeaderForAllFiles;
            }
            set
            {
                ((IGPALFileInternal)this).FileSettings.UseOneHeaderForAllFiles = value;
            }
        }
        List<Dictionary<object, dynamic>> IGPALFileInternal.FileDictionary
        {
            get
            {
                return ((IGPALFileInternal)this).FileSettings.FileDictionary;
            }
            set
            {
                ((IGPALFileInternal)this).FileSettings.FileDictionary = value;
            }
        }
        List<IGPALGrid<string>> IGPALFileInternal.FileGrid
        {
            get
            {
                return ((IGPALFileInternal)this).FileSettings.FileGrid;
            }
            set
            {
                ((IGPALFileInternal)this).FileSettings.FileGrid = value;
            }
        }
        bool IGPALFileInternal.AlreadyTokenized
        {
            get
            {
                return ((IGPALFileInternal)this).FileSettings.AlreadyTokenized;
            }
 
            set
            {
                ((IGPALFileInternal)this).FileSettings.AlreadyTokenized = value;
            }
        }
        public int Count
        {
            get => Filenames.Count;
        }
        #endregion <Getters/Setters>
        #region Helpers
        public void CopyTo(string destination)
        {
            string myDestination = destination;
            bool isDir = IsDirectoryOnly(destination);
 
            foreach (string filename in ((IGPALFileInternal)this).FileSettings.Filenames)
            {
                try
                {
                    string directory = Path.GetDirectoryName(filename);
                    string filenamepart = Path.GetFileName(filename);
 
                    foreach (string filename2 in Directory.GetFiles(false == string.IsNullOrEmpty(directory) ? directory : @".\", filenamepart))
                    {
                        if (true == isDir)
                            myDestination = Path.Combine(destination, Path.GetFileName(filename2));
                        File.Copy(filename2, myDestination);
                        GPAL.PublishSimpleEvent(Enums.GPALEventType.INFO, $"[{filename2}] copied to [{destination}].", this, Enums.GPALObjectType.GPALFile);
                    }
                }
                catch (Exception ex)
                {
                    GPAL.PublishSimpleEvent(Enums.GPALEventType.EXCEPTION, $"Unable to copy [{filename}] to [{destination}].", this, Enums.GPALObjectType.GPALFile, ex);
                }
            }
        }

        public void MoveTo(string destination)
        {
            string myDestination = destination;
            bool isDir = IsDirectoryOnly(destination);
 
            foreach (string filename in ((IGPALFileInternal)this).FileSettings.Filenames)
            {
                try
                {
                    string directory = Path.GetDirectoryName(filename);
                    string filenamepart = Path.GetFileName(filename);
 
                    foreach (string filename2 in Directory.GetFiles(false == string.IsNullOrEmpty(directory) ? directory : @".\", filenamepart))
                    {
                        if (true == isDir)
                            myDestination = Path.Combine(destination, Path.GetFileName(filename2));
                        File.Move(filename2, myDestination);
                        GPAL.PublishSimpleEvent(Enums.GPALEventType.INFO, $"[{filename2}] moved to [{destination}].", this, Enums.GPALObjectType.GPALFile);
                    }
                }
                catch (Exception ex)
                {
                    GPAL.PublishSimpleEvent(Enums.GPALEventType.EXCEPTION, $"Unable to move [{filename}] to [{destination}].", this, Enums.GPALObjectType.GPALFile, ex);
                }
            }
        }

        public void Delete(string destination)
        {
            string myDestination = destination;
            bool isDir = IsDirectoryOnly(destination);
 
            try
            {
                if (true == isDir)
                    foreach (string filename in Directory.GetFiles(destination))
                    {
                        myDestination = Path.Combine(destination, filename);
                        File.Delete(Path.Combine(myDestination, filename));
                        GPAL.PublishSimpleEvent(Enums.GPALEventType.INFO, $"[{myDestination}] deleted.", this, Enums.GPALObjectType.GPALFile);
                    }
                else
                {
                    File.Delete(myDestination);
                    GPAL.PublishSimpleEvent(Enums.GPALEventType.INFO, $"[{myDestination}] deleted.", this, Enums.GPALObjectType.GPALFile);
                }
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(Enums.GPALEventType.EXCEPTION, $"Unable to delete[{myDestination}].", this, Enums.GPALObjectType.GPALFile, ex);
            }
        }

        public void Delete()
        {
            foreach (string filename in ((IGPALFileInternal)this).FileSettings.Filenames)
            {
                try
                {
                    File.Delete(filename);
                    GPAL.PublishSimpleEvent(Enums.GPALEventType.INFO, $"[{filename}] deleted.", this, Enums.GPALObjectType.GPALFile);
                }
                catch (Exception ex)
                {
                    GPAL.PublishSimpleEvent(Enums.GPALEventType.EXCEPTION, $"Unable to delete [{filename}].", this, Enums.GPALObjectType.GPALFile, ex);
                }
            }
        }

        internal static bool IsDirectoryOnly(string path)
        {
            // the question is about path itself, never about its parent. it named a directory when it says so with
            // a trailing separator, when it already exists as one, or when it carries no extension to suggest a
            // filename.
            // CAVEAT: a directory name containing a dot reads as a file by that last rule. Create such a directory
            // beforehand and the "already exists" test settles it first.
            bool isDirectory = true == path.EndsWith(Path.DirectorySeparatorChar.ToString())
                || true == path.EndsWith(Path.AltDirectorySeparatorChar.ToString())
                || true == Directory.Exists(path)
                || false == Path.HasExtension(path);
 
            // either way the folder has to be there before anything is written: the path itself when it is a
            // directory, its parent when it is a file
            string directoryToCreate = true == isDirectory ? path : Path.GetDirectoryName(path);
 
            if (false == string.IsNullOrEmpty(directoryToCreate) && false == Directory.Exists(directoryToCreate))
            {
                Directory.CreateDirectory(directoryToCreate);
                GPAL.PublishSimpleEvent(Enums.GPALEventType.INFO, $"[{directoryToCreate}] created");
            }
 
            return isDirectory;
        }
       
        internal GPALFile Clone()
        {
            GPALFile clone = new GPALFile();
            IGPALFileInternal cloneInternal = (IGPALFileInternal)clone;
            IGPALFileInternal thisInternal = (IGPALFileInternal)this;
 
            // Manually copy FileSettings properties
            cloneInternal.FileSettings = new GPALFileSettings
            {
                Filenames = new List<string>(thisInternal.FileSettings.Filenames),
                FileCount = thisInternal.FileSettings.FileCount,
                NextFileCount = thisInternal.FileSettings.NextFileCount,
                Delimiter = new List<char?>(thisInternal.FileSettings.Delimiter),
                FieldsEnclosedInQuotes = new List<bool>(thisInternal.FileSettings.FieldsEnclosedInQuotes),
                FirstLineIsColumnNames = new List<bool>(thisInternal.FileSettings.FirstLineIsColumnNames),
                IgnoreFirstLineColumnNames = new List<bool>(thisInternal.FileSettings.IgnoreFirstLineColumnNames),
                UseOneHeaderForAllFiles = thisInternal.FileSettings.UseOneHeaderForAllFiles,
                TokenList = thisInternal.FileSettings.TokenList != null ? new List<IGPALGrid<string>>(thisInternal.FileSettings.TokenList) : null,
                FileData = thisInternal.FileSettings.FileData != null ? new List<string>(thisInternal.FileSettings.FileData) : null,
                FileDictionary = thisInternal.FileSettings.FileDictionary != null ? new List<Dictionary<object, dynamic>>(thisInternal.FileSettings.FileDictionary) : null,
                FileGrid = thisInternal.FileSettings.FileGrid != null ? new List<IGPALGrid<string>>(thisInternal.FileSettings.FileGrid) : null,
                AlreadyTokenized = thisInternal.FileSettings.AlreadyTokenized
            };
 
            // Copy FileDictionary directly (it's already a list of dictionaries)
            cloneInternal.FileDictionary = thisInternal.FileDictionary != null ? new List<Dictionary<object, dynamic>>(thisInternal.FileDictionary) : null;
 
            return clone;
        }
        #endregion Helpers
        #region Implicit Converter
        public static implicit operator string(GPALFile url) => url.Filename;
 
        // Implicit conversion from string to GPALFile, so a filename string
        // can be passed directly where GPALFile is expected
        public static implicit operator GPALFile(string fileName)
        {
            var file = new GPALFile();  // uses parameterless constructor
 
            if (string.IsNullOrWhiteSpace(fileName))
            {
                GPAL.PublishSimpleEvent(
                    GPALEventType.DEBUG,
                    "Implicit conversion received null or whitespace filename - " +
                    "creating placeholder GPALFile with no real filename.",
                    "(null or empty)",
                    GPALObjectType.GPALFile
                );
 
                file.WithFileName("Placeholder_Empty_" + DateTime.UtcNow.Ticks);
                return file;
            }
 
            string trimmed = fileName.Trim();
 
            // Add the filename using the existing fluent method
            file.WithFileName(trimmed);
 
            // Give it a recognizable name for debugging/logs
            string shortName = trimmed.Length > 48
                ? trimmed.Substring(0, 45) + "..."
                : trimmed;
 
            GPAL.PublishSimpleEvent(
                GPALEventType.DEBUG,
                $"Implicit GPALFile created from [{shortName}]."
            );
 
            return file;
        }
        #endregion Implicit Converter
    }

    internal class NaturalFilenameComparer : IComparer<string>
    {
        public static readonly NaturalFilenameComparer Instance = new NaturalFilenameComparer();
 
        public int Compare(string x, string y)
        {
            IEnumerable<string> partsX = SplitIntoParts(x);
            IEnumerable<string> partsY = SplitIntoParts(y);
 
            using (var enumX = partsX.GetEnumerator())
            using (var enumY = partsY.GetEnumerator())
            {
                while (true)
                {
                    bool hasX = enumX.MoveNext();
                    bool hasY = enumY.MoveNext();
 
                    if (false == hasX && false == hasY)
                        return 0;
                    if (false == hasX)
                        return -1;
                    if (false == hasY)
                        return 1;
 
                    string partX = enumX.Current;
                    string partY = enumY.Current;
 
                    bool isNumericX = char.IsDigit(partX[0]);
                    bool isNumericY = char.IsDigit(partY[0]);
 
                    int comparison;
 
                    if (true == isNumericX && true == isNumericY)
                    {
                        // compare numerically, falling back to length for very large numbers
                        BigInteger numX = BigInteger.Parse(partX);
                        BigInteger numY = BigInteger.Parse(partY);
                        comparison = numX.CompareTo(numY);
                    }
                    else
                    {
                        comparison = string.Compare(partX, partY, StringComparison.OrdinalIgnoreCase);
                    }
 
                    if (0 != comparison)
                        return comparison;
                }
            }
        }
 
        private static IEnumerable<string> SplitIntoParts(string value)
        {
            int index = 0;
 
            while (index < value.Length)
            {
                bool isDigit = char.IsDigit(value[index]);
                int start = index;
 
                while (index < value.Length && char.IsDigit(value[index]) == isDigit)
                    index++;
 
                yield return value.Substring(start, index - start);
            }
        }
    }
}