Faulty docs for Mojo::Log's format() sub prototype

[ronsavage]

• Mojolicious version: 9.38
• Perl version: 5.40.0
• Operating system: Debian 6.1.99-1 (2024-07-15) x86_64 GNU/Linux

Steps to reproduce the behavior

Browse the docs for Mojo::Log at https://metacpan.org/pod/Mojo::Log.
Click on 'format' in the Contents column on the right
Examine this line of POD:
$log->format(sub ($time, $level, @lines) { "[2018-11-08 14:20:13.77168] [28320] [info] I ♥ Mojolicious\n" });

My code uses:
use strict;
use warnings;

And later:
$logger -> format(sub ($time, $level, @lines) {"Level: <$_[1]>. Msg: <$_[2]>\n"});

Expected behavior

Perl should not report any errors.

Actual behavior

I get these Perl error messages:
Prototype after '@' for ? : $time, $level, @lines at scripts/x.pl line 184.
Illegal character in prototype for ? : $time, $level, @lines at scripts/x.pl line 184.

Solution

I found that by changing the code thusly, the errors no longer appear:
$logger -> format(sub (@) {"Level: <$_[1]>. Msg: <$_[2]>\n"});

[Grinnz]

Mojolicious docs assume the signatures feature is enabled. See https://metacpan.org/pod/Mojolicious::Guides::FAQ#What-does-%22Illegal-character-in-prototype%22-mean?

[ajmetz]

This is great an' all as regards getting ronsavage's example working, and the original point of faulty docs is still present - the example in the docs remains "[2018-11-08 14:20:13.77168] [28320] [info] I ♥ Mojolicious\n" rather than any example use of $level and $time.

[guest20]

@ajmetz I don't think that filling the example with calls to strftime / printf / join is going to make the example clearer

[ajmetz]

I assumed the current "I ♥ Mojolicious", etc, was a typo / oversight.
To be clear - I mean the example at: https://metacpan.org/pod/Mojo::Log#format - I believe it would be clearer if $time, $level and @lines were actually used.

[ajmetz]

Hm. Maybe { # do something with $time, $level, or @lines } would suffice. I was surprised by the static string, as it had a time in it, when it could have used $time. It had a level in it, when it could have used $level. That's a bit confusing.

[guest20]

@ajmetz it was perfectly clear what your meant.

You know that $level and $time are both numbers that need formatting and @lines needs to be joined or otherwise formatted?

Doing all those things in the example is going to make the example long and noisy and isn't going to clarify that you should put your own code into the callback or that you should use the arguments passed to the callback as part of doing that...

[ronsavage]

Grinnz: Thanx for the reply.
The Perl Signatures page says sigs are enabled 'by a use v5.36 (or higher) declaration'. I am using 5.40.0, but I had problems with sub($, $, @) and so gave up on that. Probably I did something wrong. And any way, with no var names in there, how are we meant to refer to the variables in the sub's block? IDN. I spent a long time reading the Perl docs on sigs, but exited not much wiser. Sigh. It works now, so I will just leave the code as is....

[Grinnz]

You need either a "use v5.36 (or higher) declaration" or to pass the -signatures argument to Mojo::Base or Mojolicious::Lite. That is the only way they will be enabled.

[Grinnz]

I'm not sure what you mean by no var names. The signatures, as shown in the examples, contain variable names.

[ronsavage]

Hi Dan Indeed they do. But I got Perl compile errors with names, so I used sigils. And then 1 sigil, and it worked. And I emphasize, the code says 'use 5.40.0;'. I doubt 'use v5.40.0;' (i.e. an extra 'v') would make a difference. I am perplexed.

…

On 2024-11-06 17:42, Dan wrote: I'm not sure what you mean by no var names. The signatures, as shown in the examples, contain variable names.

-- Cheers, Ron savage.net.au symboliciq.au

[Grinnz]

(@) is a valid prototype. ($, $, @) is a valid signature, but one where none of the variables are usable in the subroutine. If you got compilation errors with the latter but not the former, you did not enable signatures correctly.

[ronsavage]

Hi Dan I just used: use 5.40.0; use feature 'signatures'; and: $demo -> logger -> format(sub ($time, $level, @lines) {"Level: $level. Msg: $lines[0]\n"}); It worked with and without the 'use feature' line. Why did it fail before? IDN. But at least it's working. Thanx for your help.

…

On 2024-11-06 18:20, Dan wrote: (@) is a valid prototype. ($, $, @) is a valid signature, but one where none of the variables are usable in the subroutine. If you got compilation errors with the latter but not the former, you did not enable signatures correctly.

-- Cheers, Ron savage.net.au symboliciq.au