Main.cpp

/* File: Main.cpp
   Project: Kanabo
   Purpose: Processes launch arguments and acts on them by issuing instructions to GameDataManager.
   Notes: Some basic terminology for understanding the argument handling code: an argument is any space-separated term passed to Kanabo on the
          command line. An option is an argument preceded by "--". An option value is an argument not preceded by "--" that follows an option.
          A task is a job requested by an option. Terminology related to game data is in GameData.cpp's header comment. The overall hierarchy of
          this program is as follows, in descending order: Main -> GameDataManager (GDM) -> GameData -> Template -> Field -> DataIO -> DiskItem.
   Margin Guide: |----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- -----|
   Copyright 2026 Iritscen */

#include "GameDataManager.hpp" // also brings in DataIO.hpp, DiskItem.hpp, Field.hpp and Template.hpp

#include <algorithm> // needed on Windows for std::replace
#include <charconv> // for from_chars()
#include <cstdlib> // for getenv()
#include <format> // needed on Windows for std::format
#include <functional> // needed on Windows for std::function
#include <iomanip> // needed on Windows for std::quoted
#include <iostream> // for cout, cerr
#include <optional> // for optional
#include <sstream> // for istringstream
#if MAC
    #include <unistd.h> // for STDOUT_FILENO
#endif
#if MAC
    #include <sys/ioctl.h> // for ioctl() and TIOCGWINSZ
#elif WIN
    #include <io.h> // for _isatty() and _fileno()
    #define WIN32_LEAN_AND_MEAN
    #include <windows.h> // for GetConsoleScreenBufferInfo()
    #pragma comment(lib, "user32.lib") // for GetDpiForSystem()
#endif

using std::cerr;
using std::cout;
using std::errc;
using std::from_chars;
using std::find_if;
using std::find_if_not;
using std::format;
using std::function;
using std::initializer_list;
using std::istringstream;
using std::locale;
using std::map;
using std::numpunct;
using std::nullopt;
using std::optional;
using std::pair;
using std::quoted;
using std::stoi;
using std::streambuf;
using std::streamsize;
using std::string;
using std::string_view;
using std::unordered_map;
using std::vector;

/********************** Enums, Structs & Tables **********************/
enum class RunMode : uint8_t
{
    Unset,
    CLI,   // user invoked Kanabo from command line
    Batch, // Kanabo has been invoked on command line to run a batch file
    GUI    // Kanabo was double-clicked as desktop application
};

enum class HelpCategory : uint8_t
{
    About,
    IO,
    Task,
    Filter,
    Modifier
};
using HC = HelpCategory;

struct HelpCategoryEntry
{
    HelpCategory hceCat;
    string       hceName;
    string       hceDesc;
};

// Header text used by the help command to delineate categories
namespace {
vector<HelpCategoryEntry> HelpCategoryEntryTable = // NOLINT(cert-err58-cpp)
{
    {HC::About,    "[About]",        "Information about Kanabo."},
    {HC::IO,       "[Input/Output]", "How to specify source data and destinations for tasks."},
    {HC::Task,     "[Tasks]",        "Operations you can perform on Oni game data."},
    {HC::Filter,   "[Filters]",      "How to limit the scope of a task."},
    {HC::Modifier, "[Modifiers]",    "Additional settings for I/O, tasks, filters or other modifiers."}
};
} // anonymous namespace

// TypeCodes of value that an option can require
enum class OptionValueTypeReq : uint8_t
{
    Nothing,
    File,
    Folder,
    FileOrFolder,
    DataPacket // arbitrary text meant for a specific command
};
using OVT = OptionValueTypeReq;

// Quantities of value that an option can require
enum class OptionValueQuantityReq : uint8_t
{
    None,
    ZeroOrOne,
    One,
    Some
};
using OVQ = OptionValueQuantityReq;

struct OptionValueEntry
{
    OptionValueQuantityReq oveQuan; // required quantity of type
    OptionValueTypeReq     oveType; // required type
    string                 usageHelpText; // human-readable needs of this option, for the help page
    string                 errorHelpText; // human-readable needs of this option, for error message
};

// Human-readable strings used by the help command when explaining option value requirements
namespace {
vector<OptionValueEntry> OptionValueTable = // NOLINT(cert-err58-cpp)
{
    {OVQ::None,      OVT::Nothing,      "N/A",
                                        "N/A"},
    {OVQ::ZeroOrOne, OVT::DataPacket,   "[option name]",
                                        "an option's name (optional)"},
    {OVQ::One,       OVT::File,         "[path/to/file]",
                                        "a path to a file"},
    {OVQ::One,       OVT::Folder,       "[path/to/folder]",
                                        "a path to a folder"},
    {OVQ::One,       OVT::FileOrFolder, "[path/to/file_or_folder]",
                                        "a path to a file or folder"},
    {OVQ::One,       OVT::DataPacket,   "[data for this option]",
                                        "one value with option-specific data"},
    {OVQ::Some,      OVT::File,         "[path/to/file1] [path/to/file2] (...)",
                                        "a path to at least one file (or more, separated by spaces)"},
    {OVQ::Some,      OVT::Folder,       "[path/to/folder1] [path/to/folder2] (...)",
                                        "a path to at least one folder (or more, separated by spaces)"},
    {OVQ::Some,      OVT::FileOrFolder, "[path/to/file_or_folder1] [path/to/file_or_folder2] (...)",
                                        "a path to at least one file or folder (or more, separated by spaces)"},
    {OVQ::Some,      OVT::DataPacket,   "[data 1 for this option] [data 2 for this option] (...)",
                                        "one or more arguments with option-specific data, separated by spaces"}
};
} // anonymous namespace

// Every option that can be supplied to the program, defined with unique bits so we add them to a bitset for use in OptionEntry's "goesWith"
enum class Option : uint64_t
{
    Unset             = 0x0000000000,
    Alias             = 0x0000000001,
    FilterName        = 0x0000000002,
    FilterIndex       = 0x0000000004,
    FilterTag         = 0x0000000008,
    FilterField       = 0x0000000010,
    FilterValue       = 0x0000000020,
    FilterSize        = 0x0000000040,
    Source            = 0x0000000080,
    Destination       = 0x0000000100,
    DestName          = 0x0000000200,
    OverwritePolicy   = 0x0000000400,
    SanitizePolicy    = 0x0000000800,
    DisplayScale      = 0x0000001000,
    OnceLine_        = 0x0000002000, // above this line are options which must not be used more than once
    FilterNamePartial = 0x0000004000,
    FilterValueWhole  = 0x0000008000,
    FilterCaseInsens  = 0x0000010000,
    ListFields        = 0x0000020000,
    ShowFieldOffsets  = 0x0000040000,
    ShowLinkers       = 0x0000080000,
    ShowLinkees       = 0x0000100000,
    ShowPlaceholders  = 0x0000200000,
    ShowUnnamed       = 0x0000400000,
    ShowOrphans       = 0x0000800000,
    TaskLine_        = 0x0001000000, // above this line are non-task options, i.e. options which fall under HC::IO, HC::Filter and HC::Modifier
    Batch             = 0x0002000000,
    Help              = 0x0004000000,
    Version           = 0x0008000000,
    Compliance        = 0x0010000000,
    Knowledge         = 0x0020000000,
    Flags             = 0x0040000000,
    TypeCodes         = 0x0080000000,
    FileLine_        = 0x0100000000, // below this line are options which operate on source files
    Info              = 0x0200000000,
    ListInstances     = 0x0400000000,
    ListTables        = 0x0800000000,
    ListTemplates     = 0x1000000000,
    Export            = 0x2000000000, // maps to either Operation::ExportBinary or ::ExportGraphics depending on argument received
    Display           = 0x4000000000, // below this are convenience bitsets for use with the "goesWith" safeguard in OptionTable
    Filterable        = (ListInstances + Export + Display), // these accept any filter
    TagFilterable     = (Knowledge + ListInstances + ListTables + ListTemplates + Export + Display), // these accept a tag filter
    MustFilter        = (Export + Display), // these require a filter to limit output
    WritesOutput      = (Export)
};

// Which I/O-related options are required for the task this option performs?
enum class OptionIORequirement : uint8_t
{
    None        = 0x0, // explicit values defined so that we can safely use bit tests to check option requirements in an efficient manner
    Source      = 0x1,
    Destination = 0x2,
    SrcAndDst   = (Source + Destination),
    TaskData    = 0x4,
    All         = (TaskData + SrcAndDst)
};
using IOReq = OptionIORequirement;

struct OptionEntry
{
    string                 fullName;  // launch argument name that user types after "--"
    string                 shortName; // short version for convenience, which follows a "-"
    Option                 optCode;   // internal code for this option
    Operation              operCode;  // which GDM operation this option maps to, if any
    OptionIORequirement    ioReq;     // what I/O options must be used along with this option
    OptionValueQuantityReq valQReq;   // how many values this option requires
    OptionValueTypeReq     valTReq;   // what type of values this option requires
    HelpCategory           helpCat;   // category where this option will appear on the help page
    uint64_t               goesWith;  // what Option(s) this modifier argument is intended for
    string                 longHelp;  // full usage description, shown by --help <option>
    string                 shortHelp; // brief one-liner, shown in the default --help listing
};

