Goal

Last time I tried, but failed, to implement the shortcut directive. I failed, because I was trying to change many things at a time. One of the problems was that riki currently assumes parameters to directives are always named. That is not actually true for all directives, including shortcut.

My goal today is to change riki so that parameters can be named without a value, valued without a name, or be name/value pairs.

I’ll have succeded if riki can handle all the following forms, as far as parsing is concerned. I don’t care about actually implementing the directives yet.

• [[!foo bar]] - positional parameter, could be name or value
• [[!foo yo=yoyo]] - name/value parameter

The usual unquoted, quoted, or triple quoted variants for positional parameters or values are expected. Parsing the variants is already implemented.

Plan

• Write down a detailed prose specification of how parameters should work. Add it to doci/directifes.md.
• Start implementing the specification, first in the wikitext parser.

Notes

Specification

• At wikitext parsing time, name/value pairs are easy to recognize unambiguously.

• A quoted value without a name can also be distinguished.

• However, if a parameter that is only a name or an unquoted value, the parser doesn’t know which it is. The directive implementation needs to do that.

• There are thus three cases:

• a name/value pair

• a quoted value

• a name or unquoted value

• Wrote that up in doc/directives.md in informal prose.

Wikitext parser

• The current struct Parameter type assumes each parameter has a name. It does not allow for positional parameters. This is the cause of all the pain in this area.

• I will change that to be an enum with variants for name/value pairs and positional parameters. The wikitext parser needs to be changed too, to allow for quoted or triple quoted values without names as parameters. And the directive module needs to be changed for the new enum.

• This is too many changes at once. I’ll do the minimum, which is change the parameter type into an enum, but not the parser. I’ll gut the directive module parameter handling, for now. I’ll need to change all the directive stuff anyway for the parameter handling changes.

• That made things easier.

• Adding parsing of value-only parameters. Easy enough, but reminded that I still don’t have a good way to debug winnow parsers, except adding prints in opportune places.

• Most directives only have named parameters. They might not have values.

• Others will have only positional parameters, such as tag.

• For full generality, a directive needs to be able to iterate over the parameters, regardless of kind.

• but I’ll add this only once it’s needed

• The directive implementations need to easily check errors in parameters.

• I may later add a declarative way for directives to specify what parameters they support, but for now I’ll stick with repetitive code.

• I may want to later distinguish between unnamed quoted and unquoted values. For now, the quoted value is treated as if it were a name.

Summary

Making one change at a time sure does make things easier. Merged.