argz.hpp File Reference

Lightweight, header-only, template command-line argument parser. More...

#include "mxvk_runtime_options.hpp"
#include <algorithm>
#include <cctype>
#include <charconv>
#include <cmath>
#include <cstddef>
#include <cstdio>
#include <cstdlib>
#include <filesystem>
#include <iomanip>
#include <iostream>
#include <iterator>
#include <ranges>
#include <string>
#include <string_view>
#include <system_error>
#include <type_traits>
#include <unordered_map>
#include <utility>
#include <vector>
#include <unistd.h>

Go to the source code of this file.

Classes
class	ArgException< String >
	Exception thrown by Argz::proc() on unrecognised or malformed options. More...
struct	Argument< String >
	Describes a single parsed argument entry returned by Argz::proc(). More...
struct	ArgumentData< String >
	Holds the raw argv strings converted to the target String type. More...
struct	Arguments
	Plain data structure returned by proc_args() with all common libmx2 CLI options. More...
class	Argz< String >
	Template command-line argument parser. More...
struct	FramebufferDimensions
	Parsed software framebuffer dimensions. More...

Concepts
concept	StringType
	Models a string-like class with indexing, concatenation, length, and value_type.

Enumerations
enum class	ArgType {   ARG_SINGLE , ARG_SINGLE_VALUE , ARG_DOUBLE , ARG_DOUBLE_VALUE ,   ARG_NONE }
	Discriminator for option kind used inside Argument. More...

Functions
std::string	executable_directory (const char *executable)
double	parse_arg_double (const std::string &text, const std::string &option_name)
int	parse_arg_int (const std::string &text, const std::string &option_name)
std::string	parse_executable_name (const char *argv0)
Arguments	proc_args (int &argc, char **argv)
	Parse standard libmx2 command-line options from main()'s argv.

Detailed Description

Lightweight, header-only, template command-line argument parser.

Supports both short options (-x) and long options (--name), with or without values, for any string type that satisfies the StringType concept (typically std::string or std::wstring).

Typical usage:

Argz<std::string> parser(argc, argv);
parser.addOptionSingle('h', "Show help")
      .addOptionSingleValue('o', "Output file");
Argument<std::string> arg;
int code;
while ((code = parser.proc(arg)) != -1) { ... }

A convenience wrapper proc_args() provides a pre-built parser that handles the options common to all libmx2 applications (-p path, -r resolution, -f fullscreen, …).

Definition in file argz.hpp.

Enumeration Type Documentation

ArgType

enum class ArgType

strong

Discriminator for option kind used inside Argument.

Enumerator
ARG_SINGLE
ARG_SINGLE_VALUE
ARG_DOUBLE
ARG_DOUBLE_VALUE
ARG_NONE

Definition at line 102 of file argz.hpp.

                   {
    ARG_SINGLE,
    ARG_SINGLE_VALUE,
    ARG_DOUBLE,
    ARG_DOUBLE_VALUE,
    ARG_NONE
};

Function Documentation

executable_directory()

std::string executable_directory ( const char * executable )

inlinenodiscard

Definition at line 78 of file argz.hpp.

                                                                            {
#if defined(_WIN32)
    std::vector<char> buffer(32768);
    const DWORD length = GetModuleFileNameA(nullptr, buffer.data(), static_cast<DWORD>(buffer.size()));
    if (length > 0 && length < buffer.size()) {
        return std::filesystem::path(std::string(buffer.data(), length)).parent_path().lexically_normal().string();
    }
#elif defined(__linux__)
    std::vector<char> buffer(4096);
    const ssize_t length = readlink("/proc/self/exe", buffer.data(), buffer.size());
    if (length > 0 && static_cast<std::size_t>(length) < buffer.size()) {
        return std::filesystem::path(std::string(buffer.data(), static_cast<std::size_t>(length))).parent_path().lexically_normal().string();
    }
#endif
 
    std::error_code error;
    const std::filesystem::path absolute_path = std::filesystem::absolute(executable == nullptr ? "." : executable, error);
    if (!error && absolute_path.has_parent_path()) {
        return absolute_path.parent_path().lexically_normal().string();
    }
    return ".";
}