// If changing the name of an argument, make sure to search the rest of the table for mentions of that argument by its old name
namespace {
vector<OptionEntry> OptionTable = // NOLINT(cert-err58-cpp)
{
    {"--alias", "-a",                  Option::Alias,             Operation::None,           IOReq::Source,    OVQ::One,       OVT::File,
        HC::IO,       static_cast<uint64_t>(Option::Unset),
        "For supplying a text file with shorthand names for file paths that can be used in a command or commands. Path aliases allow you to "
        "reference files by shorthand names prefixed by a '@' when specifying a source or destination for an operation, e.g. "
        "\"--source @airport\". Here are some sample lines in a path alias file:\n"
#if MAC
        "      winr /path/to/Installations/Windows retail/GameDataFolder\n"
        "      airport /path/to/Installations/Mac retail/GameDataFolder/level4_Final.dat\n"
#elif WIN
        "      winr C:\\path\\to\\Installations\\Windows retail\\GameDataFolder\n"
        "      airport C:\\path\\to\\Installations\\Mac retail\\GameDataFolder\\level4_Final.dat\n"
#endif
        "   If an alias points to a GameDataFolder directory, as with \"winr\" above, you can append a level number to the alias when you call "
        "Kanabo, e.g. \"--source @winr8\", to have it resolve to the level data file for that level. Folder expansion works for the PS2's GDF "
        "as well, i.e. \"/1\" in the disc directory. Make sure not to end an alias name in the file with a number, e.g. \"airport2\", or "
        "Kanabo will assume it's a reference to level 2 within a GameDataFolder pointed to by an alias called \"airport\".",
        "For supplying a text file with shorthand names for file paths."},
    {"--batch", "-b",                  Option::Batch,             Operation::None,           IOReq::None,      OVQ::One,       OVT::File,
        HC::Task,     static_cast<uint64_t>(Option::Unset),
        "Runs a series of commands listed in a text file. Each command must be separated by a newline. If specifying an alias file to use "
        "with your commands, you must do it on the command line alongside the --batch option. You must specify a destination as part of each "
        "command if the command produces file output.",
        "Runs a series of commands listed in a text file."},
    {"--compliance", "-c",             Option::Compliance,        Operation::Compliance,     IOReq::None,      OVQ::None,      OVT::Nothing,
        HC::About,    static_cast<uint64_t>(Option::Unset),
        "Prints information on which templates Kanabo has been certified as understanding on a field by field level. Templates in this list "
        "can have their field values displayed, filtered by, etc. and can be exported smartly.",
        "Prints information on which templates Kanabo has been certified for."},
    {"--dest", "-d",                   Option::Destination,       Operation::None,           IOReq::None,      OVQ::One,       OVT::FileOrFolder,
        HC::IO,       static_cast<uint64_t>(Option::Unset),
        "Specifies the location to which files should be outputted, or the game data file or folder of game data files to create.",
        "Specifies the location to which files should be outputted."},
    {"--display-scale", "-ds",         Option::DisplayScale,      Operation::None,           IOReq::None,      OVQ::One,       OVT::DataPacket,
        HC::Modifier, static_cast<uint64_t>(Option::Display),
        "Sets the scale factor for image display with --display (default: 2x on Retina displays, 1x otherwise). Only takes integer values.",
        "Sets the scale factor to use with --display."},
    {"--display", "-di",               Option::Display,           Operation::Display,        IOReq::Source,    OVQ::None,      OVT::Nothing,
        HC::Task,     static_cast<uint64_t>(Option::Unset),
        "Displays an instance on the command line using a graphics protocol, if the user is in a graphics-capable terminal (currently "
        "supported: kitty on macOS, WezTerm on Windows). Falls back to writing a temporary file and opening it with the default image viewer "
        "if the terminal does not support a graphics protocol. Supported types: TXMP and TXAN (textures/animations), TSFT and TSFF (font/font "
        "family). Must be used with the --filter-name option to limit the instances to be displayed. Note that displaying a TXAN will omit the "
        "first frame of the animation because this is found in the initial TXMP; you should display the texture using the name of the animated "
        "TXMP to see the full animation.",
        "Displays an instance visually if possible."},
    {"--export",          "-e",        Option::Export,            Operation::None,           IOReq::All,       OVQ::One,       OVT::DataPacket,
        HC::Task,     static_cast<uint64_t>(Option::Unset),
        "Exports the desired instances from a game data file. Requires an option value with the intended format: \"onix\" exports OniSplit-"
        "compatible .onix files; \"png\" exports PNG/APNG images (assuming template support). Must be used with a filter option to specify "
        "which instances to export.",
        "Exports instances from a game data file as .onix files or PNG."},
    {"--filter-case-insens", "-fci",   Option::FilterCaseInsens,  Operation::None,           IOReq::None,      OVQ::None,      OVT::Nothing,
        HC::Modifier, static_cast<uint64_t>(Option::FilterName),
        "Tells the name filter to be case-insensitive.",
        "Tells the name filter to be case-insensitive."},
    {"--filter-field", "-ff",          Option::FilterField,       Operation::None,           IOReq::None,      OVQ::One,       OVT::DataPacket,
        HC::Modifier, static_cast<uint64_t>(Option::ListFields),
        "Adds onto the --list-fields modifier to the --list command, telling it to only show the field whose name matches the value you supply "
        "to this option. Note that --list-fields requires a filter option to limit the templates shown, regardless of whether you use this "
        "filter modifier.",
        "Limits --list-fields output to only the named field."},
    {"--filter-index", "-fi",          Option::FilterIndex,       Operation::None,           IOReq::Source,    OVQ::One,       OVT::DataPacket,
        HC::Filter,   static_cast<uint64_t>(Option::Filterable),
        "Limits the results of a task to instances which match this index number or range of numbers. Specify a range with the '-' character.",
        "Limits the results of a task to instances matching an index number or range."},
    {"--filter-name", "-fn",           Option::FilterName,        Operation::None,           IOReq::Source,    OVQ::One,       OVT::DataPacket,
        HC::Filter,   static_cast<uint64_t>(Option::Filterable),
        "Limits the results of a task to instances which fully match this name. Searching for \"TRAMKON\" will not return any results because "
        "there are no resources by that name. You must add the wildcard operator, '-': \"TRAMKON-\"; this will show all resources beginning "
        "with TRAMKON. You could also search for \"-KON-\" to see all resources with that string somewhere in their name. See the filter "
        "arguments under Modifiers for additional options.",
        "Limits the results of a task to instances fully matching this name."},
    {"--filter-name-partial", "-fnp",  Option::FilterNamePartial, Operation::None,           IOReq::None,      OVQ::None,      OVT::Nothing,
        HC::Modifier, static_cast<uint64_t>(Option::FilterName),
        "Tells the name filter to validate on a partial match. This means you do not need to use the wildcard operator with the name filter in "
        "order to find resources that contain a partial string.",
        "Tells the name filter to validate on a partial match without the wildcard."},
    {"--filter-size", "-fs",           Option::FilterSize,        Operation::None,           IOReq::None,      OVQ::One,       OVT::DataPacket,
        HC::Filter,   static_cast<uint64_t>(Option::ListInstances),
        "Limits the instance list to instances whose total size (including aux data) matches the given expression. Use a comparison operator "
        "(e.g. \">100\", \"<=512\"), a range (e.g. \"100-200\", inclusive), or an exact value (e.g. \"256\" or \"=256\"). All values are in "
        "bytes. Remember to use quotes around option values that use '<' or '>' or your shell may intercept them.",
        "Limits the instance list to instances of a certain size."},
    {"--filter-tag", "-ft",            Option::FilterTag,         Operation::None,           IOReq::Source,    OVQ::One,       OVT::DataPacket,
        HC::Filter,   static_cast<uint64_t>(Option::TagFilterable),
        "Limits the results of a task to instances with the supplied tag. For BINA and OBJC subtypes, you can search with either the qualified "
        "or unqualified name, e.g. \"TRIG\" would show both TRIG and BINA/OBJC/TRIG, but \"BINA/OBJC/TRIG\" will only show the latter.",
        "Limits the results of a task to instances with the supplied tag."},
    {"--filter-value", "-fv",          Option::FilterValue,       Operation::None,           IOReq::None,      OVQ::One,       OVT::DataPacket,
        HC::Filter,   static_cast<uint64_t>(Option::FilterField),
        "Filters the instance list to only show instances where the field specified by --filter-field contains the given value. Your input "
        "must align with the kind of data the field holds: for numeric fields, use a comparison operator (e.g. \">0\", \"<=10\"), a range "
        "(e.g. \"10-20\" or \"-5.0-5.0\", inclusive), or an exact value (floats are compared with tolerance); you can also use a \"!=\" prefix "
        "to negate the match, e.g. \"!=60\" to find fields whose value is not 60, or \"!=60-90\" to find fields outside that range. For "
        "boolean fields, use \"true\"/\"false\" or \"yes\"/\"no\". For flag set fields, use \"has:FlagName\" to match when the named flag is "
        "set, \"has no:FlagName\" to match when it is not set, or \"has none\" to match when no flags are set; multiple flag conditions can be "
        "combined in one filter (e.g. \"has:FlagA has no:FlagB\") and all must be satisfied. For type code fields, use \"type:TypeName\" to "
        "match by type name, \"type not:TypeName\" to match any type other than the given name, or a numeric value to match by raw code. For "
        "textual fields, the match is exact and case-sensitive. Filtering using a syntax incompatible with the field's type will produce no "
        "results for that field.",
        "Filters the instance list to instances with a certain field value."},
    {"--filter-value-whole", "-fvw",   Option::FilterValueWhole,  Operation::None,           IOReq::None,      OVQ::None,      OVT::Nothing,
        HC::Modifier, static_cast<uint64_t>(Option::FilterValue),
        "Modifies --filter-value to show all fields of each matching instance rather than only the field that matched.",
        "Modifies --filter-value to show all fields of each matching instance."},
    {"--flags", "-f",                  Option::Flags,             Operation::Flags,          IOReq::None,      OVQ::None,      OVT::Nothing,
        HC::About,    static_cast<uint64_t>(Option::Unset),
        "Lists the names of all flags defined across all certified templates. Useful as a reference when using the --filter-value option on "
        "a flag set field.",
        "Lists the names of all flags defined across all certified templates."},
    {"--help", "-h",                   Option::Help,              Operation::None,           IOReq::None,      OVQ::ZeroOrOne, OVT::DataPacket,
        HC::About,    static_cast<uint64_t>(Option::Unset),
        "Prints this help message. Use '--help <option name without leading hyphens>' for detailed help on a specific option.",
        "Prints this help message. Use '--help <option name>' for detailed help."},
    {"--info", "-i",                   Option::Info,              Operation::Info,           IOReq::Source,    OVQ::None,      OVT::Nothing,
        HC::Task,     static_cast<uint64_t>(Option::Unset),
        "Gives basic information about a game data file.",
        "Gives basic information about a game data file."},
    {"--knowledge", "-k",              Option::Knowledge,         Operation::Knowledge,      IOReq::None,      OVQ::None,      OVT::Nothing,
        HC::About,    static_cast<uint64_t>(Option::Unset),
        "Prints Kanabo's knowledge of each certified template, showing the address of each field for all known game data formats, plus the "
        "template's total size. The --filter-tag option will work with this operation to only show the desired template.",
        "Prints Kanabo's knowledge of each certified template's fields and sizes."},
    {"--list", "-l",                   Option::ListInstances,     Operation::ListInstances,  IOReq::Source,    OVQ::None,      OVT::Nothing,
        HC::Task,     static_cast<uint64_t>(Option::Unset),
        "Lists the instances in a game data file.",
        "Lists the instances in a game data file."},
    {"--list-fields", "-lf",           Option::ListFields,        Operation::None,           IOReq::None,      OVQ::None,      OVT::Nothing,
        HC::Modifier, static_cast<uint64_t>(Option::ListInstances),
        "Tells the instance list command to show the names and values of each field in each instance. Outputs a large amount of text, so a "
        "filter must also be used with this option.",
        "Tells the instance list command to show an instance's field names and values."},
    {"--list-tables", "-tab",          Option::ListTables,        Operation::ListTables,     IOReq::Source,    OVQ::None,      OVT::Nothing,
        HC::Task,     static_cast<uint64_t>(Option::Unset),
        "Prints the raw descriptor tables in a game data file: template descriptors, name descriptors and instance descriptors. Use the tag "
        "filter if you only want to see one template.",
        "Prints the raw descriptor tables in a game data file."},
    {"--list-templates", "-tem",       Option::ListTemplates,     Operation::ListTemplates,  IOReq::Source,    OVQ::None,      OVT::Nothing,
        HC::Task,     static_cast<uint64_t>(Option::Unset),
        "Scans the game data file(s) or folder(s) of data files and prints a sorted list of the template tags and their checksums across all "
        "files. If the checksum for a given template differs across the files specified, all checksums will be printed. Use the tag filter if "
        "you only want to see one template.",
        "Compiles a list of template tags and checksums in some data file(s)."},
    {"--output", "-o",                 Option::DestName,          Operation::None,           IOReq::None,      OVQ::One,       OVT::DataPacket,
        HC::IO,       static_cast<uint64_t>(Option::WritesOutput),
        "Overrides the default output file name for an exported file (which would be the name of the resource being exported). Do not include "
        "the file suffix when using this option, as the suffix will be determined by Kanabo.",
        "Overrides the default output file name for an exported file."},
    {"--overwrite-policy", "-op",      Option::OverwritePolicy,   Operation::None,           IOReq::None,      OVQ::One,       OVT::DataPacket,
        HC::Modifier, static_cast<uint64_t>(Option::WritesOutput),
        "Sets the name collision policy when performing an export operation. Use \"overwrite\" (or \"o\") to overwrite an existing file "
        "without asking, \"skip\" (or \"s\") to automatically pass over the file, or \"unique\" (or \"u\") to automatically generate a unique "
        "file name for the new export.",
        "Sets the name collision policy when performing an export operation."},
    {"--sanitize-policy", "-sp",       Option::SanitizePolicy,    Operation::None,           IOReq::None,      OVQ::One,       OVT::DataPacket,
        HC::Modifier, static_cast<uint64_t>(Option::WritesOutput),
        "Sets the policy for how illegal characters in file names are encoded when exporting an instance. Use \"unicode\" (or \"u\") to "
        "replace illegal characters with their Unicode full-width equivalents (the default), or \"html\" (or \"h\") to replace them with HTML "
        "percent-encodings.",
        "Sets the policy for encoding illegal characters in file names when exporting."},
    {"--show-field-offsets", "-sfo",   Option::ShowFieldOffsets,  Operation::None,           IOReq::None,      OVQ::None,      OVT::Nothing,
        HC::Modifier, static_cast<uint64_t>(Option::ListFields),
        "Tells the instance list command to show the byte offset of each field within its instance. Use this alongside the option to list "
        "fields, otherwise it will have no effect.",
        "Shows the byte offset of each field with the instance list command."},
    {"--show-linkees", "-sle",         Option::ShowLinkees,       Operation::None,           IOReq::None,      OVQ::One,       OVT::DataPacket,
        HC::Modifier, static_cast<uint64_t>(Option::ListInstances),
        "Controls whether the instance list command shows the instances which are linked to by filter-matched instances. Use \"yes\" to show "
        "matching instances followed by their linkees or \"only\" to show only the linkees rather than the matching instances themselves. "
        "Kanabo's default behavior is to not show linked-to instances, so using \"no\" with this option produces the same behavior as not "
        "using it at all. The search for linked-to instances is recursive: Kanabo shows instances linked to by the matching instance's "
        "linkees, and so on. When this option is set to anything other than \"no\", --list will require at least one filter option to be "
        "supplied. Cannot be used together with --show-linkers.",
        "Shows instances linked to by filter-matched instances."},
    {"--show-linkers", "-slr",         Option::ShowLinkers,       Operation::None,           IOReq::None,      OVQ::One,       OVT::DataPacket,
        HC::Modifier, static_cast<uint64_t>(Option::ListInstances),
        "Controls whether the instance list command shows the instances which link to filter-matched instances. Use \"yes\" to show matching "
        "instances followed by their linkers or \"only\" to show only the linkers rather than the matching instances themselves. Kanabo's "
        "default behavior is to not show linking instances, so using \"no\" with this option produces the same behavior as not using it at "
        "all. The search for linking instances is recursive: Kanabo shows instances that link to the matching instance's linkers, and so on. "
        "When this option is set to anything other than \"no\", --list will require at least one filter option to be supplied. Cannot be used "
        "together with --show-linkees.",
        "Shows instances that link to filter-matched instances."},
    {"--show-placeholders", "-spl",    Option::ShowPlaceholders,   Operation::None,           IOReq::None,      OVQ::One,       OVT::DataPacket,
        HC::Modifier, static_cast<uint64_t>(Option::ListInstances),
        "Controls whether placeholder instances are shown in the instance list. Use \"no\" to hide them or \"only\" to show only the "
        "placeholders. Kanabo's default behavior is to show placeholders, so using \"yes\" with this option produces the same behavior as not "
        "using it at all.",
        "Controls whether placeholder instances are shown in the instance list."},
    {"--show-unnamed", "-sun",         Option::ShowUnnamed,       Operation::None,           IOReq::None,      OVQ::One,       OVT::DataPacket,
        HC::Modifier, static_cast<uint64_t>(Option::ListInstances),
        "Controls whether unnamed instances are shown in the instance list. Use \"no\" to hide them or \"only\" to show only the unnamed "
        "instances. Kanabo's default behavior is to show unnamed instances, so using \"yes\" with this option produces the same behavior as "
        "not using it at all.",
        "Controls whether unnamed instances are shown in the instance list."},
    {"--show-orphans", "-sor",         Option::ShowOrphans,       Operation::None,           IOReq::None,      OVQ::One,       OVT::DataPacket,
        HC::Modifier, static_cast<uint64_t>(Option::ListInstances),
        "Controls whether orphan instances are shown in the instance list. An orphan is an unnamed instance that has no linkers (no other "
        "instance links to it). Use \"only\" to show only orphans or \"no\" to hide them. Kanabo's default behavior is to show orphans, so "
        "using \"yes\" with this option produces the same behavior as not using it at all. Cannot be used together with --show-linkers or "
        "--show-linkees.",
        "Controls whether orphan instances are shown in the instance list."},
    {"--source", "-s",                 Option::Source,            Operation::None,           IOReq::None,      OVQ::Some,      OVT::FileOrFolder,
        HC::IO,       static_cast<uint64_t>(Option::Unset),
        "Specifies the game data file(s) or folder(s) of game data files to draw from.",
        "Specifies the game data file(s) or folder(s) to draw from."},
    {"--typecodes", "-t",              Option::TypeCodes,         Operation::TypeCodes,      IOReq::None,      OVQ::None,      OVT::Nothing,
        HC::About,    static_cast<uint64_t>(Option::Unset),
        "Lists the names of all type codes defined across all certified templates. Useful as a reference when using the --filter-value "
        "option on a type code field.",
        "Lists the names of all type codes defined across all certified templates."},
    {"--version", "-v",                Option::Version,           Operation::None,           IOReq::None,      OVQ::None,      OVT::Nothing,
        HC::About,    static_cast<uint64_t>(Option::Unset),
        "Prints the program version.",
        "Prints the program version."},
};
} // anonymous namespace

