/**
 * @file args.h
 * @brief Collecting a verb's positional arguments, shared by the verb files.
 *
 * Every device verb group -- graphics, audio, and now sprites -- takes a short
 * positional list with optional trailing members, so every handler wants the
 * same two things: how many arguments arrived, and their numeric values. This
 * was written twice before it was written here. src/runtime_audio.c's copy
 * carried the rule for when to stop copying it:
 *
 *     "If a third group wants it, that is the point at which it earns a home of
 *      its own."
 *
 * Group H is the third group.
 */

#ifndef _AKBASIC_ARGS_H_
#define _AKBASIC_ARGS_H_

#include <akerror.h>

#include <akbasic/grammar.h>

struct akbasic_Runtime;

/**
 * @brief Collect a verb's arguments into an array, evaluating each one.
 *
 * Strings are refused here rather than in each verb. A verb that does take one
 * -- SSHAPE, GSHAPE, SPRSAV -- reads its leaf directly instead, because what it
 * wants from that argument is not a number and never was.
 *
 * @param obj Runtime to evaluate against.
 * @param expr The command leaf.
 * @param verb Name to use in a diagnostic; a verb that refuses has to say which.
 * @param values Where to put the evaluated arguments.
 * @param max Capacity of @p values.
 * @param count Output destination populated by the function.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_NULLPOINTER When any argument but `verb` is NULL.
 * @throws AKBASIC_ERR_SYNTAX When more than `max` arguments were given.
 * @throws AKBASIC_ERR_TYPE When an argument evaluated to a string.
 */
akerr_ErrorContext AKERR_NOIGNORE *akbasic_args_numbers(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, const char *verb, double *values, int max, int *count);

#endif // _AKBASIC_ARGS_H_