parse_arg_double()

double parse_arg_double ( const std::string & text, const std::string & option_name )

inlinenodiscard

Definition at line 785 of file argz.hpp.

                                                                                                  {
    double value = 0.0;
    const char *begin = text.data();
    const char *end = begin + text.size();
    const std::from_chars_result result = std::from_chars(begin, end, value);
    if (result.ec != std::errc{} || result.ptr != end || !std::isfinite(value)) {
        throw ArgException<std::string>("Invalid numeric value for " + option_name + ": " + text);
    }
    return value;
}

parse_arg_int()

int parse_arg_int ( const std::string & text, const std::string & option_name )

inlinenodiscard

Definition at line 774 of file argz.hpp.

                                                                                            {
    int value = 0;
    const char *begin = text.data();
    const char *end = begin + text.size();
    const std::from_chars_result result = std::from_chars(begin, end, value);
    if (result.ec != std::errc{} || result.ptr != end) {
        throw ArgException<std::string>("Invalid numeric value for " + option_name + ": " + text);
    }
    return value;
}

parse_executable_name()

std::string parse_executable_name ( const char * argv0 )

inlinenodiscard

Definition at line 796 of file argz.hpp.

                                                                        {
    if (argv0 == nullptr || argv0[0] == '\0') {
        return "mxvk";
    }
 
    std::string name = argv0;
    const std::string::size_type separator = name.find_last_of("/\\");
    if (separator != std::string::npos) {
        name.erase(0, separator + 1);
    }
 
    constexpr std::string_view exe_extension = ".exe";
    if (name.size() >= exe_extension.size()) {
        const std::string::size_type extension_pos = name.size() - exe_extension.size();
        const bool has_exe_extension = std::ranges::equal(name.begin() + static_cast<std::ptrdiff_t>(extension_pos),
                                                          name.end(),
                                                          exe_extension.begin(),
                                                          exe_extension.end(),
                                                          [](char left, char right) {
                                                              return std::tolower(static_cast<unsigned char>(left)) == std::tolower(static_cast<unsigned char>(right));
                                                          });
        if (has_exe_extension) {
            name.erase(extension_pos);
        }
    }
 
    return name.empty() ? "mxvk" : name;
}

proc_args()

Arguments proc_args ( int & argc, char ** argv )

inline

Parse standard libmx2 command-line options from main()'s argv.

Registers and processes the following options:

Flag	Long form	Description
-h		Print help and exit
-p	–path	Asset directory path
-r	–resolution	Resolution as WxH (e.g. 1920x1080)
-f	–fullscreen	Enable fullscreen
	–fast	Enable fast mode
	–filename	Input filename
	–model	Model filename
-o	–output	Output filename
-c	–crf	Constant Rate Factor
	–encode-preset	Encoder preset
	–encode-tune	Encoder tune
	–encode-codec	Encoder codec policy or name
	–encode-realtime	Enable realtime/low-latency encoding
	–mxwrite-block	Block MXWrite when its queue is full
	–repeat	Enable playback or texture repetition
	–binary	Use binary glyphs only
	–enable-crt	Enable CRT post-processing at startup
	–enable-vsync	Enable FIFO present mode / v-sync
	–enable-screenshot	Enable F10 screenshot capture
	–disable-sound	Disable application background music
	–benchmark	Enable application benchmark mode
	–wireframe	Render supported 3D models as wireframes
	–nowarpfix	Disable perspective-correct texture mapping
	–disable-mipmap	Disable mipmap generation and selection
	–mip-bias	Mipmap level-of-detail bias
	–framebuffer	Software framebuffer size as WxH
	–fps	Override capture FPS