/****************************** Globals ******************************/
// Constants
constexpr string kAppVer = "1.3.27.0";

// Variables
namespace { // enforce internal linkage
namespace Main
{
    RunMode                   mode = RunMode::Unset;
    string                    batchPath; // path to file with list of commands to run in Batch mode
    unordered_map<string, string> aliases; // path aliases loaded from the --alias argument's file; persists across batch iterations
    vector<string>            arguments; // all arguments the program received
    vector<string>            srcPaths; // source file(s)/folder(s) for a task
    string                    dstPath; // destination file/folder for a task
    string                    destName; // custom output name for an exported file
    Option                    taskRequested = Option::Unset; // which task the user requested
    vector<string>            taskData; // data packet for a task
    // These are the primary filters available for limiting the instances acted on by an operation
    InstanceFilter            instanceFilter = {.ifActive = false, .ifName = "", .ifPartialMatch = false, // NOLINT(cert-err58-cpp)
                                                .ifCaseInsensitive = false, .ifIndex1 = 0, .ifIndex2 = 0, .ifTag = "", .ifFilterValue = "",
                                                .ifFilterSize = ""};
    // Settings for the "list instance" task
    ListSettings              listSettings = {.lsShowValues = false, .lsShowOffsets = false, .lsFilterField = "", // NOLINT(cert-err58-cpp)
                                              .lsShowWholeValueMatch = false, .lsShowLinkers = YesNoOnly::No,
                                              .lsShowLinkees = YesNoOnly::No, .lsShowPlaceholders = YesNoOnly::Yes,
                                              .lsShowUnnamed = YesNoOnly::Yes, .lsShowOrphans = YesNoOnly::Yes};
    int                       displayScale = -1; // scale factor for displaying textures (-1 = auto-detect display scale)
    optional<OverwritePolicy> overwritePolicy; // policy on name collision; nullopt means user has not specified one, so use default behavior
    optional<SanitizePolicy>  sanitizePolicy; // policy on illegal char encoding; nullopt means use Unicode full-width default
}
} // anonymous namespace

/************************** Helper Functions **************************/
// Subclass the current locale to add commas to number output
class comma_numpunct : public numpunct<char>
{
    protected:
    virtual char do_thousands_sep() const
    {
        return ',';
    }
    
    virtual string do_grouping() const
    {
        return "\3";
    }
};

// A streambuf subclass that intercepts characters written to cout/cerr and word-wraps long lines to fit the terminal window
class WordWrapBuf : public streambuf
{
public:
    WordWrapBuf(streambuf * sink) : sink_(sink), terminalWidth_(getTerminalWidth()) {}

protected:
    int_type overflow(int_type c) override
    {
        if (c == traits_type::eof())
            return traits_type::eof();
        if (c == '\n')
        {
            flushLine();
            return sink_->sputc('\n');
        }
        lineBuffer_ += static_cast<char>(c);
        return c;
    }

    int sync() override
    {
        // Do not flush the partial-line buffer here; content will be word-wrapped and emitted when a newline arrives via overflow(). Flushing
        // here would cause each operator<< (cerr has unitbuf set) to be treated as an independent line, breaking the wrap budget for messages
        // assembled across multiple operator<< calls.
        return sink_->pubsync();
    }

private:
    streambuf * sink_;
    string      lineBuffer_;
    int         terminalWidth_;

    static int getTerminalWidth()
    {
#if MAC
        struct winsize ws = {};
        if (ioctl(STDOUT_FILENO, TIOCGWINSZ, &ws) == 0 && ws.ws_col > 0)
            return ws.ws_col;
#elif WIN
        CONSOLE_SCREEN_BUFFER_INFO csbi = {};
        if (GetConsoleScreenBufferInfo(GetStdHandle(STD_OUTPUT_HANDLE), &csbi))
            return csbi.srWindow.Right - csbi.srWindow.Left + 1;
#endif
        return 80; // fallback terminal width
    }

    void flushLine()
    {
        if (lineBuffer_.empty())
            return;

        // Fast path: line already fits within the terminal width
        if (static_cast<int>(lineBuffer_.size()) <= terminalWidth_)
        {
            sink_->sputn(lineBuffer_.data(), static_cast<streamsize>(lineBuffer_.size()));
            lineBuffer_.clear();
            return;
        }

        // Measure leading whitespace to use as an indent on continuation lines
        size_t indentLen = 0;
        while (indentLen < lineBuffer_.size() && lineBuffer_[indentLen] == ' ')
            indentLen++;
        string indent(indentLen, ' ');

        // Tokenize the line by spaces, hyphens, and forward slashes. Spaces are consumed as separators.
        // Hyphens and forward slashes are sticky break characters: they stay at the end of their token
        // and the token that follows them carries no space prefix. This allows wrapping at path
        // separators and hyphenated words without altering the visible characters on each line.
        vector<pair<string, bool>> tokens; // (token text, spaceBefore)
        size_t i = indentLen; // start after the leading indent which is prepended separately
        size_t tokenStart = i;
        bool spaceBefore = false; // first token is prefixed only by the indent, not a space

        while (i <= lineBuffer_.size())
        {
            char c = (i < lineBuffer_.size()) ? lineBuffer_[i] : '\0';
            if (c == ' ' || c == '\0')
            {
                if (i > tokenStart)
                {
                    tokens.push_back({lineBuffer_.substr(tokenStart, i - tokenStart), spaceBefore});
                    spaceBefore = true; // tokens after a space are space-separated
                }
                else
                    spaceBefore = true; // consecutive spaces; carry through the space flag
                tokenStart = i + 1;
            }
            else if (c == '-' || c == '/')
            {
                // Include the break character at the end of this token
                tokens.push_back({lineBuffer_.substr(tokenStart, i - tokenStart + 1), spaceBefore});
                spaceBefore = false; // token following a break char attaches without a space
                tokenStart = i + 1;
            }
            i++;
        }

        // Greedily pack tokens onto output lines
        string currentLine = indent;
        bool firstToken = true;
        for (const auto & [text, needsSpace] : tokens)
        {
            if (firstToken)
            {
                currentLine += text;
                firstToken = false;
            }
            else
            {
                int candidateSize = static_cast<int>(currentLine.size()) + (needsSpace ? 1 : 0)
                                    + static_cast<int>(text.size());
                if (candidateSize <= terminalWidth_)
                {
                    if (needsSpace)
                        currentLine += ' ';
                    currentLine += text;
                }
                else
                {
                    // Current line is full; emit it and start a new one with the continuation indent
                    sink_->sputn(currentLine.data(), static_cast<streamsize>(currentLine.size()));
                    sink_->sputc('\n');
                    currentLine = indent + text;
                }
            }
        }

        if (not currentLine.empty())
            sink_->sputn(currentLine.data(), static_cast<streamsize>(currentLine.size()));

        lineBuffer_.clear();
    }
};

