Class ScriptArgs

common/script/scriptargs.hpp:63–141

A checked view over picoc's (Param, NumArgs) argument array. Every native binding receives its arguments the same way — an array of struct Value*, each one's payload reached through ->Val->Integer or ->Val->Pointer. Spelling that out per binding meant ~60 unchecked casts: a script passing NULL where a char* was expected, or a count that does not match the array beside it, dereferenced straight th

// strArray/intArray take that count and the binding must have obtained it from
// count(), which is what rejects the absurd values.
class ScriptArgs {
public:
    // Upper bound on any element count a script passes in. Nothing legitimate
    // comes close — a pick list is tens of entries, the largest bundled script
    // builds a few thousand — while an uninitialised or miscomputed count is
    // usually huge or negative. The point is to fail loudly at the boundary
    // instead of walking off the end of the array.
    static constexpr int kMaxListItems = 65536;

    // `binding` is the script-visible name (the one in library_checkpoint.c's
    // table, not the ckpt_ symbol): it is what the user sees in the message and
    // what they can search for in the API header.
    ScriptArgs(struct ParseState* parser, struct Value** param, int numArgs, const char* binding)
        : mParser(parser), mParam(param), mNumArgs(numArgs), mBinding(binding)
    {
    }

    /* ---- integers ------------------------------------------------------ */

    int num(int i) const;
    // Fails with both bounds in the message, so the script author is told the
    // contract rather than just that they broke it.
    int numInRange(int i, int min, int max) const;
    // A byte count: non-negative, widened once here so no binding has to cast a
    // signed script int to size_t itself.
    size_t byteCount(int i) const;
    // An element count for the array argument beside it: non-negative and below
    // kMaxListItems.
    int count(int i) const;

    /* ---- strings ------------------------------------------------------- */

    // A NUL-terminated string argument. NULL fails the run.
    const char* str(int i) const;
    // Same, but NULL reads as `fallback` — for text a script may legitimately
    // omit (a progress label).
    const char* strOr(int i, const char* fallback) const;

    /* ---- pointers ------------------------------------------------------ */

    void* ptr(int i) const;
    void* ptrOrNull(int i) const;

    // Out parameters, by what the binding stores through them.
    char** outStr(int i) const;
    // For an out parameter a script is allowed to skip by passing NULL.
    char** outStrOrNull(int i) const;
    int* outInt(int i) const;
    // A caller-supplied char buffer of `size` bytes, terminator included.
    // `size` must come from a numInRange/num on the argument that carries it.
    char* outBuf(int i, int size) const;

    /* ---- arrays -------------------------------------------------------- */

    // `count` elements, none of them NULL: the check the pick-list bindings
    // used to skip before indexing straight into the array.
    char* const* strArray(int i, int count) const;
    int* intArray(int i, int count) const;