Str.match not documented / Str.subst does not list all options [some are inaccurate/incomplete]

[zoffixznet]

The Str.match method appears to undocumented. Moreover, Str.subst uses it for regex matching, and it appears that some of the options accepted by Str.match are not listed for Str.subst (some may be applicable on for Str.subst-mutate that returns Match objects).

Lastly, the :nth (and aliases) also take a Whatever while :x does not take a Callable, but does take Range or Whatever

[gfldex]

this depends on lizmats match overhaul. At least the return type may change depending adverbs.

[Altai-man]

Does lizmat plan to do any changes in this area now? Issue seems pretty old.

Str.match is documented at https://docs.perl6.org/routine/match, I'll update the input types on https://docs.perl6.org/routine/subst now.

[Altai-man]

@zoffixznet, can you look at match and subst descriptions? What else should be done to close this?

[zoffixznet]

Does lizmat plan to do any changes in this area now? Issue seems pretty old.

No, as I understand it, everything was finished off last year.

What else should be done to close this?

Briefly looking at this, I see the two original concerns are still valid:

Lastly, the :nth (and aliases) also take a Whatever while :x does not take a Callable, but does take Range or Whatever

And I spotted one more error: nth can also take a positively-incrementing list, e.g. :nth(1, 3, 7)

<Zoffix> m: say 'aaaa'.match: 'a', :x(1..2)
<camelia> rakudo-moar 266f34: OUTPUT«(｢a｣ ｢a｣)␤»
<Zoffix> m: say 'a'.match: 'a', :x(1..2)
<camelia> rakudo-moar 266f34: OUTPUT«(｢a｣)␤»
<Zoffix> m: say 'a'.match: 'a', :nth(*)
<camelia> rakudo-moar 266f34: OUTPUT«｢a｣␤»
<Zoffix> m: say '1 z 23 a b 5 c d'.match: /\d/, :nth(*)
<camelia> rakudo-moar 266f34: OUTPUT«｢5｣␤»
<Zoffix> m: say 'aaaa'.match: :x({4;})
<camelia> rakudo-moar 266f34: OUTPUT«Cannot resolve caller match(Str: :x(Block)); none of these signatures match:␤    (Any:U $: | is raw)␤    (Cool:D $: $target, *%adverbs)␤    (Str $: Cool:D $pattern, |c is raw)␤    (Str $: Regex:D $pattern, :continue(:$c)!, *%_)␤    (Str $: Regex:…

The second thing is it seems the accepted adverbs are scattered between regexes#Adverbs, match docs, and subst docs. For example subst and regex Adverbs docs don't seem to mention nth family of adverbs. The subst-mutate docs don't mention anything but :g, which on standalone routine page makes it look like it doesn't take any but :g.

But perhaps it makes more sense to document it all in just one place (in regexes#Adverbs). Most of the adverbs are the same in s///, S///, m///, .subst-mutate, .subst, and .match.

A few adverbs only make sense for matching (e.g. :ex and :ov), a few only for substitutions (e.g. :ss or :ii), and some must be stuffed inside the regex when using method forms instead of just using it as an adverb (e.g. :s or :i)

# Works
<Zoffix> m: say 'a b' ~~ m:s/a ./
<camelia> rakudo-moar 266f34: OUTPUT«｢a b｣␤»

# Doesn't
<Zoffix> m: say 'a b'.match: :s, /a ./
<camelia> rakudo-moar 266f34: OUTPUT«｢a ｣␤»

# Does, because it was moved into the regex.
<Zoffix> m: say 'a b'.match: /:s a ./
<camelia> rakudo-moar 266f34: OUTPUT«｢a b｣␤»

So to me it feels all of these can be neatly documented in one space and each include these three indicators (maybe an icon with alt="" text or more concise or clear explanation): can be used in matching; can be used in substituting; and can be used as an adverb in method form

[labster]

The page on .subst should mention .subst-mutate. And the Regexes page should mention both, though at least it does mention .match.