namespace {

// Get an OptionTable entry's name by its option code
string GetNameByOption(Option opt)
{
    auto result = find_if(OptionTable.begin(), OptionTable.end(), [opt](const OptionEntry & e) {return e.optCode == opt;});
    
    return (result != OptionTable.end() ? format("{}/{}", result->fullName, result->shortName) : format("(lookup of option code {} failed!)",
                                                                                                        static_cast<int>(opt)));
};

// Checks both the long and short name of an option against the string passed in
bool ArgNameMatchesOption(const string & arg, Option opt)
{
    auto result = find_if(OptionTable.begin(), OptionTable.end(), [arg, opt](const OptionEntry & e)
                                                                  {return (e.optCode == opt && (e.fullName == arg || e.shortName == arg));});
    return (result != OptionTable.end());
}

// Find the first element in a range of arguments that matches an option by either its long or short name
vector<string>::iterator FindOptionArg(vector<string>::iterator begin, vector<string>::iterator end, Option opt)
{
    auto optEntry = find_if(OptionTable.begin(), OptionTable.end(), [opt](const OptionEntry & e) {return e.optCode == opt;});
    if (optEntry == OptionTable.end())
        return end;
    return find_if(begin, end, [&optEntry](const string & s) {return s == optEntry->fullName || s == optEntry->shortName;});
}

// Find the first element in a range of arguments that matches any of the given options; sets matchedOpt to indicate which one was found
vector<string>::iterator FindOptionArg(vector<string>::iterator begin, vector<string>::iterator end,
                                       initializer_list<Option> opts, Option & matchedOpt)
{
    auto earliest = end;
    for (Option opt : opts)
    {
        auto it = FindOptionArg(begin, end, opt);
        if (it != end && (earliest == end || it < earliest))
        {
            earliest = it;
            matchedOpt = opt;
        }
    }
    return earliest;
}

// Get an OptionValueTable entry's help message by its requirements
string GetOptionValueUsageByOption(OptionEntry opt)
{
    auto result = find_if(OptionValueTable.begin(), OptionValueTable.end(), [opt](const OptionValueEntry & e)
                                                                            {return (e.oveQuan == opt.valQReq) && (e.oveType == opt.valTReq);});

    return (result != OptionValueTable.end() ? result->errorHelpText : format("(lookup of usage for quantity req {} and type req {} failed!)",
                                                                              static_cast<int>(opt.valQReq), static_cast<int>(opt.valTReq)));
}

// For when we need to re-init globals between executing lines of a batch file
void InitMain(void)
{
    Main::arguments.clear();
    Main::srcPaths.clear();
    Main::dstPath.clear();
    Main::destName.clear();
    Main::taskRequested = Option::Unset;
    Main::taskData.clear();
    Main::instanceFilter.ifActive = false;
    Main::instanceFilter.ifName = "";
    Main::instanceFilter.ifPartialMatch = false;
    Main::instanceFilter.ifCaseInsensitive = false;
    Main::instanceFilter.ifIndex1 = 0;
    Main::instanceFilter.ifIndex2 = 0;
    Main::instanceFilter.ifFilterValue = "";
    Main::instanceFilter.ifFilterSize = "";
    Main::listSettings.lsShowValues = false;
    Main::listSettings.lsShowOffsets = false;
    Main::listSettings.lsFilterField = "";
    Main::listSettings.lsShowWholeValueMatch = false;
    Main::listSettings.lsShowLinkers = YesNoOnly::No;
    Main::listSettings.lsShowLinkees = YesNoOnly::No;
    Main::listSettings.lsShowPlaceholders = YesNoOnly::Yes;
    Main::listSettings.lsShowUnnamed = YesNoOnly::Yes;
    Main::displayScale = -1;
    Main::overwritePolicy = nullopt;
    Main::sanitizePolicy = nullopt;
}

// Print brief listing of all accepted options
void PrintHelp(void)
{
    cout << "Kanabo is a tool for analyzing and manipulating data for the Oni game engine.\n";
    cout << "It examines, alters and repacks game resources in all known binary file formats.\n";
    cout << "Use '--help <option>' (without leading hyphens) for detailed help on any option.\n";
    cout << "You can also find the detailed documentation at https://wiki.oni2.net/Kanabo.\n";

    // Print options by help category
    for (auto thisHC = HelpCategoryEntryTable.begin(); thisHC != HelpCategoryEntryTable.end(); thisHC++)
    {
        bool printedCat = false;
        bool firstAfterCatName = true;

        // Find all options in this category
        for (auto thisOpt = OptionTable.begin(); thisOpt != OptionTable.end(); thisOpt++)
        {
            if (thisOpt->helpCat == thisHC->hceCat)
            {
                // Only print category name if we found a member in that category
                if (not printedCat)
                {
                    cout << "\n" << thisHC->hceName << "\n";
                    cout << thisHC->hceDesc << "\n";
                    printedCat = true;
                }

                // Print option name
                cout << (firstAfterCatName ? "" : "\n") << "   " << GetNameByOption(thisOpt->optCode) << " ";
                if (firstAfterCatName)
                    firstAfterCatName = false;

                // Find usage message that goes along with this option
                auto thisOV = OptionValueTable.begin();
                for (; thisOV != OptionValueTable.end(); thisOV++)
                {
                    if (thisOV->oveQuan == thisOpt->valQReq && thisOV->oveType == thisOpt->valTReq)
                    {
                        if (thisOV->oveType != OVT::Nothing)
                        {
#if WIN
                            // Substitute backward slashes for forward slashes in the sample paths
                            replace(thisOV->usageHelpText.begin(), thisOV->usageHelpText.end(), '/', '\\');
#endif
                            cout << thisOV->usageHelpText << "\n";
                        }
                        else
                            cout << '\n';
                        break;
                    }
                }
                if (thisOV == OptionValueTable.end())
                    cout << format("(lookup of help for quantity req {} and type req {} failed!)\n",
                                   static_cast<int>(thisOpt->valQReq), static_cast<int>(thisOpt->valTReq));

                // Print brief option description
                cout << "   " << thisOpt->shortHelp << "\n";
            }
        }
    }
}

// Print detailed help for a single option identified by name (without leading hyphens)
void PrintArgLongHelp(string_view argName)
{
    // Strip any accidental leading hyphens the user may have included
    while (not argName.empty() && argName.front() == '-')
        argName.remove_prefix(1);

    // Search for a matching option by full or short name
    auto thisOpt = OptionTable.end();
    for (auto it = OptionTable.begin(); it != OptionTable.end(); it++)
    {
        if (it->fullName  == "--" + string(argName) ||
            it->shortName == "-"  + string(argName))
        {
            thisOpt = it;
            break;
        }
    }

    if (thisOpt == OptionTable.end())
    {
        cerr << "Advisory: Unknown option " << quoted(string(argName)) << "; use '--help' with no option value to list all options.\n";
        return;
    }

    // Print option name line
    cout << "Printing detailed help for " << thisOpt->fullName << ".\n";
    cout << GetNameByOption(thisOpt->optCode) << " ";

    // Find and print the usage text for this option
    auto thisOV = OptionValueTable.begin();
    for (; thisOV != OptionValueTable.end(); thisOV++)
    {
        if (thisOV->oveQuan == thisOpt->valQReq && thisOV->oveType == thisOpt->valTReq)
        {
            if (thisOV->oveType != OVT::Nothing)
            {
#if WIN
                replace(thisOV->usageHelpText.begin(), thisOV->usageHelpText.end(), '/', '\\');
#endif
                cout << thisOV->usageHelpText << "\n";
            }
            else
                cout << '\n';
            break;
        }
    }
    if (thisOV == OptionValueTable.end())
        cout << format("(lookup of long help for quantity req {} and type req {} failed!)\n",
                       static_cast<int>(thisOpt->valQReq), static_cast<int>(thisOpt->valTReq));

    // Print full detail description
    cout << "   " << thisOpt->longHelp << "\n";
}

/************************ Argument Processing ************************/
// If a path or data packet supplied as an argument contains spaces, it may be recorded into our argument array in pieces (this is known to
// happen when reading arguments from a text file). Here we search for arguments that are pieces of a fragmented value and re-unify them. Values
// using either single/double quote marks or backslash-escaped spaces are accepted.
bool UnifySplitValues(void)
{
    bool usesQuotes = false;

    // Set up a few lambdas
    auto looksLikeOption = [](auto arg)
    {
        return (arg->front() == '-');
    };
    auto quoteAtStart = [](auto arg)
    {
        return arg->front() == '"' || arg->front() == '\'';
    };
    auto quoteAtEnd = [](auto arg)
    {
        return arg->back() == '"' || arg->back() == '\'';
    };
    auto backslashAtEnd = [](auto arg)
    {
        return arg->back() == '\\';
    };
    auto looksLikeStartOfSplitValue = [quoteAtStart, quoteAtEnd, backslashAtEnd, &usesQuotes](auto arg)
    {
        if (quoteAtStart(arg) && not quoteAtEnd(arg))
        {
            usesQuotes = true;
            return true;
        }
        else if (backslashAtEnd(arg))
        {
            usesQuotes = false;
            return true;
        }
        return false;
    };
    auto looksLikeEndOfSplitValue = [quoteAtEnd, backslashAtEnd, &usesQuotes](auto arg)
    {
        if (usesQuotes && quoteAtEnd(arg))
            return true;
        if (not usesQuotes && not backslashAtEnd(arg))
            return true;
        return false;
    };
    auto clearQuotesOrBackslashes = [&usesQuotes](auto arg)
    {
        if (usesQuotes)
        {
            arg->erase(0, 1);
            if (arg->size() >= 2)
                arg->erase(arg->length()-1);
        }
        else
        {
            size_t pos = 0;
            while ((pos = arg->find('\\', pos)) != string::npos)
                arg->erase(pos, 1);
        }
    };

    for (auto thisArg = Main::arguments.begin(); thisArg != Main::arguments.end(); thisArg++)
    {
        if (looksLikeStartOfSplitValue(thisArg))
        {
            // Scan ahead and merge the split value's pieces until we hit the last piece
            auto thisArg2 = next(thisArg);
            while(thisArg2 != Main::arguments.end())
            {
                if (looksLikeOption(thisArg2))
                {
                    cerr << "Error: Could not process arguments because this value did not end before another option was reached: "
                         << quoted(*thisArg2) << "\n";
                    return false;
                }
                
                // Tack on this fragment of the value, restoring the space that got eaten by argv[], then delete the fragment
                *thisArg = *thisArg + " " + *thisArg2;
                if (looksLikeEndOfSplitValue(thisArg2))
                {
                    Main::arguments.erase(thisArg2);
                    break;
                }
                else
                {
                    thisArg2 = Main::arguments.erase(thisArg2); // advances "thisArg2"
                    continue;
                }
            }

            clearQuotesOrBackslashes(thisArg);
        }
        // While we're here, we need to account for the possibility that the user passed in a path or data packet in quotes that did not need
        // them, and therefore it was never split into separate elements of argv[]. Although this isn't a fragmented path, we still have to
        // remove the quote marks.
        else if (quoteAtStart(thisArg) && quoteAtEnd(thisArg))
        {
            usesQuotes = true;
            clearQuotesOrBackslashes(thisArg);
        }
    }

    return true;
}

// Make the arguments ready to be iterated through, then use the incoming arguments to determine the mode we're supposed to run in
bool ProcessArgumentsAndSetMode(const char * argv[])
{
    // Move the args into a global vector
    for (int i = 0; argv[i] != nullptr; i++)
        Main::arguments.push_back(argv[i]);
    
    // If we have no arguments, program must have been opened with a double-click
    if (Main::arguments.empty())
    {
        Main::mode = RunMode::GUI;
        return true;
    }

    // Remove the first argument (program name) as it's not helpful from here on
    Main::arguments.erase(Main::arguments.begin());

    // Was anything passed in besides the program name?
    if (Main::arguments.empty())
    {
        cerr << "Advisory: No options received. Run Kanabo with the " << quoted(GetNameByOption(Option::Help)) << " option.\n";
        return false;
    }

    // Merge arguments that represent pieces of file paths into single elements
    if (not UnifySplitValues())
        return false;

    // This is a bit of a hack; we're cheating by running ahead of ProcessOptionsAndValues(). But we need to check for the version arg now so
    // that "taskRequested" can be set before PrintHeader() runs
    if (FindOptionArg(Main::arguments.begin(), Main::arguments.end(), Option::Version) != Main::arguments.end())
    {
        if (Main::arguments.size() != 1)
        {
            cerr << "Advisory: When asking for the version, you should not pass Kanabo any other arguments.\n";
            return false;
        }
        else // Main::arguments.size() == 1
        {
            Main::taskRequested = Option::Version;
            Main::mode = RunMode::CLI;
            return true;
        }
    }
    
    // Check for the batch option and save location of batch file
    auto batchArgIter = FindOptionArg(Main::arguments.begin(), Main::arguments.end(), Option::Batch);
    if (batchArgIter != Main::arguments.end())
    {
        auto batchValueIter = next(batchArgIter);
        if (batchValueIter == Main::arguments.end() || batchValueIter->front() == '-')
        {
            cerr << "Error: Did not receive a path to the batch file you want to run.\n";
            return false;
        }

        // Validate that the only other arguments present are at most one --alias <file> pair
        for (auto it = Main::arguments.begin(); it != Main::arguments.end(); it++)
        {
            if (it == batchArgIter || it == batchValueIter)
                continue;
            if (ArgNameMatchesOption(*it, Option::Alias))
            {
                auto aliasValueIter = next(it);
                if (aliasValueIter != Main::arguments.end() && aliasValueIter->front() != '-')
                {
                    it++; // skip the alias file value on the next iteration
                    continue;
                }
            }
            cerr << "Error: When using batch mode, you should only pass Kanabo the batch option, the path of the batch file you want to run, "
                    "and optionally the " << quoted(GetNameByOption(Option::Alias)) << " option with a path alias file.\n";
            return false;
        }

        Main::batchPath = *batchValueIter;
        // Remove the --batch <file> pair, leaving any --alias pair in place for LoadAliasFiles() to consume
        Main::arguments.erase(batchArgIter, next(batchValueIter));
        Main::mode = RunMode::Batch;
    }
    else
        Main::mode = RunMode::CLI;
    
    return true;
}

// Read the alias file supplied with the --alias argument and populate Main::aliases; remove the --alias pair from Main::arguments
bool LoadAliasFiles(void)
{
    auto argIter = FindOptionArg(Main::arguments.begin(), Main::arguments.end(), Option::Alias);
    if (argIter == Main::arguments.end())
        return true;

    auto nextArg = next(argIter);
    if (nextArg == Main::arguments.end())
        return true;

    const string & aliasFilePath = *nextArg;
    DiskItem aliasFile(aliasFilePath, ReadingMode::Text, ReportingMode::ErrorsOnly);
    if (aliasFile.opened())
    {
        string aliasLine{};
        int curLine = 0;
        while (aliasFile.nextLine(aliasLine))
        {
            curLine++;
            if (aliasLine.empty() || aliasLine.front() == '#')
                continue;

            size_t pos = aliasLine.find(' ');
            if (pos == string::npos)
            {
                cerr << "Error: Line " << curLine << " has no spaces. Each line in this file should contain an alias followed by a file path.\n";
                continue;
            }
            Main::aliases[aliasLine.substr(0, pos)] = aliasLine.substr(pos + 1);
        }
    }

    // Erase the --alias <file> pair
    Main::arguments.erase(argIter, next(nextArg));
    return true;
}

// Replace path token arguments with the paths specified in the alias list
bool ProcessAliasArguments(void)
{
    // In Batch mode, --alias is not permitted within batch file lines; it must be supplied on the outer command line
    if (Main::mode == RunMode::Batch)
    {
        if (FindOptionArg(Main::arguments.begin(), Main::arguments.end(), Option::Alias) != Main::arguments.end())
        {
            cerr << "Error: The " << quoted(GetNameByOption(Option::Alias)) << " option cannot be used inside a batch file. "
                    "Supply it on the command line alongside " << quoted(GetNameByOption(Option::Batch)) << " instead.\n";
            return false;
        }
    }

    // Check arguments for paths starting with the path token and replace them with the matching alias
    for (auto thisArg = Main::arguments.begin(); thisArg != Main::arguments.end(); thisArg++)
    {
        if (thisArg->front() == '@')
        {
            if (Main::aliases.empty())
            {
                cerr << "Error: You supplied a path token, " << quoted(*thisArg) << ", but did not supply a path alias file with the "
                     << quoted(GetNameByOption(Option::Alias)) << " option.\n";
                return false;
            }

            // Copy token name without path token
            string token = thisArg->substr(1);

            // Check if the token ends in one or more digits, which indicates a level number suffix (e.g. "win8" → alias "win" + level 8).
            // find_if_not scans from the end; .base() gives a forward iterator to the start of the digit run.
            auto digitStart = find_if_not(token.rbegin(), token.rend(),
                                          [](unsigned char c){return isdigit(c);}).base();
            bool hasLevelSuffix = (digitStart != token.end()); // true when there is at least one trailing digit

            if (hasLevelSuffix && digitStart != token.begin()) // baseName must be non-empty
            {
                string baseName    = token.substr(0, static_cast<size_t>(digitStart - token.begin()));
                string levelNumStr = token.substr(static_cast<size_t>(digitStart - token.begin()));

                // Look up the base alias name (without the level number)
                auto baseResult = Main::aliases.find(baseName);
                if (baseResult == Main::aliases.end())
                {
                    cerr << "Error: You supplied a path token, " << quoted(*thisArg) << ", but the alias " << quoted(baseName)
                         << " derived from it was not found in the supplied path alias file.\n";
                    return false;
                }

                // Strip any trailing path separators from the alias path so the leaf name check works correctly
                string aliasPath = baseResult->second;
                while (not aliasPath.empty() && (aliasPath.back() == '/' || aliasPath.back() == '\\'))
                    aliasPath.pop_back();

                // Extract the leaf folder name
                size_t lastSep = aliasPath.find_last_of("/\\");
                string leafName = (lastSep != string::npos) ? aliasPath.substr(lastSep + 1) : aliasPath;

                if (leafName == "GameDataFolder")
                {
                    // Construct the level data file path: <GameDataFolder>/level<N>_Final.dat
#if MAC
                    *thisArg = aliasPath + "/level" + levelNumStr + "_Final." + kFileSuffix_LevelFile32;
#elif WIN
                    *thisArg = aliasPath + "\\level" + levelNumStr + "_Final." + kFileSuffix_LevelFile32;
#endif
                }
                else if (GameDataManager::isPS2Directory(aliasPath))
                {
                    // For a PS2 directory, look up the virtual level file name and resolve it to an actual disk path
                    auto ps2Result = GameDataManager::findPS2LevelFile(aliasPath, levelNumStr);
                    if (not ps2Result.has_value())
                    {
                        cerr << "Error: You supplied a path token, " << quoted(*thisArg) << ", but level " << levelNumStr
                             << " could not be found in the PS2 directory pointed to by alias " << quoted(baseName) << ".\n";
                        return false;
                    }
                    *thisArg = ps2Result.value();
                }
                else
                {
                    cerr << "Error: You supplied a path token, " << quoted(*thisArg) << ", but the alias " << quoted(baseName) << " does not "
                            "point to a GameDataFolder directory. Folder expansion by appending a level number to an alias name is only "
                            "supported for aliases that point to a GameDataFolder.\n";
                    return false;
                }
            }
            else
            {
                // No level number suffix: perform an exact alias lookup
                auto result = Main::aliases.find(token);
                if (result == Main::aliases.end())
                {
                    cerr << "Error: You supplied a path token, " << quoted(*thisArg) << ", but it was not found in the supplied path alias "
                            "file.\n";
                    return false;
                }

                // Replace token argument with actual path
                *thisArg = result->second;
            }
        }
    }

    return true;
}

// Make sure no option was supplied more than once (must run before any pipeline step that erases arguments)
bool CheckForDuplicateOptions(void)
{
    for (auto thisOpt = OptionTable.begin(); thisOpt != OptionTable.end(); thisOpt++)
    {
        if (thisOpt->optCode >= Option::OnceLine_)
            continue;

        int numFound = static_cast<int>(count(Main::arguments.begin(), Main::arguments.end(), thisOpt->fullName));
        numFound += static_cast<int>(count(Main::arguments.begin(), Main::arguments.end(), thisOpt->shortName));
        if (numFound > 1)
        {
            cerr << "Error: The option " << quoted(GetNameByOption(thisOpt->optCode)) << " was passed more than once.\n";
            return false;
        }
    }

    return true;
}

// Check for any argument with a non-zero "goesWith" value and make sure at least one of the required companion options is also present
bool ValidateCompanionArguments(void)
{
    for (const auto & arg : Main::arguments)
    {
        // Look up this argument in the option table
        auto thisOpt = find_if(OptionTable.begin(), OptionTable.end(),
                               [&arg](const OptionEntry & e){return e.fullName == arg || e.shortName == arg;});
        if (thisOpt == OptionTable.end())
            continue;
        if (thisOpt->goesWith == static_cast<uint64_t>(Option::Unset))
            continue;

        // At least one companion option must be present
        bool companionFound = false;
        for (const auto & companionOpt : OptionTable)
        {
            if ((thisOpt->goesWith & static_cast<uint64_t>(companionOpt.optCode)) != 0)
            {
                if (FindOptionArg(Main::arguments.begin(), Main::arguments.end(), companionOpt.optCode) != Main::arguments.end())
                {
                    companionFound = true;
                    break;
                }
            }
        }
        if (not companionFound)
        {
            vector<string> companions;
            for (const auto & companionOpt : OptionTable)
            {
                if ((thisOpt->goesWith & static_cast<uint64_t>(companionOpt.optCode)) != 0)
                    companions.push_back(GetNameByOption(companionOpt.optCode));
            }
            cerr << "Error: The option " << quoted(GetNameByOption(thisOpt->optCode)) << " can only be used together with ";
            for (auto it = companions.begin(); it != companions.end(); it++)
            {
                cerr << quoted(*it);
                
                if (next(it) != companions.end())
                {
                    if (next(next(it)) != companions.end())
                        cerr << ", ";
                    else
                        cerr << " or ";
                }
            }
            cerr << ".\n";
            return false;
        }
    }

    return true;
}

// Check for any filter arguments and save them in our filter global for passing to GameData
bool ProcessFilterArguments(void)
{
    // Returns true if the string is non-empty, contains only digits, and should fit within a 32-bit integer
    const int kMaxDigitsInInt = 9; // cuts off values ≥ 1 billion but we don't care
    auto isValidIndexStr = [](const string & s)
    {
        return not s.empty() && s.size() <= kMaxDigitsInInt &&
               find_if(s.begin(), s.end(), [](unsigned char c){return not isdigit(c);}) == s.end();
    };

    auto argIter = Main::arguments.begin();
    Option matchedOpt = Option::Unset;
    while ((argIter = FindOptionArg(argIter, Main::arguments.end(), {Option::FilterName, Option::FilterIndex, Option::FilterTag,
                                                                     Option::FilterNamePartial, Option::FilterCaseInsens}, matchedOpt))
           != Main::arguments.end())
    {
        if (matchedOpt == Option::FilterNamePartial)
        {
            Main::instanceFilter.ifPartialMatch = true;
            argIter = Main::arguments.erase(argIter);
            continue;
        }
        if (matchedOpt == Option::FilterCaseInsens)
        {
            Main::instanceFilter.ifCaseInsensitive = true;
            argIter = Main::arguments.erase(argIter);
            continue;
        }

        // All remaining options require a value argument
        auto nextArg = next(argIter);
        if (nextArg == Main::arguments.end())
            break;

        if (matchedOpt == Option::FilterName)
        {
            Main::instanceFilter.ifName = *nextArg;
            Main::instanceFilter.ifActive = true;
        }
        else if (matchedOpt == Option::FilterTag)
        {
            Main::instanceFilter.ifTag = *nextArg;
            Main::instanceFilter.ifActive = true;
        }
        else // Option::FilterIndex
        {
            const string & val = *nextArg;
            size_t hyphenPos = val.find('-');

            if (hyphenPos == 0)
            {
                // Hyphen at the start means a negative number or a missing start index for a range
                cerr << "Error: The value " << quoted(val) << " passed to " << quoted(GetNameByOption(Option::FilterIndex))
                     << " is not valid. Negative numbers are not accepted; if supplying a range, make sure a start index precedes the hyphen.\n";
                return false;
            }
            else if (hyphenPos != string::npos)
            {
                // Range value, e.g. "100-110"
                string part1 = val.substr(0, hyphenPos);
                string part2 = val.substr(hyphenPos + 1);

                if (not isValidIndexStr(part1) || not isValidIndexStr(part2))
                {
                    cerr << "Error: The value " << quoted(val) << " passed to " << quoted(GetNameByOption(Option::FilterIndex))
                         << " is not a valid range. Please supply a range of non-negative integers separated by a hyphen, e.g. \"100-110\".\n";
                    return false;
                }

                int index1 = stoi(part1);
                int index2 = stoi(part2);

                if (index2 < index1)
                {
                    cerr << "Error: The range " << quoted(val) << " passed to " << quoted(GetNameByOption(Option::FilterIndex))
                         << " is not valid because the end index is lower than the start index.\n";
                    return false;
                }

                Main::instanceFilter.ifIndex1 = index1;
                Main::instanceFilter.ifIndex2 = index2;
                Main::instanceFilter.ifActive = true;
            }
            else // received single number
            {
                if (not isValidIndexStr(val))
                {
                    cerr << "Error: The value " << quoted(val) << " passed to " << quoted(GetNameByOption(Option::FilterIndex))
                         << " is not a valid index. Please supply a non-negative integer or a range of integers separated by a hyphen, e.g. "
                            "\"100-110\".\n";
                    return false;
                }

                Main::instanceFilter.ifIndex1 = stoi(val);
                Main::instanceFilter.ifIndex2 = Main::instanceFilter.ifIndex1;
                Main::instanceFilter.ifActive = true;
            }
        }

        // Erase the option and its value argument
        argIter = Main::arguments.erase(argIter, next(nextArg));
    }

    return true;
}

// Check for any list argument modifiers and save them in our list settings global for passing to GameData
bool ProcessListSettings(void)
{
    map<string, YesNoOnly> yesNoOnlyMap =
    {
        {"yes",  YesNoOnly::Yes},
        {"no",   YesNoOnly::No},
        {"only", YesNoOnly::Only}
    };

    auto argIter = Main::arguments.begin();
    Option matchedOpt = Option::Unset;
    while ((argIter = FindOptionArg(argIter, Main::arguments.end(), {Option::ListFields, Option::ShowFieldOffsets, Option::ShowLinkers,
                                                                     Option::ShowLinkees, Option::ShowPlaceholders, Option::ShowUnnamed,
                                                                     Option::ShowOrphans, Option::FilterField, Option::FilterValue,
                                                                     Option::FilterSize, Option::FilterValueWhole},
                                    matchedOpt)) != Main::arguments.end())
    {
        if (matchedOpt == Option::ListFields)
            Main::listSettings.lsShowValues = true;
        else if (matchedOpt == Option::ShowFieldOffsets)
            Main::listSettings.lsShowOffsets = true;
        else if (matchedOpt == Option::ShowPlaceholders || matchedOpt == Option::ShowUnnamed || matchedOpt == Option::ShowOrphans
                 || matchedOpt == Option::ShowLinkers || matchedOpt == Option::ShowLinkees)
        {
            auto nextArg = next(argIter);
            if (nextArg == Main::arguments.end())
                break;
            const string & val = *nextArg;
            auto mapLookup = yesNoOnlyMap.find(val);
            if (mapLookup == yesNoOnlyMap.end())
            {
                cerr << "Error: The value " << quoted(val) << " passed to " << quoted(GetNameByOption(matchedOpt))
                     << " is not valid. Use \"yes\", \"no\", or \"only\".\n";
                return false;
            }
            if (matchedOpt == Option::ShowPlaceholders)
                Main::listSettings.lsShowPlaceholders = mapLookup->second;
            else if (matchedOpt == Option::ShowUnnamed)
                Main::listSettings.lsShowUnnamed = mapLookup->second;
            else if (matchedOpt == Option::ShowOrphans)
                Main::listSettings.lsShowOrphans = mapLookup->second;
            else if (matchedOpt == Option::ShowLinkers)
                Main::listSettings.lsShowLinkers = mapLookup->second;
            else
                Main::listSettings.lsShowLinkees = mapLookup->second;
            argIter = Main::arguments.erase(argIter, next(nextArg));
            continue;
        }
        else if (matchedOpt == Option::FilterField || matchedOpt == Option::FilterValue || matchedOpt == Option::FilterSize)
        {
            auto nextArg = next(argIter);
            if (nextArg == Main::arguments.end())
                break;
            if (matchedOpt == Option::FilterField)
                Main::listSettings.lsFilterField = *nextArg;
            else if (matchedOpt == Option::FilterValue)
            {
                Main::instanceFilter.ifFilterValue = *nextArg;
                Main::instanceFilter.ifActive = true;
            }
            else
            {
                Main::instanceFilter.ifFilterSize = *nextArg;
                Main::instanceFilter.ifActive = true;
            }
            argIter = Main::arguments.erase(argIter, next(nextArg));
            continue;
        }
        else if (matchedOpt == Option::FilterValueWhole)
            Main::listSettings.lsShowWholeValueMatch = true;
        else
            return false;
        
        argIter = Main::arguments.erase(argIter);
    }

    return true;
}

// Helper function to detect display scale factor (Retina support on macOS)
int DetectDisplayScale(void)
{
#if MAC
    FILE * pipe = popen("system_profiler SPDisplaysDataType 2>/dev/null | grep -i 'retina' | wc -l", "r");
    if (pipe)
    {
        char buffer[128];
        if (fgets(buffer, sizeof(buffer), pipe) != nullptr)
        {
            pclose(pipe);
            // Validate buffer contains at least one digit before converting, since stoi() throws if it finds none
            const char * p = buffer;
            while (*p == ' ' || *p == '\t') p++; // skip leading whitespace
            if (isdigit(static_cast<unsigned char>(*p)))
            {
                int retinaCount = stoi(buffer);
                if (retinaCount > 0)
                    return 2; // assume 2x scale factor for Retina display
            }
        }
        else
            pclose(pipe);
    }
    return 1;
#elif WIN
    UINT dpi = GetDpiForSystem();
    return static_cast<int>((dpi + 48) / 96); // +48 rounds to nearest integer (half of 96), avoiding need to include <cmath> for round()
#endif
}

// Detect which inline image display method the current terminal supports, if any
TerminalImageSupport DetectTerminalImageSupport(void)
{
#if MAC
    // Check if running in kitty by looking for environment variables that it sets
    // This is the primary detection method as it's reliable and has no side effects
    const char * kittyWindowId = getenv("KITTY_WINDOW_ID");
    if (kittyWindowId && kittyWindowId[0] != '\0')
        return TerminalImageSupport::Kitty;

    // Alternately, check for kitty installation directory
    const char * kittyInstallDir = getenv("KITTY_INSTALLATION_DIR");
    if (kittyInstallDir && kittyInstallDir[0] != '\0')
        return TerminalImageSupport::Kitty;

    // Alternately, check for kitty in COLORTERM (some kitty configurations set this)
    const char * colorterm = getenv("COLORTERM");
    if (colorterm && string(colorterm).find("kitty") != string::npos)
        return TerminalImageSupport::Kitty;

    return TerminalImageSupport::None;
#elif WIN
    // The kitty graphics protocol uses APC escape sequences, which Windows ConPTY strips before they
    // reach the terminal emulator, so kitty detection is not attempted on Windows.
    // Check for WezTerm, which supports inline display via its imgcat subcommand (bypasses ConPTY).
    // Uses getenv_s (C11 secure version) to avoid MSVC deprecation warnings.
    auto envSet = [](const char * name) -> bool {
        size_t len = 0;
        getenv_s(&len, nullptr, 0, name);
        return len > 1; // len includes null terminator; >1 means value is non-empty
    };

    if (envSet("WEZTERM_EXECUTABLE"))
        return TerminalImageSupport::WezTerm;

    // TERM_PROGRAM is set to "WezTerm" by WezTerm; check its value explicitly
    size_t len = 0;
    getenv_s(&len, nullptr, 0, "TERM_PROGRAM");
    if (len > 1)
    {
        string termProgram(len - 1, '\0');
        getenv_s(&len, termProgram.data(), len, "TERM_PROGRAM");
        if (termProgram == "WezTerm")
            return TerminalImageSupport::WezTerm;
    }

    return TerminalImageSupport::None;
#endif
}

// Process argument requesting scaling of instance to be displayed
bool ProcessDisplayScaleArgument(void)
{
    auto argIter = Main::arguments.begin();
    while ((argIter = FindOptionArg(argIter, Main::arguments.end(), Option::DisplayScale)) != Main::arguments.end())
    {
        auto nextArg = next(argIter);

        if (nextArg == Main::arguments.end())
            break;

        const string & scaleStr = *nextArg;
        int scale = 0, kScaleSafety = 4;
        auto [ptr, ec] = from_chars(scaleStr.data(), scaleStr.data() + scaleStr.size(), scale);
        if (ec != errc{} || ptr != scaleStr.data() + scaleStr.size() || scale <= 0)
        {
            cerr << "Error: Display scale must be a positive integer, but the value " << quoted(scaleStr) << " was received.\n";
            return false;
        }
        if (scale > kScaleSafety)
        {
            cerr << "Error: Display scale exceeded safety value of " << kScaleSafety << ".\n";
            return false;
        }
        Main::displayScale = scale;

        // Erase display scale arguments
        argIter = Main::arguments.erase(argIter, next(nextArg));
    }

    return true;
}

// Process argument setting the file collision policy for export operations
bool ProcessOverwritePolicyArgument(void)
{
    auto argIter = FindOptionArg(Main::arguments.begin(), Main::arguments.end(), Option::OverwritePolicy);
    if (argIter == Main::arguments.end())
        return true;

    auto nextArg = next(argIter);
    if (nextArg == Main::arguments.end() || nextArg->front() == '-')
    {
        cerr << "Error: The overwrite policy option requires a value of \"overwrite\" (\"o\" for short), \"skip\" (\"s\"), or \"unique\" "
                "(\"u\").\n";
        return false;
    }

    const string & policyStr = *nextArg;
    if (policyStr == "o" || policyStr == "overwrite")
        Main::overwritePolicy = OverwritePolicy::AutoOverwrite;
    else if (policyStr == "u" || policyStr == "unique")
        Main::overwritePolicy = OverwritePolicy::AutoUniquify;
    else if (policyStr == "s" || policyStr == "skip")
        Main::overwritePolicy = OverwritePolicy::AutoCancel;
    else
    {
        cerr << "Error: The value " << quoted(policyStr)
             << " is not a valid overwrite policy. Use \"overwrite\" (\"o\" for short), \"skip\" (\"s\"), or \"unique\" (\"u\").\n";
        return false;
    }

    Main::arguments.erase(argIter, next(nextArg));
    return true;
}

bool ProcessSanitizePolicyArgument(void)
{
    auto argIter = FindOptionArg(Main::arguments.begin(), Main::arguments.end(), Option::SanitizePolicy);
    if (argIter == Main::arguments.end())
        return true;

    auto nextArg = next(argIter);
    if (nextArg == Main::arguments.end() || nextArg->front() == '-')
    {
        cerr << "Error: The sanitize policy option requires a value of \"unicode\" (\"u\" for short) or \"html\" (\"h\").\n";
        return false;
    }

    const string & policyStr = *nextArg;
    if (policyStr == "u" || policyStr == "unicode")
        Main::sanitizePolicy = SanitizePolicy::Unicode;
    else if (policyStr == "h" || policyStr == "html")
        Main::sanitizePolicy = SanitizePolicy::Html;
    else
    {
        cerr << "Error: The value " << quoted(policyStr) << " is not a valid sanitize policy. Use \"unicode\" (\"u\" for short) or \"html\" "
                "(\"h\").\n";
        return false;
    }

    Main::arguments.erase(argIter, next(nextArg));
    return true;
}

// Welcome the user to our program
bool PrintHeader(void)
{
    // If the user only asked for the version to be printed, HandleTask() will take care of that, so this function is unneeded
    if (Main::taskRequested == Option::Version)
        return true;

    time_t curTime = time({});
    
    if (curTime == -1)
    {
        cerr << "Error: Failed to obtain the current time.\n";
        return false;
    }
    
    char timeStr[26] = {}; // "yyyy-mm-dd hh:mm:ss a.m." + 1
    tm localTime = {};
#if MAC
    void * localTimePtr = localtime_r(&curTime, &localTime);
    errno_t result = (localTimePtr == NULL);
#elif WIN
    errno_t result = localtime_s(&localTime, &curTime);
#endif
    if (result)
    {
        cerr << "Error: Failed to obtain the local time.\n";
        return false;
    }
    
    size_t result2 = strftime(timeStr, sizeof(timeStr), "%F %r", &localTime);

    if (not result2 || not strlen(timeStr))
    {
        cerr << "Error: Failed to convert the time.\n";
        return false;
    }

    cout << "--Kanabo v" << kAppVer << "--\n";
    cout << "Session start: " << timeStr << "\n";

    return true;
}

// Validate and record all launch arguments
bool ProcessOptionsAndValues(void)
{
    // Make sure no task was requested more than once (duplicate options are already caught by CheckForDuplicateOptions())
    vector<Option> tasksRequested;
    for (auto thisOpt = OptionTable.begin(); thisOpt != OptionTable.end(); thisOpt++)
    {
        if (thisOpt->optCode < Option::TaskLine_)
            continue;

        int numFound = static_cast<int>(count(Main::arguments.begin(), Main::arguments.end(), thisOpt->fullName));
        numFound += static_cast<int>(count(Main::arguments.begin(), Main::arguments.end(), thisOpt->shortName));
        if (numFound > 0)
            tasksRequested.push_back(thisOpt->optCode);
    }
    
    // Make sure only one task was asked for
    if (tasksRequested.size() > 1)
    {
        cerr << "Error: You requested " << tasksRequested.size() << " different tasks with the following arguments: ";
        for (auto task = tasksRequested.begin(); task != tasksRequested.end(); task++)
            cerr << GetNameByOption(*task) << (next(task) != tasksRequested.end() ? ", " : ". ");
        cerr << "Error: Only one task can be requested in a single invocation of Kanabo unless you use the batch script task to pass a list of "
                "tasks in a text file.\n";
        return false;
    }

    // Iterate through arguments
    for (auto thisArg = Main::arguments.begin(); thisArg != Main::arguments.end(); thisArg++)
    {
        auto nextArgIsValue = [&thisArg]
        {
            if (next(thisArg) != Main::arguments.end())
                return (next(thisArg)->front() != '-'); // if the arg does not start with "-", we'll assume it's a value, not an option
            else
                return false;
        };
        auto nextNextArgIsValue = [&thisArg]
        {
            if (next(thisArg) != Main::arguments.end() && next(next(thisArg)) != Main::arguments.end())
                return (next(next(thisArg))->front() != '-');
            else
                return false;
        };
        
        // Validate arguments according to usage specified in OptionTable[], and if they pass, record them in Main
        auto thisOpt = OptionTable.begin();
        for (; thisOpt != OptionTable.end(); thisOpt++)
        {
            auto saveOptionValue = [&thisArg, &thisOpt]
            {
                switch (thisOpt->optCode)
                {
                    case Option::Destination:
                    Main::dstPath = *thisArg;
                    break;

                    case Option::DestName:
                    Main::destName = *thisArg;
                    break;

                    case Option::Source:
                    Main::srcPaths.push_back(*thisArg);
                    break;

                    case Option::Help:
                    default:
                    Main::taskData.push_back(*thisArg);
                    break;
                }
            };
            
            if (ArgNameMatchesOption(*thisArg, thisOpt->optCode))
            {
                // Don't advance past here if we got the incorrect number of values for this option
                if (thisOpt->valQReq == OVQ::None && nextArgIsValue())
                {
                    cerr << "Error: You passed a value to the option " << quoted(GetNameByOption(thisOpt->optCode)) << " but it takes no "
                            "value.\n";
                    return false;
                }
                else if (thisOpt->valQReq >= OVQ::One && not nextArgIsValue())
                {
                    cerr << "Error: You didn't pass a value to the option " << quoted(GetNameByOption(thisOpt->optCode)) << " but it requires "
                         << GetOptionValueUsageByOption(*thisOpt) << ".\n";
                    return false;
                }
                else if (thisOpt->valQReq == OVQ::One && nextArgIsValue() && nextNextArgIsValue())
                {
                    cerr << "Error: You passed multiple values to the option " << quoted(GetNameByOption(thisOpt->optCode))
                         << " but it requires " << GetOptionValueUsageByOption(*thisOpt) << ".\n";
                    return false;
                }
                
                // Save values passed in for this option
                if (thisOpt->valQReq == OVQ::ZeroOrOne || thisOpt->valQReq == OVQ::One)
                {
                    if (nextArgIsValue())
                    {
                        advance(thisArg, 1);
                        saveOptionValue();
                    }
                }
                else if (thisOpt->valQReq == OVQ::Some)
                {
                    while (nextArgIsValue())
                    {
                        advance(thisArg, 1);
                        saveOptionValue();
                    }
                }
                
                // Record task that this option calls for (if any)
                if (thisOpt->optCode > Option::TaskLine_)
                    Main::taskRequested = thisOpt->optCode;
                
                break;
            }
        }
        
        if (thisOpt == OptionTable.end())
        {
            cerr << "Error: Unrecognized option " << quoted(*thisArg) << ". Exiting.\n";
            return false;
        }
    }
    
    return true;
}

// Perform pre-flight checks to make sure the user provided the data and arguments that the chosen task requires
bool ValidateTaskRequirements(void)
{
    // Set up a few lambdas
    auto noDest = []
    {
        if (Main::dstPath.empty())
        {
            cerr << "Error: No destination path was passed in. You need to supply a path to a file/folder with "
                 << quoted(GetNameByOption(Option::Destination)) << " in order to use the "
                 << quoted(GetNameByOption(Main::taskRequested)) << " option.\n";
            if (Main::mode != RunMode::CLI)
                cerr << "Error: Normally Kanabo will use the working directory as your default destination path if you don't specify one, but "
                        "you are running in Batch mode so the destination needs to be specified on each command line within your batch file.\n";
            return true;
        }
        else return false;
    };
    auto noSource = []
    {
        if (Main::srcPaths.empty())
        {
            cerr << "Error: No source paths were passed in. You need to supply one or more paths to files/folders with "
                 << quoted(GetNameByOption(Option::Source)) << " in order to use the "
                 << quoted(GetNameByOption(Main::taskRequested)) << " option.\n";
            return true;
        }
        return false;
    };
    auto sIfPlural = [](int n)
    {
        if (n != 1)
            return "s";
        else
            return "";
    };
    auto noTaskData = []
    {
        if (Main::taskData.empty())
        {
            cerr << "Error: No task data was passed in. You need to supply at least one option to the "
                 << quoted(GetNameByOption(Main::taskRequested)) << " option.\n";
            return true;
        }
        return false;
    };
    auto notTaskDataCount = [sIfPlural](int n)
    {
        int values = static_cast<int>(Main::taskData.size());
        if (values != n)
        {
            cerr << "Error: You passed " << values << " value" << sIfPlural(values) << " to the "
                 << quoted(GetNameByOption(Main::taskRequested)) << " option, but it only takes " << n << " value" << sIfPlural(n) << ".\n";
            return true;
        }
        return false;
    };

    // In CLI mode, set the destination to the working directory if the user didn't specify one; in Batch mode the working directory is
    // ambiguous so we leave the requirement of explicitly specifying a destination in place
    bool userProvidedDest = not Main::dstPath.empty();
    if (Main::mode == RunMode::CLI)
    {
        if (Main::dstPath.empty())
            Main::dstPath = ".";
    }
    
    // Look up I/O requirements for this task
    IOReq reqs = IOReq::None;
    OVQ quan = OVQ::None;
    for (auto thisOpt = OptionTable.begin(); thisOpt != OptionTable.end(); thisOpt++)
    {
        if (thisOpt->optCode == Main::taskRequested)
        {
            reqs = thisOpt->ioReq;
            quan = thisOpt->valQReq;
            break;
        }
    }

    // Reject the command if any I/O argument was supplied that the task doesn't require, since this likely indicates user confusion
    if (not Main::srcPaths.empty() && not (static_cast<int>(reqs) & static_cast<int>(IOReq::Source)))
    {
        cerr << "Error: You supplied a source, but the " << quoted(GetNameByOption(Main::taskRequested)) << " option does not use a source.\n";
        return false;
    }
    if (userProvidedDest && not (static_cast<int>(reqs) & static_cast<int>(IOReq::Destination)))
    {
        cerr << "Error: You supplied a destination, but the " << quoted(GetNameByOption(Main::taskRequested))
             << " option does not use a destination.\n";
        return false;
    }

    // Make sure I/O requirements are met
    if (static_cast<int>(reqs) & static_cast<int>(IOReq::Source))
    {
        if (noSource()) return false;
    }
    if (static_cast<int>(reqs) & static_cast<int>(IOReq::Destination))
    {
        if (noDest()) return false;
    }
    if (static_cast<int>(reqs) & static_cast<int>(IOReq::TaskData))
    {
        if (quan == OVQ::One)
        {
            if (notTaskDataCount(1)) return false;
        }
        else if (quan == OVQ::Some)
        {
            if (noTaskData()) return false;
        }
    }

    // Require a filter to be used if the task is in the MustFilter group; note that GDM may have further requirements, such as a filter being
    // required with the "list instances" operation but only when the "list fields" option is also turned on
    if (static_cast<uint64_t>(Main::taskRequested) & static_cast<uint64_t>(Option::MustFilter))
    {
        if (not Main::instanceFilter.ifActive)
        {
            cerr << "Error: When using " << quoted(GetNameByOption(Main::taskRequested)) << ", you must supply at least one option from the "
                    "filter category to limit the output.\n";
            return false;
        }
    }

    // Ensure "show linkers" and "show linkees" are not used together
    if (Main::listSettings.lsShowLinkers != YesNoOnly::No && Main::listSettings.lsShowLinkees != YesNoOnly::No)
    {
        cerr << quoted(GetNameByOption(Option::ShowLinkers)) << " and " << quoted(GetNameByOption(Option::ShowLinkees))
             << " cannot be used together.\n";
        return false;
    }

    // Ensure "show orphans" is not used with "show linkers" or "show linkees"
    if (Main::listSettings.lsShowOrphans != YesNoOnly::No)
    {
        if (Main::listSettings.lsShowLinkers != YesNoOnly::No)
        {
            cerr << quoted(GetNameByOption(Option::ShowOrphans)) << " cannot be used together with "
                 << quoted(GetNameByOption(Option::ShowLinkers)) << ".\n";
            return false;
        }
        if (Main::listSettings.lsShowLinkees != YesNoOnly::No)
        {
            cerr << quoted(GetNameByOption(Option::ShowOrphans)) << " cannot be used together with "
                 << quoted(GetNameByOption(Option::ShowLinkees)) << ".\n";
            return false;
        }
    }

    // Require a filter to be active when the "show linkers" option is used
    if (Main::listSettings.lsShowLinkers != YesNoOnly::No && not Main::instanceFilter.ifActive)
    {
        cerr << quoted(GetNameByOption(Option::ShowLinkers)) << " requires at least one filter option to be supplied.\n";
        return false;
    }

    // Require a filter to be active when the "show linkees" option is used
    if (Main::listSettings.lsShowLinkees != YesNoOnly::No && not Main::instanceFilter.ifActive)
    {
        cerr << quoted(GetNameByOption(Option::ShowLinkees)) << " requires at least one filter option to be supplied.\n";
        return false;
    }
    
    return true;
}

// Pass the user's requested task to GameDataManager or handle it here if GDM is unneeded
bool HandleTask(void)
{
    // Prepare system info
    SystemInfo sysInfo = {DetectTerminalImageSupport(), Main::displayScale};
    if (sysInfo.displayScale < 1)
        sysInfo.displayScale = DetectDisplayScale(); // auto-detect if not manually specified

    // Prepare overwrite policy, which DiskItem enforces program-wide for every file it writes
    OverwritePolicy overwritePolicy;
    if (Main::overwritePolicy.has_value())
        overwritePolicy = *Main::overwritePolicy;
    else if (Main::mode == RunMode::CLI)
        overwritePolicy = OverwritePolicy::Ask;
    else // we're in Batch mode so just assume we shouldn't overwrite
        overwritePolicy = OverwritePolicy::AutoCancel;
    DiskItem::setOverwritePolicy(overwritePolicy);

    // Prepare sanitize policy, which DiskItem applies when sanitizing file name stems
    DiskItem::setSanitizePolicy(Main::sanitizePolicy.value_or(SanitizePolicy::Unicode));

    // Determine where we tell GameData (through GameDataManager) to stop loading the file, which is a safety measure in case something is
    // breaking the next step of the load process and we want to be able to get limited information about the file
    int stopAfter = LoadPhase::P9_Done;
    if (Main::taskRequested == Option::Info)
        stopAfter = LoadPhase::P3_FileIdentified;
    else if (Main::taskRequested == Option::ListTables || Main::taskRequested == Option::ListTemplates)
        stopAfter = LoadPhase::P6_TemplateDescriptorsParsed;

    // Spin up a game data manager and open all the files and/or folders of files the user passed in
    GameDataManager manager(sysInfo);
    if (Main::taskRequested > Option::FileLine_)
    {
        for (const string & thePath : Main::srcPaths)
        {
            DiskItem pathItem(thePath);
            if (pathItem.isDir())
            {
                if (GameDataManager::isPS2Directory(thePath))
                {
                    for (const string & ps2File : GameDataManager::enumeratePS2DataFiles(thePath))
                        manager.openFile(ps2File, stopAfter);
                }
                else
                {
                    for (const string & child : pathItem.enumerateChildren())
                    {
                        DiskItem childItem(child);
                        if (childItem.isFile() && childItem.suffix() == kFileSuffix_LevelFile32)
                            manager.openFile(child, stopAfter);
                    }
                }
            }
            else
                manager.openFile(thePath, stopAfter);
        }
    }

    // Handle requested task
    switch (Main::taskRequested)
    {
        case Option::Help:
        if (Main::taskData.empty())
            PrintHelp();
        else
            PrintArgLongHelp(Main::taskData.front());
        break;

        case Option::Version:
        cout << "Kanabo v" << kAppVer << "\n";
        break;

        case Option::Unset:
        cerr << "Advisory: Didn't receive a task option to act upon. Run Kanabo with the --help option to learn about available tasks.\n";
        return false;
        
        case Option::Export:
        {
            const string & fmt = Main::taskData[0];
            if (fmt == "onix")
                manager.doOperation(Main::dstPath, Main::destName, Operation::ExportBinary, Main::instanceFilter, Main::listSettings);
            else if (fmt == "png")
                manager.doOperation(Main::dstPath, Main::destName, Operation::ExportGraphics, Main::instanceFilter, Main::listSettings);
            else
            {
                cerr << "Error: Unrecognized export format " << quoted(fmt) << ". Supported formats are \"onix\" and \"png\".\n";
                return false;
            }
            break;
        }

        default: // send all other Options to GDM as Operations
        auto entry = find_if(OptionTable.begin(), OptionTable.end(),
                             [](const OptionEntry & e){return e.optCode == Main::taskRequested;});
        if (entry == OptionTable.end()) // shouldn't be possible as "taskRequested" can only be set to a value from "OptionTable"
        {
            cerr << "Error: Requested task not found in option table.\n";
            return false;
        }
        manager.doOperation(Main::dstPath, Main::destName, entry->operCode, Main::instanceFilter, Main::listSettings);
    }

    return true;
}

} // anonymous namespace