-z	–font-size	Matrix rain font size
-j	–font-path	Matrix rain font file path
-C	–color	Matrix rain RGB tint (#RRGGBB or R,G,B)
	–texture	Texture file
	–textures	Texture file alias
-S	–shader-path	SPV shader folder (must contain index.txt)
	–fragment	Fragment shader SPV path
-i	–index	Acidcam filter mode index
	–shader-index	Initial shader entry index

Parameters

argc	Reference to argc from main().
argv	argv from main().

Returns

Populated Arguments struct; on parse error, returns a default-valued struct.

Definition at line 872 of file argz.hpp.

                                                   {
    Arguments args;
    const std::string executable_name = parse_executable_name(argc > 0 ? argv[0] : nullptr);
    Argz<std::string> parser(argc, argv);
    parser.addOptionSingle('h', "Display help message")
        .addOptionSingle('v', "Print version")
        .addOptionSingleValue('p', "assets path")
        .addOptionDoubleValue('P', "path", "assets path")
        .addOptionSingleValue('r', "Resolution WidthxHeight")
        .addOptionDoubleValue('R', "resolution", "Resolution WidthxHeight")
        .addOptionSingle('f', "fullscreen")
        .addOptionDouble('F', "fullscreen", "fullscreen")
        .addOptionDouble(301, "fast", "fast")
        .addOptionDoubleValue(256, "filename", "input filename")
        .addOptionDoubleValue(324, "model", "model filename (.obj, .mxmod, or .mxmod.z)")
        .addOptionSingleValue('o', "output filename")
        .addOptionDoubleValue(304, "output", "output filename")
        .addOptionSingleValue('c', "crf value")
        .addOptionDoubleValue(305, "crf", "crf value")
        .addOptionDoubleValue(306, "encode-preset", "encoder preset")
        .addOptionDoubleValue(307, "encode-tune", "encoder tune")
        .addOptionDoubleValue(308, "encode-codec", "encoder codec policy or name")
        .addOptionDouble(309, "encode-realtime", "encoder realtime mode")
        .addOptionDouble(314, "mxwrite-block", "block MXWrite when its queue is full")
        .addOptionDouble(310, "repeat", "repeat playback or wrapped textures")
        .addOptionDouble(315, "binary", "use binary glyphs only")
        .addOptionDouble(319, "enable-crt", "enable CRT post-processing at startup")
        .addOptionDouble(320, "enable-vsync", "enable FIFO present mode / v-sync")
        .addOptionDouble(322, "enable-screenshot", "enable F10 screenshot capture")
        .addOptionDouble(325, "disable-sound", "disable background music")
        .addOptionDouble(330, "benchmark", "enable application benchmark mode")
        .addOptionDouble(331, "wireframe", "render supported 3D models as wireframes")
        .addOptionDouble(326, "nowarpfix", "3dmath - disable perspective-correct texture mapping")
        .addOptionDoubleValue(327, "framebuffer", "3dmath - software framebuffer size WidthxHeight")
        .addOptionDouble(328, "disable-mipmap", "3dmath - disable mipmap generation and selection")
        .addOptionDoubleValue(329, "mip-bias", "3dmath - mipmap level-of-detail bias (-16 to 16)")
        .addOptionDoubleValue(321, "fps", "capture FPS override")
        .addOptionSingleValue('z', "matrix rain font size")
        .addOptionDoubleValue(316, "font-size", "matrix rain font size")
        .addOptionSingleValue('j', "matrix rain font file path")
        .addOptionDoubleValue(317, "font-path", "matrix rain font file path")
        .addOptionSingleValue('C', "matrix rain RGB tint (#RRGGBB or R,G,B)")
        .addOptionDoubleValue(318, "color", "matrix rain RGB tint (#RRGGBB or R,G,B)")
        .addOptionDoubleValue(302, "resource", "resource file")
        .addOptionDoubleValue(303, "resource_path", "resource data path")
        .addOptionDoubleValue(257, "texture", "texture file (.png or .tex)")
        .addOptionDoubleValue(323, "textures", "texture file (.png or .tex)")
        .addOptionSingleValue('S', "shader SPV folder path (contains index.txt)")
        .addOptionDoubleValue(258, "shader-path", "shader SPV folder path (contains index.txt)")
        .addOptionDoubleValue(313, "fragment", "fragment shader SPV path")
        .addOptionSingleValue('i', "acidcam filter mode index")
        .addOptionDoubleValue(311, "index", "acidcam filter mode index")
        .addOptionDoubleValue(312, "shader-index", "initial shader entry index")
        .addOptionDoubleValue(300, "camera", "camera index");
 
    Argument<std::string> arg;
    std::string path;
    int value = 0;
    int tw = 1280, th = 720;
    bool fullscreen = false;
    bool fast = false;
    bool resolutionSpecified = false;
    std::string filename;
    std::string model;
    std::string output;
    std::string crf;
    std::string encodePreset;
    std::string encodeTune;
    std::string encodeCodec;
    bool encodeRealtime = false;
    bool mxwriteBlockWhenFull = false;
    bool repeat = false;
    bool binary = false;
    bool enable_crt = false;
    bool enable_vsync = false;
    bool enable_screenshot = false;
    bool disable_sound = false;
    bool benchmark = false;
    bool wireframe = false;
    bool nowarpfix = false;
    bool disable_mipmap = false;
    float mip_bias = 0.0f;
    FramebufferDimensions framebuffer;
    bool framebufferSpecified = false;
    double fps = 0.0;
    int font_size = 22;
    std::string font_path;
    std::string color;
    std::string texture;
    std::string shaderPath;
    std::string fragmentPath;
    int camera_index = 0;
    int index = 0;
    int shader_index = 0;
    std::string resource;
    std::string resource_path;
    while ((value = parser.proc(arg)) != -1) {
        switch (value) {
        case 303:
            resource_path = arg.arg_value;
            break;
        case 302:
            resource = arg.arg_value;
            break;
        case 256:
            filename = arg.arg_value;
            break;
        case 324:
            model = arg.arg_value;
            break;
        case 'o':
        case 304:
            output = arg.arg_value;
            break;
        case 'c':
        case 305:
            crf = arg.arg_value;
            break;
        case 306:
            encodePreset = arg.arg_value;
            break;
        case 307:
            encodeTune = arg.arg_value;
            break;
        case 308:
            encodeCodec = arg.arg_value;
            break;
        case 309:
            encodeRealtime = true;
            break;
        case 314:
            mxwriteBlockWhenFull = true;
            break;
        case 310:
            repeat = true;
            break;
        case 315:
            binary = true;
            break;
        case 319:
            enable_crt = true;
            break;
        case 320:
            enable_vsync = true;
            break;
        case 322:
            enable_screenshot = true;
            break;
        case 325:
            disable_sound = true;
            break;
        case 330:
            benchmark = true;
            break;
        case 331:
            wireframe = true;
            break;
        case 326:
            nowarpfix = true;
            break;
        case 327: {
            const std::string::size_type separator = arg.arg_value.find('x');
            if (separator == std::string::npos) {
                throw ArgException<std::string>("Invalid framebuffer size, expected WidthxHeight: " + arg.arg_value);
            }
            framebuffer.width = parse_arg_int(arg.arg_value.substr(0, separator), "--framebuffer width");
            framebuffer.height = parse_arg_int(arg.arg_value.substr(separator + 1), "--framebuffer height");
            if (framebuffer.width <= 0 || framebuffer.height <= 0) {
                throw ArgException<std::string>("Invalid framebuffer size: " + arg.arg_value);
            }
            framebufferSpecified = true;
        } break;
        case 328:
            disable_mipmap = true;
            break;
        case 329: {
            const double parsed_mip_bias = parse_arg_double(arg.arg_value, "--mip-bias");
            if (parsed_mip_bias < -16.0 || parsed_mip_bias > 16.0) {
                throw ArgException<std::string>("Mip bias must be between -16 and 16: " + arg.arg_value);
            }
            mip_bias = static_cast<float>(parsed_mip_bias);
        } break;
        case 321:
            fps = parse_arg_double(arg.arg_value, "--fps");
            if (fps <= 0.0) {
                throw ArgException<std::string>("Invalid numeric value for --fps: " + arg.arg_value);
            }
            break;
        case 'z':
        case 316:
            font_size = parse_arg_int(arg.arg_value, "--font-size");
            if (font_size <= 0) {
                throw ArgException<std::string>("Invalid numeric value for --font-size: " + arg.arg_value);
            }
            break;
        case 'j':
        case 317:
            font_path = arg.arg_value;
            break;
        case 'C':
        case 318:
            color = arg.arg_value;
            break;
        case 257:
        case 323:
            texture = arg.arg_value;
            break;
        case 'S':
        case 258:
            shaderPath = arg.arg_value;
            break;
        case 313:
            fragmentPath = arg.arg_value;
            break;
        case 'h':
        case 'v':
            parser.help(std::cout);
            exit(EXIT_SUCCESS);
            break;
        case 'p':
        case 'P':
            path = arg.arg_value;
            break;
        case 'r':
        case 'R': {
            auto pos = arg.arg_value.find("x");
            if (pos == std::string::npos) {
                throw ArgException<std::string>("Invalid resolution for --resolution, expected WidthxHeight: " + arg.arg_value);
            }
            std::string left, right;
            left = arg.arg_value.substr(0, pos);
            right = arg.arg_value.substr(pos + 1);
            tw = parse_arg_int(left, "--resolution width");
            th = parse_arg_int(right, "--resolution height");
            if (tw <= 0 || th <= 0) {
                throw ArgException<std::string>("Invalid numeric value for --resolution: " + arg.arg_value);
            }
            resolutionSpecified = true;
        } break;
        case 'f':
        case 'F':
            fullscreen = true;
            break;
        case 301:
            fast = true;
            break;
        case 300:
            camera_index = parse_arg_int(arg.arg_value, "--camera");
            break;
        case 'i':
        case 311:
            index = parse_arg_int(arg.arg_value, "--index");
            break;
        case 312:
            shader_index = parse_arg_int(arg.arg_value, "--shader-index");
            break;
        }
    }
    if (path.empty()) {
        path = executable_directory(argc > 0 ? argv[0] : nullptr);
        std::cerr << "mx: No path provided; using executable directory: " << path << '\n';
    } else {
        std::error_code error;
        const std::filesystem::path absolute_path = std::filesystem::absolute(path, error);
        if (!error) {
            path = absolute_path.lexically_normal().string();
        }
    }
    args.executable_name = executable_name;
    mxvk::setDefaultExecutableName(executable_name);
    args.width = tw;
    args.height = th;
    args.resolutionSpecified = resolutionSpecified;
    args.path = path;
    args.fullscreen = fullscreen;
    args.fast = fast;
    args.filename = filename;
    args.model = model;
    args.output = output;
    args.crf = crf;
    args.encodePreset = encodePreset;
    args.encodeTune = encodeTune;
    args.encodeCodec = encodeCodec;
    args.encodeRealtime = encodeRealtime;
    args.mxwriteBlockWhenFull = mxwriteBlockWhenFull;
    args.repeat = repeat;
    args.binary = binary;
    args.enable_crt = enable_crt;
    args.enable_vsync = enable_vsync;
    args.enable_screenshot = enable_screenshot;
    args.disable_sound = disable_sound;
    args.benchmark = benchmark;
    args.wireframe = wireframe;
    args.nowarpfix = nowarpfix;
    args.disable_mipmap = disable_mipmap;
    args.mip_bias = mip_bias;
    args.framebuffer = framebuffer;
    args.framebufferSpecified = framebufferSpecified;
    mxvk::setDefaultEnableScreenshot(enable_screenshot);
    args.fps = fps;
    args.font_size = font_size;
    args.font_path = font_path;
    args.color = color;
    args.texture = texture;
    args.shaderPath = shaderPath;
    args.fragmentPath = fragmentPath;
    args.camera_index = camera_index;
    args.index = index;
    args.shader_index = shader_index;
    args.resource = resource;
    args.resource_path = resource_path;
    return args;
}