lichtkind

There are signatures in Raku, core Perl 5, Moose, Dios and lot of other modules. With KBOS I tried to find out how optimal signatures would look like to me. My objectives are: 3. easy to parse with the eye, 2. concise syntax and 1. delegates as much work as possible into the background so I have to write the least amount of code.

Basic Mechanics

Surely KBOS signatures are written inside round braces. When Keyword::Simple detects a KBOS method keyword, I replace the round braces with quotes, so the entire signature arrives as a string parameter in the class factory, where it can be parsed further. That gives me a great deal of freedom over the syntax and I'm not bound by any syntax rule of Perl 5. But in interest of speed there are some very simple syntax rules of KBOS, that also help users to get their content fast.

Three Parts

The parameter are separated by comma - everything else would be weird. Space would not work anyway, because some parameters are sometimes typed and sometimes the types have even multi word definitions - you could not tell what is what if we would just rely on spaces. But beside the necessary comma there are two other separators: '-' and '-->'. the ladder I took straight out of Raku and it visually suggests that is followed by the return type. I just sleep better when I can rely on the data type a method returns - plus it belongs logically to the kind of tasks a signature is delegating (what goes into a method, and what out).

Most controversial is probably the '-' separator. Optically I found it fitting, since you use it also in English sentences as a separator and the '-' is also contained in '-->' so your already watching out for this character in your first look at a KBOS signature. '-' divides the required from the optional parameter. The question what is optional is to me too important as to hide it with a postfix '?' as Raku does. KBOS signatures potentially contain more special character than a Raku signature so I had to do a little extra to make it stick out.

If you use method arguments as positionals, the optional args will take up the right part of the signature anyway. And it immediately helps me to understand the character of a method, when I see at the first glance what is the ration between optional and required, what do I have to provide and what are the extras.

Character Management

To help to make '-->', '-' and ',' stick out these characters can not be used anywhere else in a signature. Parameter names and types can only contain word characters. And only type shortcuts can contain special character, except the separator only chars. The type shortcuts are taken basically from Perl: $ & @ % and Raku: ~ + ? but i added several more as to me seen it Kephra::Base::Data::Type. You can also combine them. For instance is @+ shortcut for an Array that contains only numbers as elements.

Type Management

But the shortcuts are mostly for the usual default types. The less common types I typically
write as a word into the signature:

(str_uc label, int time - ? extra_space --> message_type )

But writing the type before the 'variable name' is common practice since C so there is also nothing to see, move along. What is more special are the last time mentioned relative types. Given my class has an attribute of type ARRAY named books. And now I want to write a method called demand with one parameter which should be a valid index which book the caller selects. In KBOS I could write

method demand (index of books book) { ....

Only if parameter book receives a valid integer, the method will be even run. Relative types can relate to arguments and other parameter that are on the left hand side of the current parameter (to prevent circular dependencies). Of course you can define in the call your own relative types.

Call Management
As you might expect, KBOS watches, if all required parameter receive a value. That is a hard constraint for a method body call. What you might not expect, is that KBOS allows you to call all method parameter by name. That is nothing fancy, just pass an HASH as the only argument. Nonetheless all values in there will be type checked as if it were a positional call and the required parameter have to be also present also.

Inside the method you get you parameter values the same way as $self. Its is simple the second positional inside @_. That way you keep full control over variable naming and nothing is happening behind you back. Plus you get the parameter value via methods a la .... = $args->prametername(); which keeps the arguments read only.

Next time I write about the five types of methods KBOS implements.