-/* An argument list. If a function \foo expects scm scm pitch, then the lexer expands \foo into the token sequence:
- MUSIC_FUNCTION EXPECT_PITCH EXPECT_SCM EXPECT_SCM EXPECT_NO_MORE_ARGS
-and this rule returns the reversed list of arguments. */
-
-function_arglist_skip:
- function_arglist_common
- | EXPECT_OPTIONAL EXPECT_PITCH function_arglist_skip
- {
- $$ = scm_cons ($1, $3);
- } %prec FUNCTION_ARGLIST
- | EXPECT_OPTIONAL EXPECT_DURATION function_arglist_skip
- {
- $$ = scm_cons ($1, $3);
- } %prec FUNCTION_ARGLIST
- | EXPECT_OPTIONAL EXPECT_SCM function_arglist_skip
- {
- $$ = scm_cons ($1, $3);
- } %prec FUNCTION_ARGLIST
- ;
-
+/* Function argument lists are arguably the most complex part in the
+ * parser. They are pretty tricky to understand because of the way
+ * they are processed, and because of optional arguments that can be
+ * omitted. When there are several optional arguments in a row,
+ * omitting one automatically omits all following arguments. Optional
+ * arguments can only be omitted when either
+ *
+ * a) the omission is explicitly started with \default
+ * b) the omission is implicitly started by an argument not matching
+ * its predicate, and there is a mandatory argument later that can
+ * "catch" the argument that does not fit.
+ *
+ * When argument parsing starts, the lexer pushes EXPECT_SCM tokens
+ * (corresponding to mandatory arguments and having a predicate
+ * function as semantic value) or EXPECT_OPTIONAL EXPECT_SCM (where
+ * the semantic value of the EXPECT_OPTIONAL token is the default to
+ * use when the optional argument is omitted, and EXPECT_SCM again has
+ * the argument predicate as semantic value) in reverse order to the
+ * parser, followed by EXPECT_NO_MORE_ARGS. The argument list is then
+ * processed inside-out while actual tokens are consumed.
+ *
+ * This means that the argument list tokens determine the actions
+ * taken as they arrive. The structure of the argument list is known
+ * to the parser and stored in its parse stack when the first argument
+ * is being parsed. What the parser does not know is which predicates
+ * will match and whether or not \default will be appearing in the
+ * argument list, and where.
+ *
+ * Many of the basic nonterminals used for argument list scanning come
+ * in a "normal" and a "closed" flavor. A closed expression is one
+ * that can be parsed without a lookahead token. That makes it
+ * feasible for an optional argument that may need to be skipped:
+ * skipping can only be accomplished by pushing back the token into
+ * the lexer, and that only works when there is no lookahead token.
+ *
+ * Sequences of 0 or more optional arguments are scanned using either
+ * function_arglist_backup or function_arglist_nonbackup. The first
+ * is used when optional arguments are followed by at least one
+ * mandatory argument: in that case optional arguments may be skipped
+ * by either a false predicate (in which case the expression will be
+ * pushed back as one or more tokens, preceded by a BACKUP token) or
+ * by using \default.
+ *
+ * If optional arguments are at the end of the argument list, they are
+ * instead scanned using function_arglist_nonbackup: here the only
+ * manner to enter into skipping of optional arguments is the use of
+ * \default.
+ *
+ * The argument list of a normal function call is parsed using
+ * function_arglist. The part of an argument list before a mandatory
+ * argument is parsed using function_arglist_optional.
+ *
+ * The difference is that leading optional arguments are scanned using
+ * function_arglist_nonbackup and function_arglist_backup,
+ * respectively.
+ *
+ * Most other details are obvious in the rules themselves.
+ *
+ */