// Oversee parsing and handling of launch arguments
int main(int, const char * argv[]) // NOLINT(bugprone-exception-escape)
{
    // Set cout to use our custom locale
    locale comma_locale(locale(), new comma_numpunct());
    cout.imbue(comma_locale);
    locale::global(comma_locale);

    // Install word-wrap buffers on cout and cerr when output is to a terminal (not redirected to a file or pipe)
    WordWrapBuf wrapBufOut(cout.rdbuf());
    WordWrapBuf wrapBufErr(cerr.rdbuf());
#if MAC
    if (isatty(STDOUT_FILENO))
        cout.rdbuf(&wrapBufOut);
    if (isatty(STDERR_FILENO))
        cerr.rdbuf(&wrapBufErr);
#elif WIN
    if (_isatty(_fileno(stdout)))
        cout.rdbuf(&wrapBufOut);
    if (_isatty(_fileno(stderr)))
        cerr.rdbuf(&wrapBufErr);
#endif

    // Save arguments in memory and determine our run mode
    if (not ProcessArgumentsAndSetMode(argv))
        return 1;

    // Load the alias file if one was supplied; this populates Main::aliases for use in all modes
    if (not LoadAliasFiles())
        return 1;

    // Set up the tasks we'll perform
    vector<function<bool()>> pipeline =
    {
        PrintHeader,
        ProcessAliasArguments,
        CheckForDuplicateOptions,
        ValidateCompanionArguments,
        ProcessFilterArguments,
        ProcessListSettings,
        ProcessDisplayScaleArgument,
        ProcessOverwritePolicyArgument,
        ProcessSanitizePolicyArgument,
        ProcessOptionsAndValues,
        ValidateTaskRequirements,
        HandleTask
    };

    // Batch mode leads with a different task
    if (Main::mode == RunMode::Batch)
        pipeline[0] = UnifySplitValues;

    // Perform requested tasks according to Kanabo's run mode
    if (Main::mode == RunMode::CLI)
    {
        // A single runthrough of all tasks
        for (auto & task : pipeline)
        {
            if (not task())
                return 1;
        }
    }
    else if (Main::mode == RunMode::Batch)
    {
        // Load the batch file that was passed in with the batch argument and run each line as if it's a separate invocation of the program
        DiskItem batchFile(Main::batchPath, ReadingMode::Text, ReportingMode::ErrorsOnly);
        Main::arguments.clear(); // arguments from the outer invocation are no longer needed
        if (batchFile.opened())
        {
            string command{};
            while (batchFile.nextLine(command))
            {
                if (command.empty() || command.front() == '#')
                    continue;

                // If there are contents in "arguments", we've executed at least one command line before this, so print a divider line and
                // re-init globals
                if (not Main::arguments.empty())
                {
                    cout << "--------------------------------\n";
                    InitMain();
                }

                // Construct invocation from line of batch file
                istringstream iss(command);
                string token;
                while (iss >> token) // iterate over terms separated by whitespace
                    Main::arguments.push_back(token);

                // Run our task pipeline on this command
                for (auto & task : pipeline)
                {
                    if (not task())
                        return 1;
                }
            }
        }
        else
        {
            cerr << "Error: Failed to open batch file for processing.\n";
            return 1;
        }
    }
    else // Main::mode == RunMode::GUI
        return 1; // there's no GUI yet!
    
    return 0;
}